Merge pull request #189 from awwaiid/syntax-additions

Clarify Hash literal syntax. Expand on other things.

Author: LLFourn

doc/Language/syntax.pod

@@ -345,24 +345,29 @@ arrays themselves:
 =head3 L<Hash|/type/Hash> literals
 
 A pair of curly braces can surround a list of pairs to form a
-L<Hash|/type/Hash> literal; typically there is a comma-delimited list
-of pairs inside:
+L<Hash|/type/Hash> literal; typically there is a comma-delimited list of pairs
+inside. If a non-pair is used, it is assumed to be a key and the next element
+is the value. Most often this is used with simple arrow pairs.
+
+    say { a => 3, b => 23, :foo, :dog<cat>, "french", "fries" };
+    # a => 3, b => 23, dog => cat, foo => True, french => fries
 
     say {a => 73, foo => "fish"}.keys.join(" ");   # a foo
     #   ^^^^^^^^^^^^^^^^^^^^^^^^ Hash constructor
 
-Most often this is used with arrow pairs.
+When assigning to a C<%> sigil variable, the curly braces are optional.
 
-=head3 L<Regex|/type/Regex> literals
+    my %ages = fred => 23, jean => 87, ann => 4;
 
-=comment TODO
+=head3 L<Regex|/type/Regex> literals
 
 A regex is declared with slashes like C</foo/>. Note that this C<//> syntax is shorthand for the full C<rx//> syntax.
 
-You can assign regexes to variables, just like with other literals.
+    /foo/          # Short version
+    rx/foo/        # Longer version
+    Q :regex /foo/ # Even longer version
 
-    my $pattern = /foo/;
-    say "Match!" if "asdfoosdf" ~~ $pattern; # Match!
+    my $r = /foo/; # Regexes can be assigned to variables
 
 =head2 Declarations
 
@@ -374,11 +379,15 @@ You can assign regexes to variables, just like with other literals.
     my $x = 7;                  # initialize the variable
     my Int $x = 7;              # declare the type
     my Int $x:D = 7;            # specify that the value must be defined (not undef)
-    my Int $x where * > 3 = 7;  # restrict the value based on a function
+    my Int $x where * > 3 = 7;  # constrain the value based on a function
+
+See L<Variable Declarators and Scope|http://docs.perl6.org/language/variables#Variable_Declarators_and_Scope> for more details on other scopes (our, has).
 
 =head3 Subroutine declaration
 
+    # The signature is optional
     sub foo { say "Hello!" }
+
     sub say-hello($to-whom) { say "Hello $to-whom!" }
 
 You can also assign subroutines to variables.
@@ -387,14 +396,33 @@ You can also assign subroutines to variables.
     my &f = -> { say "Hello!" }  # Lambda style syntax. The & sigil indicates the variable holds a function
     my $f = -> { say "Hello!" }  # Functions can also be put into scalars
 
-=head3 Class, Role, and Grammar declaration
+=head3 Package, Class, Role, and Grammar declaration
+
+    package Gar { }
 
     class Foo { }
 
     role Bar { }
 
     grammar Baz { }
 
+You can declare a unit of things without explicit curly brackets.
+
+    unit package Gar;
+    # ... stuff goes here instead of in {}'s
+
+=head3 Multi-dispatch declaration
+
+Subroutines can be declared with multiple signatures.
+
+    multi sub foo() { say "Hello!" }
+    multi sub foo($name) { say "Hello $name!" }
+
+Inside of a class, you can also declare multi-dispatch methods.
+
+    multi method greet { }
+    multi method greet(Str $name) { }
+
 =head2 L<Subroutine|/language/functions> calls
 
 =comment TODO