From 3763f9e4ef4e089180fe54d38d52db7bc51ac619 Mon Sep 17 00:00:00 2001 From: Elizabeth Mattijsen Date: Thu, 9 Apr 2020 13:45:02 +0200 Subject: [PATCH] Change most prominent uses of Perl 6 to Raku --- META6.json | 2 +- README.md | 82 ++++++++++++++++++++++---------------------- lib/Inline/Perl5.pm6 | 6 ++-- notes.txt | 24 ++++++------- t/call.t | 8 ++--- t/call_back.t | 10 +++--- t/inherit.t | 12 +++---- 7 files changed, 72 insertions(+), 72 deletions(-) diff --git a/META6.json b/META6.json index 53166ae..9a5c9d5 100644 --- a/META6.json +++ b/META6.json @@ -5,7 +5,7 @@ "perl" : "6.c", "auth" : "github:niner", "authors" : [ "Stefan Seifert" ], - "description" : "Use Perl 5 code in a Perl 6 program", + "description" : "Use Perl 5 code in a Raku program", "depends" : { "build": { "requires": [ diff --git a/README.md b/README.md index 5c80b3e..a4252e0 100644 --- a/README.md +++ b/README.md @@ -17,13 +17,13 @@ Inline::Perl5 # DESCRIPTION -Module for executing Perl 5 code and accessing Perl 5 modules from Perl 6. +Module for executing Perl 5 code and accessing Perl 5 modules from Raku. Supports Perl 5 modules including XS modules. Allows passing integers, strings, arrays, hashes, code references, file handles and objects between -Perl 5 and Perl 6. Also supports calling methods on Perl 5 objects from -Perl 6 and calling methods on Perl 6 objects from Perl 5 and subclass -Perl 5 classes in Perl 6. +Perl 5 and Raku. Also supports calling methods on Perl 5 objects from +Raku and calling methods on Raku objects from Perl 5 and subclass +Perl 5 classes in Raku. # HOW DO I? @@ -37,7 +37,7 @@ automatically load Inline::Perl5 as long as it is installed: use Test::More:from; ``` -In Perl 6 the :ver adverb is used for requiring a minimum version of a loaded +In Raku the :ver adverb is used for requiring a minimum version of a loaded module: ``` @@ -74,12 +74,12 @@ Just list the functions or groups you want to import ## Call a Perl 5 function Inline::Perl5 creates wrappers for loaded Perl 5 modules and their functions. -They can be used as if they were Perl 6 modules: +They can be used as if they were Raku modules: ``` use Test::More:from; plan tests => 1; - ok 'yes', 'looks like a Perl 6 function'; + ok 'yes', 'looks like a Raku function'; ``` In this example, the `plan` function exported by `Test::More` is called. @@ -96,7 +96,7 @@ is not in the "main" namespace. $p5.call('Test::More::plan', tests => 1); ``` -Please note that since Perl 6 does not have the same concept of "context", +Please note that since Raku does not have the same concept of "context", Perl 5 functions are by default called in list context. See "Invoking a method in scalar context" for how to get around that. @@ -120,13 +120,13 @@ Or using the low level methods: my $dumper = $p5.invoke('Data::Dumper', 'new'); ``` -Please note that since Perl 6 does not have the same concept of "context", +Please note that since Raku does not have the same concept of "context", Perl 5 methods are by default called in list context. See "Invoking a method in scalar context" for how to get around that. ## Invoke a method on a Perl 5 object -Once you have a Perl 5 object in a variable it will behave just like a Perl 6 +Once you have a Perl 5 object in a variable it will behave just like a Raku object. You can call methods on it like on any other object. ``` @@ -138,7 +138,7 @@ object. You can call methods on it like on any other object. ### Invoking a method in scalar context -Please note that since Perl 6 does not have the same concept of "context", +Please note that since Raku does not have the same concept of "context", Perl 5 methods are by default called in list context. If you need to call the method in scalar context, you can tell it so explicitly, by passing the `Scalar` type object as first argument: @@ -158,7 +158,7 @@ performance in some cases. Most objects in Perl 5 are blessed hash references. Some of them don't even provide accessor methods but require you to just access the hash fields -directly. This works the same in Perl 6: +directly. This works the same in Raku: ``` use Foo:from; my $foo = Foo.new; @@ -167,7 +167,7 @@ directly. This works the same in Perl 6: ## Run arbitrary Perl 5 code -Perl6's EVAL function supports multiple languages, just like the "use" +Raku's EVAL function supports multiple languages, just like the "use" statement. It allows for execution of arbitrary Perl 5 code given as string: ``` @@ -191,10 +191,10 @@ method: Both "EVAL" and "run" return the value of the last statement in the EVAL'ed code. -## Call a Perl 6 function from Perl 5 +## Call a Raku function from Perl 5 Inline::Perl5 creates a Perl 5 package called "v6". This package contains -a "call" function which allows for calling Perl 6 functions from Perl 5, +a "call" function which allows for calling Raku functions from Perl 5, same as Inline::Perl5's "call" method. It takes the name of the function to call and passes on any additional arguments and returns the return value of the called Perl 5 function. @@ -204,7 +204,7 @@ of the called Perl 5 function. my $p5 = Inline::Perl5.new; our sub foo($str) { - say "Perl6 says hello to $str"; + say "Raku says hello to $str"; }; $p5.run(q:to/PERL5/); @@ -212,9 +212,9 @@ of the called Perl 5 function. PERL5 ``` -## Invoke a method on a Perl 6 object from Perl 5 +## Invoke a method on a Raku object from Perl 5 -Perl 6 objects passed to Perl 5 functions will behave just like any other +Raku objects passed to Perl 5 functions will behave just like any other objects in Perl 5, so you can invoke methods using the -> operator. ``` @@ -223,24 +223,24 @@ objects in Perl 5, so you can invoke methods using the -> operator. $p5.run(q' sub test { - my ($perl6) = @_; - $perl6->hello; + my ($raku) = @_; + $raku->hello; } '); class Foo { method hello { - say "Hello Perl 6"; + say "Hello Raku"; } } $p5.call('test', Foo.new); ``` -## Run arbitrary Perl 6 code from Perl 5 +## Run arbitrary Raku code from Perl 5 The "run" function in the automatically created "v6" package can be used to -execute arbitrary Perl 6 code from Perl 5. It returns the value of the last +execute arbitrary Raku code from Perl 5. It returns the value of the last evaluated expression in the executed code. ``` @@ -254,12 +254,12 @@ evaluated expression in the executed code. ## Inherit from a Perl 5 class -Inline::Perl5 creates a corresponding Perl 6 class for each Perl 5 module +Inline::Perl5 creates a corresponding Raku class for each Perl 5 module loaded via the use Foo:from or $p5.use('Foo') mechanisms. You can subclass these automatically created classes as if they were original -Perl 6 classes: +Raku classes: ``` use Data::Dumper:from; @@ -298,7 +298,7 @@ object as named parameter to your classes constructor when creating objects. class Bar does Inline::Perl5::Perl5Parent['Foo'] { method bar { - return "Perl6"; + return "Raku"; } } @@ -309,37 +309,37 @@ object as named parameter to your classes constructor when creating objects. ## Pass a scalar reference to Perl 5 code -Simply pass a [`Capture`](https://docs.perl6.org/type/Capture) object containing +Simply pass a [`Capture`](https://docs.raku.org/type/Capture) object containing the object you want to pass as a reference: -```perl6 +```raku $p5obj.takes-a-scalar-ref-to-str: \("the string"); ``` -`HASH` and `ARRAY` references are made automatically if the Perl 6 objects +`HASH` and `ARRAY` references are made automatically if the Raku objects are [containerized](https://perl6advent.wordpress.com/2017/12/02/): -```perl6 +```raku $p5obj.takes-an-array: []; $p5obj.takes-an-array-ref: $[]; ``` `CODE` objects are passed by reference automatically: -```perl6 +```raku $p5obj.takes-a-coderef: *.so; ``` `Regex` objects are passed by reference automatically: -```perl6 +```raku $p5obj.takes-a-regex: /foo/; ``` ## Catch exceptions thrown by Perl 5 code -Perl 5's exceptions (die) are translated to X::AdHoc exceptions in Perl 6 and -can be caught like any other Perl 6 exceptions: +Perl 5's exceptions (die) are translated to X::AdHoc exceptions in Raku and +can be caught like any other Raku exceptions: ``` { @@ -352,9 +352,9 @@ can be caught like any other Perl 6 exceptions: } ``` -## Catch exceptions thrown by Perl 6 code in Perl 5 +## Catch exceptions thrown by Raku code in Perl 5 -Perl 6's exceptions (die) are translated to Perl 5 exceptions and +Raku's exceptions (die) are translated to Perl 5 exceptions and can be caught like any other Perl 5 exceptions: ``` @@ -367,11 +367,11 @@ can be caught like any other Perl 5 exceptions: PERL5 ``` -## Mix Perl 5 and Perl 6 code in the same file +## Mix Perl 5 and Raku code in the same file Inline::Perl5 creates a virtual module called "v6-inline". By saying "use v6-inline;" in a Perl 5 module, you can declare that the rest of the file -is written in Perl 6: +is written in Raku: ``` package Some::Perl5::Module; @@ -386,7 +386,7 @@ is written in Perl 6: ``` Note that this Perl 5 module obviously will only work when Inline::Perl5 is -loaded, i.e. in a Perl 6 program or if you are using Inline::Perl6 in Perl 5. +loaded, i.e. in a Raku program or if you are using Inline::Perl6 in Perl 5. This functionality is aimed at supporting Perl 5 frameworks (think Catalyst or DBIx::Class or Dancer or ...) that automatically load modules and of course expect these modules to be written in Perl 5. @@ -402,7 +402,7 @@ you have to build it as: perlbrew install perl-stable -Duseshrplib (or, if you want to use more than one Inline::Perl5 interpeter safely, for -instance from within Perl 6 threads, add the `-Dusemultiplicity` option as well) +instance from within Raku threads, add the `-Dusemultiplicity` option as well) If you use plenv: @@ -415,7 +415,7 @@ package already contains everything needed. Build Inline::Perl5 with - perl6 configure.pl6 + raku configure.pl6 make and test with diff --git a/lib/Inline/Perl5.pm6 b/lib/Inline/Perl5.pm6 index 6a4cd93..a2b492e 100644 --- a/lib/Inline/Perl5.pm6 +++ b/lib/Inline/Perl5.pm6 @@ -942,12 +942,12 @@ method require(Str $module, Num $version?, Bool :$handle) { my @import_args; push @!required_modules, ($module, $version, @import_args); - # wrap the load_module call so exceptions can be translated to Perl 6 + # wrap the load_module call so exceptions can be translated to Raku my @packages = $version ?? self.call-simple-args('v6::load_module', $module, $version) !! self.call-simple-args('v6::load_module', $module); - return unless self eq $default_perl5; # Only create Perl 6 packages for the primary interpreter to avoid confusion + return unless self eq $default_perl5; # Only create Raku packages for the primary interpreter to avoid confusion { my $module_symbol = ::($module); @@ -1242,7 +1242,7 @@ our sub init_inline_perl6_callback(Str $path) { } END { - # Perl 6 does not guarantee that DESTROY methods are called at program exit. + # Raku does not guarantee that DESTROY methods are called at program exit. # Make sure at least the first Perl 5 interpreter is correctly shut down and thus can e.g. # flush its output buffers. This should at least fix the vast majority of use cases. # People who really do use multiple Perl 5 interpreters are probably experienced enough diff --git a/notes.txt b/notes.txt index dbecd6b..7fed00a 100644 --- a/notes.txt +++ b/notes.txt @@ -1,23 +1,23 @@ -FIXME sv_2mortal the P5 ref when wrapping in P6. +FIXME sv_2mortal the P5 ref when wrapping in Raku. -in P5 destructor: remove object from objects PPA and set P6 object id to 0 as a flag, +in P5 destructor: remove object from objects PPA and set Raku object id to 0 as a flag, arm the destructor again: sv_2mortal(SvREFCNT_inc(self)) when passing the object to P5 again and we note that it already has magic, but the object id is 0, -add the P6 object to the list and note the id +add the Raku object to the list and note the id scrap that! New plan: I can use the original reference to the P5 object that -contains the base class' data and store it in the Perl 6 object. And when I -pass the Perl 6 object to Perl 5 code I can simply create a new reference that +contains the base class' data and store it in the Raku object. And when I +pass the Raku object to Perl 5 code I can simply create a new reference that will be pretty indistiguishable from the original one but will have an independent reference count. DOESNT WORK! Every variable is a new SV, i.e. a new ref -This way the Perl 6 object will have complete ownership of the Perl 5 kernel, -while it's still possible for Perl 5 code to keep the Perl 6 object alive! +This way the Raku object will have complete ownership of the Perl 5 kernel, +while it's still possible for Perl 5 code to keep the Raku object alive! Plan: start with refcnt 1 When passing to P5: add magic, keep refcnt at 1 and mortalize -in destructor: free P6 object and resurrect +in destructor: free Raku object and resurrect When passing to P5 again: re-set index, keep refcnt at 1 and mortalize -in P6 destructor: remove magic, free P5 object +in Raku destructor: remove magic, free P5 object Case 1: obj created, never passed to P5 and destroyed create: ref refcnt 1, obj refcnt 1 @@ -26,9 +26,9 @@ Case 2: obj created, passed only to P5 and destroyed create: ref refcnt 1, obj refcnt 1 passed to P5, ref refcnt 1, obj refcnt 2 (mortalized) destroyed in P5: refcnt 1, disabled magic - -> P6 obj gets collected -> P5 obj destroyed because no magic -Case 3: obj created, passed to P5, kept in P6, later destroyed + -> Raku obj gets collected -> P5 obj destroyed because no magic +Case 3: obj created, passed to P5, kept in Raku, later destroyed create: refcnt 1 passed to P5, refcnt 2, mortalized destroyed in P5: refcnt 1, disabled magic -Case 5: obj created, passed to P5, kept in P6, later released in P6 +Case 5: obj created, passed to P5, kept in Raku, later released in Raku diff --git a/t/call.t b/t/call.t index 3a3ad4a..1baa758 100644 --- a/t/call.t +++ b/t/call.t @@ -44,7 +44,7 @@ sub test_int_retvals { } sub test_str_retval { - return "Hello Perl 6!"; + return "Hello Raku!"; } sub test_mixed_retvals { @@ -118,7 +118,7 @@ else { say " got: {@retvals} ({@retvals.elems} elems)"; say " expected: 3, 1, 2"; } -if ($p5.call('test_str_retval') eq 'Hello Perl 6!') { +if ($p5.call('test_str_retval') eq 'Hello Raku!') { say "ok 6 - return one string"; } else { @@ -163,10 +163,10 @@ else { } if ($p5.call('test_foo', 'main', $p5.call('Foo::new', 'Foo', 6)) == 6) { - say "ok 12 - Passing Perl 5 objects back from Perl 6"; + say "ok 12 - Passing Perl 5 objects back from Raku"; } else { - say "not ok 12 - Passing Perl 5 objects back from Perl 6"; + say "not ok 12 - Passing Perl 5 objects back from Raku"; } $p5.DESTROY; diff --git a/t/call_back.t b/t/call_back.t index 868883c..76dbf42 100644 --- a/t/call_back.t +++ b/t/call_back.t @@ -8,12 +8,12 @@ $p5.run(q/ use Test::More; sub test { - my ($perl6) = @_; + my ($raku) = @_; for (1 .. 100) { - my @retval = $perl6->test('Perl6'); - is_deeply \@retval, ['Perl6']; - my @retval = $perl6->test('Perl', 6); - is_deeply \@retval, ['Perl', 6]; + my @retval = $raku->test('Raku'); + is_deeply \@retval, ['Raku']; + my @retval = $raku->test('Raku', 42); + is_deeply \@retval, ['Raku', 42]; } }; /); diff --git a/t/inherit.t b/t/inherit.t index 251a1f6..13899e9 100644 --- a/t/inherit.t +++ b/t/inherit.t @@ -20,12 +20,12 @@ is(Foo.new(foo => 'custom').foo, 'custom'); class P6Bar is Foo { method bar { - return "Perl6"; + return "Raku"; } } -is(P6Bar.new.test, 'Perl6'); +is(P6Bar.new.test, 'Raku'); is(P6Bar.new.test_inherited, 'Perl5'); is(P6Bar.new.foo, 'Moose!'); is(P6Bar.new(foo => 'custom').foo, 'custom'); @@ -39,22 +39,22 @@ is(P6Bar.new.split, 'split', 'print method not interfering with inheritance'); class Baz is Foo { method bar { - return "Perl6!"; + return "Raku!"; } } my $baz = Baz.new; -is($baz.test, 'Perl6!') for ^2; +is($baz.test, 'Raku!') for ^2; class Qux is Bar { method qux { - return "Perl6!!"; + return "Raku!!"; } } -is(Qux.new.test, 'Perl6!!'); +is(Qux.new.test, 'Raku!!'); # vim: ft=perl6