hankache / rakuguide

The Raku Guide

Raku Guide

This document is intended to give you a quick overview of the Raku programming language.
For those who are new to Raku it should get you up and running.

Website

For online reading navigate to:

• English: https://raku.guide
• French: https://raku.guide/fr
• German: https://raku.guide/de
• Japanese: https://raku.guide/ja
• Spanish: https://raku.guide/es
• Portuguese: https://raku.guide/pt
• Dutch: https://raku.guide/nl
• Bulgarian: https://raku.guide/bg
• Chinese: https://raku.guide/zh
• Italian: https://raku.guide/it
• Turkish: https://raku.guide/tr
• Indonesian: https://raku.guide/id
• Russian: https://raku.guide/ru
• Ukrainian: https://raku.guide/uk

Building the document

The document is written in asciidoc format and generated using asciidoctor and pygments. You will need a current version of ruby, asciidoctor, pygments, and a special gem that provides a pre-release version of asciidoctor-pdf.

Install the required tools:

$ sudo pip install Pygments
$ sudo gem install asciidoctor
$ sudo gem install asciidoctor-pdf
$ sudo gem install pygments.rb

To produce rakuguide.pdf, run:

$ asciidoctor-pdf rakuguide.adoc

To produce rakuguide.html, run:

$ asciidoctor rakuguide.adoc

Feedback

All feedback is welcomed:

• Corrections
• Suggestions
• Additions
• Translations

Translations

If you wish to translate this document, always use the English version as your starting point. If you are starting a new translation create a new file. For example, the French translation will be in fr.rakuguide.adoc, the Deutsch translation in de.rakuguide.adoc
If you want to modify a translated version, consider modifying the English version first. It is important that all translations be kept in sync.

Currently the translations are in different phases of completion. For completeness rely on the English version.

Contributing

Kindly prefix your commit title with the language it is targeting. For example, all commits targeting the English version would have a title that starts with [EN]. All commits targeting the Spanish translation have a title that starts with [ES].

Authors

• Original English version: Naoum Hankache
• French Translation: Romuald Nuguet
• German Translation: Sören Laird Sörries
• Japanese Translation: Itsuki Toyota
• Spanish Translation: Ramiro Encinas
• Portuguese Translation: Breno G. de Oliveira
• Dutch Translation: Elizabeth Mattijsen
• Bulgarian Translation: Красимир Беров
• Chinese Translation: wenjie1991 and ohmycloud
• Italian Translation: MarsMarsico
• Turkish Translation: Yalın Pala
• Indonesian Translation: Heince Kurniawan
• Russian Translation: Alexander Kiryuhin
• Ukrainian Translation: Dmytro Iaskolko

For the full list of contributors: https://github.com/hankache/rakuguide/graphs/contributors

License

Creative Commons Attribution-ShareAlike 4.0 International License.
To view a copy of this license, visit https://creativecommons.org/licenses/by-sa/4.0/.

rakuguide's Issues

Please use HTTPS

Looks like newer browsers report site as insecure when you try to visit it, as reported by one of the users here (possibly using HTTPS-everywhere plugin): https://twitter.com/shniperson2/status/1008996718912987136

Even though the site doesn't handle any sensitive info, not using HTTPS still puts users at risk as malicious agent can inject unwanted stuff into the page, such at bitcoin miners or an invitation for the user to install a malicious piece of software, which they might, because they trust your site.

These days it's pretty easy to get a cert from Let's Encrypt and you can manage it easily with tools like Certbot

`0 ^.. 10` is NOT the same as `1 .. 10`

I'm raising this issue rather than a PR because it's not obvious if anything needs to be done. But...

This twitter thread caught my attention. It seems that perl6intro implies that 0 ^.. 10 and 1 .. 10 are the same. But...

say (0 ^.. 10) eqv (0 ^.. 10); # True
say (0 ^.. 10) eqv (1 .. 10);  # False

0 ^.. 10 is a range that starts above zero (and stops at 10). 1 .. 10 starts at 1 (and stops at 10).

These two ranges, used when an integer range is expected, produce the same result. But, when used in other scenarios, they may not:

say 1e-999999 ~~ 0  .. 10; # True
say 1e-999999 ~~ 0 ^.. 10; # False
say 1e-9      ~~ 0  .. 10; # True
say 1e-9      ~~ 0 ^.. 10; # True
say 1.0       ~~ 1 ^.. 10; # False
say 1.1       ~~ 1  .. 10; # True

See the Range doc for more details.

Track translation in separated branches

Hello,

I'm looking at syncing the french translation with the English one (actually 370 commits behind hankache:master).

I think that we may ease the tracking of translation by putting each one in a separate branch, each translation using the same filename.

This way:

• it's easy to see the differences between English and the translation, for example: git diff master..translation/french
• it's easy to synchronise with English, for example:
  • me@home:~/src/perl6intro (translation/french<)$ git merge master
  • resolve conflicts:
    • redo the translation of the conflicting text if English content has meaningfully changed
    • Keep the actual translation of English changes are just cosmetics (grammar, typo, …)

This will require a modification to the publication tools to iterate over each translation/ branch to build the documentation.

What do you think about this idea?

Regards.

Please add a recursion example to the functional programming section

I notice the Raku Guide has a section on functional programming but makes no mention of recursion. In functional programming recursion is favored over loops. So, this strikes me as a significant omission to the section.

Andrew Shitov's has a blog post Computing Factorials Using Raku that gives an excellent and highly readable recursion example in Raku. You might want to use a similar example. From his post:

unit sub MAIN($n);

sub factorial($n) {
    return 1 if $n < 2;
    return $n * factorial($n - 1);
}

say factorial($n);

As you can see the code uses a postfix if on a return statement. It's a very readable and idiomatic way to create a recursive function. It's also worth mentioning that, according to the official Raku documentation, if can be used this way but attempting to do the same thing with else or elsif results in a syntax error. This is also probably worth mentioning.

example doesn't compile

Hi. Going through your tutorial.

my $a;
my $b;
$b := $a;

Last line doesn't compile.

My perl version:

This is Rakudo Star version 2017.10 built on MoarVM version 2017.10
implementing Perl 6.c.

append to beginning of is awkward, confusing usage.

In a couple of places, the usage "append $thing to the beginning of $other_thing" appears. This isn't technically incorrect, but it's unusual and somewhat confused me when reading. "Append" naturally points the reader at the end of whatever you're talking about.

I think this should change to either "prepend $thing to $other_thing" or "add $thing to the beginning of $other_thing," neither of which have the "happens at the end" implications that "append" does.

Regex example produces "Use of Nil in string context" exception.

Going through the regex section, I follow along with the example, however, upon running the example I get

Use of Nil in string context
  in block <unit> at e.pl6 line 5
 is a valid email

I get his is with code copied straight out of the the book:

[ daph@archbox ~/perl6]% cat e.pl6 
my $email = '[email protected]';
my $regex = / <:L>+\.<:L>+\@<:L+:N>+\.<:L>+ /;

if $email ~~ $regex {
  say $/ ~ " is a valid email";
} else {
  say "This is not a valid email";
}

My perl6 is rakudo-star 2016.10

Mention rlwrap or Linenoise at the top

To get a repl that has working command line editing, either mention use of rlwrap (install rlwrap, then run perl6 like, rlwrap perl6), or else usage of the Linenoise module.

Fix the description of the panda in the Japanese document

It should be

_Panda_ is a module management tool that comes with Rakudo Star

SEE ALSO: 4f72adf

binding code snippet example not working

Following code in section 3.7. Assignment vs. Binding seems not working
my $a; my $b; $b := $a; $a = 7; say $b; $b = 8; say $a;

i got the following error message:
`

my $a
(Any)
my $b
(Any)
$b := $a;
===SORRY!=== Error while compiling:
Cannot use bind operator with this left-hand side
------> $b := $a;`

Use of string concatenation rather than variable interpolation?

One of the core advantages of Perl 6 over Perl 5 for me is how advanced variable interpolation is in quoting. For some reason most of perl6intro prefers "" ~ value ~ "" which I find kind of messy. Is there a strong preference for this? Or am I ok to go through and change these where appropriate? For example say "The capital of France is: %capitals<France>" works perfectly well. More complex expressions I'd prefer "{ expression }" to "" ~ expression ~ "". I'd reserve ~ for something more like $str1 ~ $str2 where there is no default quote construct to be included.

Bug in corrected Multiple inheritance example

In section 9.8 https://perl6intro.com/#_multiple_inheritance for the corrected example, I am not getting the right output. I am guessing the constructor is not correctly assigning the lines-valuesargument to the inherited @.lines-values attribute?

Instead of:

Actual sales:
[10 9 11 8 7 10]
Forecast sales:
[9 8 10 7 6 9]
Actual vs Forecast:
[10 9 11 8 7 10]
[9 8 10 7 6 9]

I get:

Actual sales:
[10 9 11 8 7 10]
Forecast sales:
[9 8 10 7 6 9]
Actual vs Forecast:
[10 9 11 8 7 10]
[]

Optional semicolons shown as if they're mandatory

semicolons actually not needed after if()s {}{} here: http://perl6intro.com/#_if and this can use a better example of a statement needing a semicolon: http://perl6intro.com/#_syntax_overview

far too long

For an “introduction”, this is way, way, way, way, way, way, way too long. Give newbies some useful examples, NOT scalars arrays hashes I/O modules ……………… boring.

The Japanese document lacks description of the reversed and reduction ops

SEE ALSO: 4f72adf

favicon says P6

Can the favicon be changed to something refering to Raku instead of Perl6?
Maybe "RG" for "Raku Guide"?

Typo in the arrays intro.

http://perl6intro.com/#_arrays

The first assignment is using brackets instead of parenthesis.

[TR] 10.1 Catching Exceptions

@yplog In my last commit I added a missing heading for "Catching Exceptions" can you kindly translate it.
Thanks.

For regex definitions explain the differences

http://perl6intro.com/#_regex_definition

Explain the differences between

/light/
m/light/
rx/light/

Are they all the same in the context of smart matching (~~) ?

This language doc shows that m/thing/ is matched immediately against $_.

The other two are just regex objects. Perhaps they're better used when saving the regex in a variable?

Japanese translation

@titsuki can you kindly update:

• Line 1 The translation of "introduction" in "Perl 6 Introduction"
• Line 12 The translation of "Table of Content"
• Some examples could be modified to use Japanese letters and showcase unicode support. So for example instead of say "Hello World"; you can use say "こんにちは世界"; etc. Assuming this is how you write hello world in Japanese. I just used Google translate ;)

"Closures" section has only one line.

I see that we have only one line about closures copied from the official documentation.
I would suggest that we copy at least the first example from there, thus explaining the matter.
https://docs.perl6.org/language/functions#Closures

sub generate-sub($x) {
    my $y = 2 * $x;
    return sub { say $y };
    #      ^^^^^^^^^^^^^^  inner sub, uses $y
}
my $generated = generate-sub(21);
$generated(); # 42

Here $y is a lexical variable inside generate-sub, and the inner subroutine that is returned uses it. By the time that the inner sub is called, generate-sub has already exited. Yet the inner sub can still use $y, because it closed over the variable.

Style/wording review

Listing here some places we have found in English version during reviewing of Russian translation.

• Section 1.2 title is Jargon. However, in this section we have tools names and no jargon at all. Probably needs to be renamed to something more appropriate.
• In section 3.4 (Types), it can be nice to add output.
• In section 7.4, list is used for only two elements. It is possible that it'd be more nice when seen in a single sentence.
• Intro explains about keywords such as does or is, but in fact those are traits, so it is a bit of misguiding here. But I am not sure how to explain such concept in, well, introduction. Similar thing, it says keyword has(used to define attributes), but in fact it is a scope declarator, not a "keyword". Or I am wrong here.
• Usages of "Output" inside of code tag and without it is mixed and inconsistent.

We did not review everything yet, so maybe new points will be added in comments later.

Download for OS X missing macports

Brew is listed, but the macport is not.

sudo port install rakudo

Note that this does not include the Star modules.

Could you please add Russian language?

Confusion over "mutators" in section 4

http://perl6intro.com/#_functions_and_mutators this section is really quite confusing and has indeed caused confusion already https://www.reddit.com/r/perl6/comments/3vjuex/how_to_easily_tell_the_difference_between_a/

MD5

The book says MD5 alone is not sufficient to hash passwords (which is correct). But then it goes on to recommend using md5 together with a salt??? Can you update it to recommend using a modern hash such as scrypt, bcrypt, or argon2?

Merge code and output to make examples easier to read

I think this:

my Int $var;
say $var.WHAT;
my $var2;
say $var2.WHAT;
$var2 = 1;
say $var2.WHAT;
$var2 = "Hello";
say $var2.WHAT;
$var2 = True;
say $var2.WHAT;
$var2 = Nil;
say $var2.WHAT;

Output

(Int)
(Any)
(Int)
(Str)
(Bool)
(Any)

Would be easier to read as:

my Int $var;
say $var.WHAT;   # (Int)
my $var2;
say $var2.WHAT;  # (Any)
$var2 = 1;
say $var2.WHAT;  # (Int)
$var2 = "Hello";
say $var2.WHAT;  # (Str)
$var2 = True;
say $var2.WHAT;  # (Bool)
$var2 = Nil;
say $var2.WHAT;  # (Any)

Also, in places where you want to say, "evaluates to", #=> would work. For example,

my @animals = ['camel','llama','owl'];
say @animals;

(where, it's output is not currently shown) could just be

my @animals = ['camel','llama','owl'];
#=> [camel llama owl]

(where the output is shown and included right next to the code that generated it).

`print` should be `say` I think

echo prints text to the terminal (the equivalent of print in Perl 6)

Shouldn't print be say here? echo adds newline to the end like say as I know.

Please regenerate HTML for BG and ES

Looks like @ramiroencinas also updated the closure section as I did.
http://bg.perl6intro.com and http://es.perl6intro.com/ need to be regenerated.
Thanks, @hankache

documentation comment raise error in raku REPL

=begin comment
This is a multi line comment.
Comment 1
Comment 2
=end comment

causes:

===SORRY!=== Error while compiling:
Preceding context expects a term, but found infix = instead.
Did you make a mistake in Pod syntax?
at line 2
------> <BOL>⏏<EOL>

Syntax errors in NOTE: or WARNING: lines in Japanese document

It is the wrong way to write "注釈:" instead of "NOTE:" or "警告:" instead of "WARNING:"

example (valid cases)

NOTE: For the complete list of operators, including their precedence, go to http://doc.perl6.org/language/operators

WARNING: The regex used in this example for email validation is not very accurate. +
Its sole purpose is to demonstrate regex functionality in Perl 6. +
Do not use it as-is in production.

UTF8 PDF

asciidoctor-pdf doesn't render utf8. See Unicode examples generated.

Improper explanation about regex \w and \d in the Japanse document

I found two mistakes in the Japanese document.

In the other programming languages(ex. Perl without use utf8;) regex \w is equal to [a-zA-Z0-9_].
But in perl6, regex \w includes unicode characters, so I should erase and edit the following explanation.

単語構成文字 [a-zA-Z0-9_]

FYI: https://doc.perl6.org/language/regexes

In perl6, regex \d could include Arabic digits. But the document says \d is equal to 10進数字(i.e. decimal digits).
So it should replace10進数字 with 数字(i.e. digits).

"ミューテーター" should be written as "ミューテータ" in the Japanese document.

It should delete "ー" symbol, because the all other terms that also can be written using "ー" symbol don't use this symbol.
For example "シグネチャー" is written as "シグネチャ".

French translation

For french Translation:

Replace the term 'sous-programme' par 'routine' ou 'sous-routine' , which is used more often in French.
If resolved, I will do it in my next commit/pull request ...
Thanks.

should snippets of code from perl6intro be linked with an eval service?

we have several on-line eval services that can eval perl6 code for us, like https://glot.io/new/perl6 or https://tio.run/nexus/perl6

zoffix gives you a "run this code" button under every piece of perl6 code on his blog over at perl6.party, for example in https://perl6.party/post/Perl6-But-Heres-My-Dispatch-So-Callwith-Maybe

should we steal the code that does it on perl6.party and introduce it to perl6intro.com?

http://es.perl6intro.com points to english version

http://es.perl6intro.com points to english version instead spanish version.

Constants can be lexically scoped in Raku

In ncitest.raku a constant is defined like this:

constant LIBPATH = "$*CWD/ncitest";

That's entirely valid. However, it really is worth noting to the reader that in Raku, unlike Perl, constants can be lexically scoped with my just like a variable. Thus, the following works as you'd expect:

my constant $A="bar";    
    
sub foo {    
    my constant $A="foo";    
    say $A;    
}    
     
foo();    
say $A;    

The result is:

$ ./constant.raku 
foo
bar

Inside of scopes where $A is already defined as a constant attempts to redefine $A will produce an error. It's worth mentioning this near ncitest.raku, where the first use of constants occurs in the guide. Given the importance of read-only variables to Functional Programming, it's worth reiterating in that section too.

The Japanese document lacks description of what :D and :U smilies do

SEE ALSO: 13a8246

Perl6-fe link is not working for syntax error in Japanese document

See the sentences in the document corresponding to the following one.

私が個人的に使っていておすすめのエディタは Atom です。
モダンなテキストエディタであり、革新的なPerl6のシンタックスハイライティング機能を持っています。
別の選択肢として、https://atom.io/packages/language-perl6fe[Perl6-fe] というAtomのためのシンタックスハイライターがあります。 
オリジナルのパッケージから派生したものですが、多くのバグフィックスと追加機能を含んでいます。

Review of French Translation

@kolikov The first 7 chapters were translated a while back. Some additions and modifications happened to the original version. Can you take a quick look at them and make the necessary modifications?

By the way the translation is now live at fr.perl6intro.com

Thanks.

Link to latest Rakudo Star

Thanks for the excellent raku.guide! I am preparing an Intro to Raku talk and will include a link.

Near the start, about installing Rakudo Star on Linux, is a little out of date– linking to .01 when there is now .10 available.

I think the right fix is two changes:

1. work with rakudo.org and have them institute a “.latest” link on https://rakudo.org/downloads/star so that anyone writing docs can have instructions that reference downloads/star/rakudo-star-2020.01.latest.gz and it will always be the latest.
2. Link to the latest

I wanted to cc the owners of rakudo.org but didn’t find an email for that site. Hope you have a contact there! I can jump on raku IRC if it will help.

If changing rakudo.org download links is too out-of-scope, at least updating to 2020.10 would be good.

Introducing subs a little more clearly?

7.1. Definition

The π is a constant Num in Perl 6 this section kind of makes that a bit confusing, especially as τ is also conceptually a constant rather than a function in maths too. I'm not really convinced showing people a maths symbol name for a sub is the most obvious either for a first example. If you really wanted to show unicode support why not a cat emojii that says meow? Or something equally dumb but perhaps a little less obtuse? Especially as the next signature example is a hello person example anyway?

Digest::MD5 example broken

You cannot create an instance of this type (Digest::MD5)
in block at scum.raku line 3

https://raku.guide/#_using_modules

Suggest rewrite to avoid this seemingly orphaned module