Attached patch adds new syntax documentation to docs/imcc/syntax.pod and
fixes some typos there. It now also indicates where various flags are
explained.
Is the shorthand syntax for function calls ("($P0, a :slurpy) = foo(3, b
:flat)") clear, or can we better use examples there?
-- bgeron
Index: docs/imcc/syntax.pod
===================================================================
--- docs/imcc/syntax.pod (revision 16662)
+++ docs/imcc/syntax.pod (working copy)
@@ -132,7 +132,7 @@
set S0, utf8:unicode:"«"
-The encoding and charset gets attaced to the string, no further processing
+The encoding and charset gets attached to the string, no further processing
is done, specifically escape sequences are not honored.
=item numeric constants
@@ -190,11 +190,12 @@
... all subroutines for language I<Foo> would use a dynamic lexpad pmc.
-=item .sub <identifier>
+=item .sub <identifier> [:<flag> ...]
=item .end
-Define a I<compilation unit> with the label B<identifier:>.
+Define a I<compilation unit> with the label B<identifier:>. See
+L<PIR Calling Conventions|imcc/calling_conventions> for available flags.
=item .emit
@@ -237,8 +238,12 @@
=item .const <type> <identifier> = <const>
-Define a named constant of style I<type> and value I<const>.
+=item .globalconst <type> <identifier> = <const>
+Define a named constant of style I<type> and value I<const> only for
+this sub or globally. If I<type> denotes a PMC type, I<const> must be
+a string constant.
+
=item .namespace <identifier>
Open a new scope block. This "namespace" is not the same as the
@@ -320,11 +325,52 @@
=back
-=head2 Parameter Passing Flags
+=head2 Shortcut directives for PCC call and return
+=over 4
+
+=item ([<var> [:<flag> ...], ...]) = <var>([arg [:<flag> ...], ...])
+
+=item <var> = <var>([arg [:<flag> ...], ...])
+
+=item <var>([arg [:<flag> ...], ...])
+
+=item <var>."_method"([arg [:<flag> ...], ...])
+
+=item <var>._method([arg [:<flag> ...], ...])
+
+Function or method call. These notations are shorthand for a longer
+PCC function call with B<.pcc_*> directives. I<var> can denote a
+global subroutine, a local B<identifier> or a B<reg>.
+
+=item .return ([<var> [:<flag> ...], ...])
+
+Return from the current compilation unit with zero or more values.
+
+The surrounded parentheses are mandatory. Besides making sequence
+break more conspiscuous, this is necessary to distinguish this syntax
+from other uses of the B<.return> directive that will be probably
+deprecated.
+
+=item .return <var>(args)
+
+=item .return <var>."somemethod"(args)
+
+=item .return <var>.somemethod(args)
+
+Tail call: call a function or method and return from the sub with the
+function or method call return values.
+
+Internally, the call stack doesn't increase because of a tail call, so
+you can write recursive functions and not have stack overflows.
+
+=back
+
+=head2 Parameter Passing and Getting Flags
+
See L<PDD03|pdds/pdd03_calling_conventions.pod> for a description of
-the meaning of the flag bits bits C<SLURPY>, C<OPTIONAL>, C<OPT_FLAG>,
-and C<FLAT>, which correspond to the claling convention flags
+the meaning of the flag bits C<SLURPY>, C<OPTIONAL>, C<OPT_FLAG>,
+and C<FLAT>, which correspond to the calling convention flags
C<:slurpy>, C<:optional>, C<:opt_flag>, and C<:flat>.
[TODO - once these flag bits are solidified by long-term use, then we
@@ -347,6 +393,12 @@
Translate to B<if x, identifier> or B<unless ..>.
+=item if null <var> goto <identifier>
+
+=item unless null <var> goto <identifier>
+
+Translate to B<if_null x, identifier> or B<unless_null ..>.
+
=item if <var> <relop> <var> goto <identifier>
The B<relop> B<<, <=, ==, != E<gt>= E<gt>> translate to the PASM opcodes
@@ -420,6 +472,10 @@
B<set_addr var, var>
+=item <var> = null
+
+B<null <var>>
+
=back
=head1 SEE ALSO
