From 0e3ac1f4dbd186484ae0d61adb2cd9312a517458 Mon Sep 17 00:00:00 2001 From: schultzdavid Date: Fri, 31 Oct 2025 14:44:23 +0000 Subject: [PATCH 1/8] some corrections & clarifications --- doc/Language/py-nutshell.rakudoc | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/doc/Language/py-nutshell.rakudoc b/doc/Language/py-nutshell.rakudoc index f92d519f9..a920f8537 100644 --- a/doc/Language/py-nutshell.rakudoc +++ b/doc/Language/py-nutshell.rakudoc @@ -32,7 +32,7 @@ Raku put "Hello, world!" There is also the L keyword, which behaves similarly, but will -call the L method of its argument. +call the L<.gist|/routine/gist> method of its argument instead of the C<.Str|/routine/Str> method. Raku @@ -64,8 +64,9 @@ matching curly braces are closed. In Raku, a semicolon signifies the end of a statement. The semicolon may be omitted if it is the last statement -of a block. The semicolon may also be omitted if there -is a closing curly brace followed by a newline. +of a block (i.e. of a list of statements enclosed in curly braces). +The semicolon may also be omitted after a closing curly brace +followed by a newline. Python @@ -81,6 +82,7 @@ Raku 3 + 4; say 1 + 2; + if True { say 42 } =head2 Blocks @@ -123,7 +125,7 @@ initialized or declared and initialized at once. $foo = 12; # initialize my $bar = 19; # both at once -Also, as you may have noticed, variables in Raku usually start with sigils -- +Also, as you may have noticed, variables in Raku usually start with sigils – symbols indicating the type of their container. Variables starting with a C<$> hold scalars. Variables starting with an C<@> hold arrays, and variables starting with a C<%> hold a hash (dict). Sigilless variables, declared with a @@ -398,7 +400,7 @@ I say "Symbol '$symbol' stands for $element"; } -=head2 Lambdas, functions and subroutines> +=head2 Functions, subroutines and lambdas Declaring a function (subroutine) with C in Python is accomplished with C in Raku. @@ -406,12 +408,15 @@ with C in Raku. =begin code :lang def add(a, b): return a + b +=end code +=begin code sub add(\a, \b) { return a + b } =end code + The C is optional; the value of the last expression is used as the return value: @@ -431,8 +436,8 @@ sub add($a, $b) { Python 2 functions can be called with positional arguments or keyword arguments. These are determined by the caller. In Python 3, some arguments may be "keyword only". -In Raku, positional and named arguments are determined -by the signature of the routine. +In Raku, each argument is either positional or named, +as determined by the signature of the routine. Python From 9605a68a65416bec08ac9846cface4f3366d3527 Mon Sep 17 00:00:00 2001 From: schultzdavid Date: Sat, 1 Nov 2025 14:48:18 +0000 Subject: [PATCH 2/8] flesh out text on ecosystem --- doc/Language/py-nutshell.rakudoc | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/doc/Language/py-nutshell.rakudoc b/doc/Language/py-nutshell.rakudoc index a920f8537..af7d0f150 100644 --- a/doc/Language/py-nutshell.rakudoc +++ b/doc/Language/py-nutshell.rakudoc @@ -832,4 +832,23 @@ Raku using the List type, or from an external module. my $list4 = (|$list1, |$list2); # equivalent to previous line say $list3; # OUTPUT: «(1, two, 3, hat, 5, 6, seven)␤» +=head1 Ecosystem + +Where Python has pip, anaconda or uv, Raku has zef as its preferred tool for module management. + +Where Python has PyPi, Raku has +as the central index of third-party L. +There are modules from three different ecosystems – +please stick to the I ecosystem. +(The others, I and I, are deprecated when it comes to Raku.) +See L for additional information, +including guidance on how to publish your own modules. + +=head2 Web development + +The Raku module L serves a similar job as Python's L. + +The Raku module L is an object–relational mapper, similar to Django's ORM capabilities or to SQLAlchemy. + =end pod + From c82d575054c147b0121dc0d2654a55e201f7a447 Mon Sep 17 00:00:00 2001 From: schultzdavid Date: Sat, 1 Nov 2025 15:00:06 +0000 Subject: [PATCH 3/8] fix rakudoc link syntax --- doc/Language/py-nutshell.rakudoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Language/py-nutshell.rakudoc b/doc/Language/py-nutshell.rakudoc index af7d0f150..8515ec6fd 100644 --- a/doc/Language/py-nutshell.rakudoc +++ b/doc/Language/py-nutshell.rakudoc @@ -836,7 +836,7 @@ Raku using the List type, or from an external module. Where Python has pip, anaconda or uv, Raku has zef as its preferred tool for module management. -Where Python has PyPi, Raku has +Where Python has PyPi, Raku has L as the central index of third-party L. There are modules from three different ecosystems – please stick to the I ecosystem. From 1de6d361f1cb1683bb2561acf2b51074b197773b Mon Sep 17 00:00:00 2001 From: schultzdavid Date: Sun, 2 Nov 2025 15:18:48 +0000 Subject: [PATCH 4/8] move code back together, adding comments --- doc/Language/py-nutshell.rakudoc | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/doc/Language/py-nutshell.rakudoc b/doc/Language/py-nutshell.rakudoc index 8515ec6fd..b310a0ea7 100644 --- a/doc/Language/py-nutshell.rakudoc +++ b/doc/Language/py-nutshell.rakudoc @@ -406,12 +406,10 @@ Declaring a function (subroutine) with C in Python is accomplished with C in Raku. =begin code :lang -def add(a, b): +def add(a, b): # Python return a + b -=end code -=begin code -sub add(\a, \b) { +sub add(\a, \b) { # Raku return a + b } =end code From 3b732566f33655cb6318ff7ff931c70d0a2e68ab Mon Sep 17 00:00:00 2001 From: schultzdavid Date: Mon, 3 Nov 2025 13:40:33 +0000 Subject: [PATCH 5/8] move Python & Raku code apart, state the language for each --- doc/Language/py-nutshell.rakudoc | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/doc/Language/py-nutshell.rakudoc b/doc/Language/py-nutshell.rakudoc index b310a0ea7..7a8a72079 100644 --- a/doc/Language/py-nutshell.rakudoc +++ b/doc/Language/py-nutshell.rakudoc @@ -405,16 +405,21 @@ I Declaring a function (subroutine) with C in Python is accomplished with C in Raku. +Python + =begin code :lang -def add(a, b): # Python +def add(a, b): return a + b +=end code + +Raku -sub add(\a, \b) { # Raku +=begin code +sub add(\a, \b) { return a + b } =end code - The C is optional; the value of the last expression is used as the return value: From 6f8e5edce9fe6aa0d1eaa63cb36d1a4c27df5cbc Mon Sep 17 00:00:00 2001 From: David Schultz Date: Mon, 3 Nov 2025 15:00:48 +0100 Subject: [PATCH 6/8] unify italics & colon usage before code snippets --- doc/Language/py-nutshell.rakudoc | 94 ++++++++++++++++---------------- 1 file changed, 47 insertions(+), 47 deletions(-) diff --git a/doc/Language/py-nutshell.rakudoc b/doc/Language/py-nutshell.rakudoc index 7a8a72079..af87df258 100644 --- a/doc/Language/py-nutshell.rakudoc +++ b/doc/Language/py-nutshell.rakudoc @@ -17,24 +17,24 @@ Let's start with printing "Hello, world!". The L keyword in Raku is the equivalent of L in Python. Like Python 2, parentheses are optional. A newline is added to the end of the line. -I +I =for code :lang print "Hello, world!" -I +I =for code :lang print("Hello, world!") -Raku +I put "Hello, world!" There is also the L keyword, which behaves similarly, but will call the L<.gist|/routine/gist> method of its argument instead of the C<.Str|/routine/Str> method. -Raku +I my $hello = "Hello, world!"; say $hello; # also prints "Hello, world!" @@ -46,7 +46,7 @@ quotes (C<">) signify that interpolation should be performed. For instance, variables that start with a C<$>, and expressions contained in curly braces are interpolated. -Raku +I my $planet = 'earth'; say "Hello, $planet"; # OUTPUT: «Hello, earth␤» @@ -68,7 +68,7 @@ of a block (i.e. of a list of statements enclosed in curly braces). The semicolon may also be omitted after a closing curly brace followed by a newline. -Python +I =for code :lang print 1 + 2 + \ @@ -76,7 +76,7 @@ print 1 + 2 + \ print ( 1 + 2 ) -Raku +I say 1 + 2 + 3 + 4; @@ -89,7 +89,7 @@ Raku In Python, indentation is used to indicate a block. Raku uses curly braces. -Python +I =for code :lang if 1 == 2: @@ -97,7 +97,7 @@ if 1 == 2: else: print("1 is not 2.") -Raku +I if 1 == 2 { say "Wait, what?" @@ -138,7 +138,7 @@ correct, but in general we are going to use sigilless variables in places where their immutability (or independence of type, when they are used in signatures) is needed or needs to be highlighted. -Python +I =begin code :lang s = 10 @@ -151,7 +151,7 @@ print(d['a']) # 10, 3, 12 =end code -Raku +I my $s = 10; my @l = 1, 2, 3; @@ -174,7 +174,7 @@ Python 3, they do. In Raku, every block creates a lexical scope. -Python +I =for code :lang if True: @@ -182,7 +182,7 @@ if True: print(x) # x is now 10 -Raku +I =for code :skip-test if True { @@ -199,7 +199,7 @@ if True { say $x # ok, $x is 10 -Python +I =for code :lang x = 10 @@ -208,7 +208,7 @@ for x in 1, 2, 3: print(x) # x is 3 -Raku +I my \x = 10; for 1, 2, 3 -> \x { @@ -219,19 +219,19 @@ Raku Lambdas in Python can be written as blocks or pointy blocks in Raku. -Python +I =for code :lang l = lambda i: i + 12 -Raku +I =for code :preamble my $l = -> $i { $i + 12 } Another Raku idiom for constructing lambdas is the Whatever star, C<*>. -Raku +I my $l = * + 12 # same as above @@ -244,7 +244,7 @@ See the section below for more constructs regarding subroutines and blocks. Another example (from the Python L): -Python +I =for code :lang squares = [] @@ -254,7 +254,7 @@ print(squares[2]()) print(squares[4]()) # both 16 since there is only one x -Raku +I my \squares = []; for ^5 -> \x { @@ -309,7 +309,7 @@ C leaves a loop in Raku, and is analogous to C in Python. C in Python is C in Raku. -Python +I =for code :lang for i in range(10): @@ -319,7 +319,7 @@ for i in range(10): break print(i) -Raku +I for ^10 -> $i { next if $i == 3; @@ -334,7 +334,7 @@ The C statement within a C loop in Python, which produces a C, is like a C/C construct in Raku. These both print 1, 2, 3. -I +I =begin code :lang def count(): @@ -345,7 +345,7 @@ for c in count(): print(c) =end code -I +I sub count { gather { @@ -364,7 +364,7 @@ iterating lists or dict/maps can both be achieved using the same L method in Raku (because the "key" of a list is its array-like numeric index): -I +I =begin code :lang elems = ["neutronium", "hydrogen", "helium", "lithium"] @@ -384,7 +384,7 @@ for symbol, elem in elem4Symbol.items(): # Symbol 'n' stands for neutronium =end code -I +I my @elems = ; for @elems.kv -> $i, $e { @@ -405,14 +405,14 @@ I Declaring a function (subroutine) with C in Python is accomplished with C in Raku. -Python +I =begin code :lang def add(a, b): return a + b =end code -Raku +I =begin code sub add(\a, \b) { @@ -442,7 +442,7 @@ In Python 3, some arguments may be "keyword only". In Raku, each argument is either positional or named, as determined by the signature of the routine. -Python +I =begin code :lang def speak(word, times): @@ -452,7 +452,7 @@ speak('hi', 2) speak(word='hi', times=2) =end code -Raku +I Positional parameters: @@ -494,12 +494,12 @@ Named parameters can be sent using a variety of formats: Creating an anonymous function can be done with C, with a block or with a pointy block. -Python +I =for code :lang square = lambda x: x ** 2 -Raku +I my $square = sub ($x) { $x ** 2 }; # anonymous sub my $square = -> $x { $x ** 2 }; # pointy block @@ -517,12 +517,12 @@ parameters. Thus these are the same: Postfix statement modifiers and blocks can be combined to easily create list comprehensions in Raku. -Python +I =for code :lang print([ i * 2 for i in [3, 9]]) # OUTPUT: «[6, 18]␤» -Raku +I say ( $_ * 2 for 3, 9 ); # OUTPUT: «(6 18)␤» say ( { $^i * 2 } for 3, 9 ); # OUTPUT: «(6 18)␤» @@ -561,14 +561,14 @@ L =for code :lang class Dog: def __init__(self, name): self.name = name -Raku: +I class Dog { has $.name; @@ -577,7 +577,7 @@ Raku: For each created class, Raku provides the constructor method C by default which takes named arguments. -Python: +I =for code :lang d = Dog('Fido') @@ -585,7 +585,7 @@ e = Dog('Buddy') print(d.name) print(e.name) -Raku +I =for code :preamble my $d = Dog.new(:name); # or: Dog.new(name => 'Fido') @@ -596,7 +596,7 @@ say $e.name; Class attributes in Raku can be declared in a few ways. One way is to just declare a lexical variable and a method for accessing it. -Python: +I =for code :lang class Dog: @@ -610,7 +610,7 @@ print(e.kind) print(d.name) print(e.name) -Raku: +I class Dog { my $kind = 'canine'; # class attribute @@ -628,7 +628,7 @@ Raku: In order to mutate attributes in Raku, you must use the C trait on the attributes: -Python: +I =for code :lang class Dog: @@ -637,7 +637,7 @@ class Dog: d = Dog() d.name = 'rover' -Raku: +I class Dog { has $.name is rw; @@ -661,7 +661,7 @@ d = Dog() d.jump() =end code -Raku +I class Animal { method jump { @@ -685,7 +685,7 @@ Python class Dog(Animal, Friend, Pet): pass -Raku +I class Animal {}; class Friend {}; class Pet {}; ...; @@ -722,7 +722,7 @@ def world(): world(); =end code -Raku +I sub world { say 'world' @@ -814,7 +814,7 @@ in the C variable. This is similar to L in R Python tuples are immutable sequences. The sequence elements do not need to be of the same types. -Python +I =for code :lang tuple1 = (1, "two", 3, "hat") @@ -823,7 +823,7 @@ print(tuple1[1]) # OUTPUT: «two␤» tuple3 = tuple1 + tuple2 print(tuple3) # OUTPUT: «(1, 'two', 3, 'hat', 5, 6, 'seven')␤» -Raku +I Raku does not have a builtin Tuple type. You can get the same behavior from Raku using the List type, or from an external module. From 323acff94aaed4fa2f762775da57fe72b76b25b0 Mon Sep 17 00:00:00 2001 From: David Schultz Date: Mon, 3 Nov 2025 22:49:16 +0100 Subject: [PATCH 7/8] fix output being outside of code block --- doc/Language/py-nutshell.rakudoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/Language/py-nutshell.rakudoc b/doc/Language/py-nutshell.rakudoc index af87df258..3451954b8 100644 --- a/doc/Language/py-nutshell.rakudoc +++ b/doc/Language/py-nutshell.rakudoc @@ -281,7 +281,7 @@ or symbol that can be used in Raku has an ASCII equivalent. Python has C loops and C loops: -=for code :lang +=begin code :lang for i in 1, 2: print(i) j = 1 @@ -290,6 +290,7 @@ while j < 3: j += 1 # 1, 2, 1, 2 +=end code Raku also has C loops and C loops: From 5e6f26fc3254f6a0c394cd418d3658561f9ecd2a Mon Sep 17 00:00:00 2001 From: David Schultz Date: Fri, 7 Nov 2025 16:42:51 +0100 Subject: [PATCH 8/8] change en dash to em dash --- doc/Language/py-nutshell.rakudoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Language/py-nutshell.rakudoc b/doc/Language/py-nutshell.rakudoc index 3451954b8..59f0e369b 100644 --- a/doc/Language/py-nutshell.rakudoc +++ b/doc/Language/py-nutshell.rakudoc @@ -125,7 +125,7 @@ initialized or declared and initialized at once. $foo = 12; # initialize my $bar = 19; # both at once -Also, as you may have noticed, variables in Raku usually start with sigils – +Also, as you may have noticed, variables in Raku usually start with sigils— symbols indicating the type of their container. Variables starting with a C<$> hold scalars. Variables starting with an C<@> hold arrays, and variables starting with a C<%> hold a hash (dict). Sigilless variables, declared with a