Author: particle
Date: 2008-12-31 00:55:46 +0100 (Wed, 31 Dec 2008)
New Revision: 24697
Modified:
docs/Perl6/Spec/S19-commandline.pod
Log:
[S19] update option reference, including: longnames for all options; desugaring
for some options; new options (-e6, -o, -O, -T)
Modified: docs/Perl6/Spec/S19-commandline.pod
===================================================================
--- docs/Perl6/Spec/S19-commandline.pod 2008-12-30 23:30:54 UTC (rev 24696)
+++ docs/Perl6/Spec/S19-commandline.pod 2008-12-30 23:55:46 UTC (rev 24697)
@@ -15,7 +15,7 @@
Maintainer: Jerry Gay <jerry....@rakudoconsulting.com>
Date: 12 Dec 2008
Last Modified: 30 Dec 2008
- Version: 4
+ Version: 5
This is a draft document. This document describes the command line interface.
It has changed extensively from previous versions of Perl in order to increase
@@ -328,88 +328,65 @@
=over 4
-=item -a
+=item --autosplit, -a
Turns on autosplit mode.
-Category: Dynamic
-
Service: Autoloop
Notes: Annotates function produced by -n | -p
-[confusingly different from p5's -a switch, which turns on autosplit.]
+=item ++argsproc [options, values] ++/argsproc
-=item --option-parser file
+{{TODO don't like this name, but don't like ++cmd either}}
-Add a command-line parsing module.
+Add a command-line processor.
-Category: Static
-
Service: Option
Notes: When this option is parsed, it immediately triggers an action that
could affect the remainder of the parse. Therefore, it's a good idea to put
-this option/value pair as early as possible in the argument list.
+this option as early as possible in the argument list.
-{{ TODO more details needed }}
+{{TODO more details needed}}
-[maybe more like ++CMD --your_ad_here ++/CMD]
+=item --check-syntax, -c
-=item -c
+Check syntax, then exit.
-Check syntax.
-
-Category: Mode
-
Service: Runtime
-Notes: exits early, before MAIN().
+Notes: Desugars to C<++compiler '--CHECK{ compiles_ok(); exit; }' ++/compiler>
-[exits long before MAIN(), at CHECK time. Also, not exclusive
-with other "Modes". All it does is suppress running.]
-
-[idea; maybe switches like -c should be documented to
-desugar to ++COMPILER --CHECK_compiles_ok ++/COMPILER or whatever.
-This might help clarify which "pass" commits to the value.]
-
=item --doc
perldoc
-Category: Mode
-
Service: Doc
-[++COMPILER --CHECK_compiles_ok --CHECK_dump_perldoc ++/COMPILER]
+Notes: Desugars to
+C<++compiler '--CHECK{ compiles_ok(); }' '--CHECK{ dump_perldoc(); }'
++/compiler>
-=item -Dletters, -Dnumbers
+{{TODO what do i pass to dump_perldoc? C<$+ARGS>, maybe?}}
+=item ++debugger [switches, flags] ++/debugger
+
Set debugging flags.
-Category: ?
-
Service: Debugger
-Notes: Should this load the debugger? No idea what should happen if the
-interpeter is built without debugging enabled. There are multiple levels:
-breaking into parrot, enabling flags of perl 6 introspection, enabling a
-perl level debugger. So... which one? Need a debugger spec to guide this.
+Notes: At least it's a start. Need a debugger spec for more.
-[little rhyme or reason to the p5 flags here, so maybe we can dehuffmanize
-debugging switches and hold -D in reserve.]
+=item --execute, -e commandline
-=item -e commandline
+Execute a single-line program. Multiple C<-e> options may be chained together,
+each one representing an input line with an implicit newline at the end.
-Execute a single-line program.
-
-Category: Mode
-
Service: Runtime
-Notes: Returns a function that's executed unless otherwise modified by awk
-service's -p , -n, -a, -F.
+Notes: Returns a function that's executed unless otherwise modified by
+Autoloop service's -p , -n, -a, -F.
Actually combines all source from all -e parameters, then compiles when
there are no more -e. Assigns the generated function to MAIN.
@@ -417,38 +394,34 @@
redirection of a vaguely here-docish flavor. You could combine it
with -c or --doc for instance, so not exclusive.]
-=item -F string
+=item --execute-lax, -e6
+Execute in lax mode, without strictures and warnings enabled.
+See L<Synopsis 11|S11-modules.pod/"Forcing Perl 6"> for details.
+
+Service: Runtime
+
+=item --autoloop-split, -F [string, closure, etc]
+
Pattern to split on (used with -a). Accepts unicode strings (as long as your
shell lets you pass them). Allows passing a closure
-(e.g. -F "{use Text::CSV}"). awk's not better any more :)
+(e.g. -F "{use Text::CSV}"). Awk's not better any more :)
-Category: Dynamic
-
Service: Autoloop
Notes: Substitutes a function for the default function which
is { split ' ' } or whatever.
-[here it's assuming the original -a behavior, not what is
-specced for -a above.]
+=item --help, -h
-=item -h, --help
+Print summary of options. Desugars to C<++cmd --print-help --exit ++/cmd>.
-Print summary of options.
-
-Category: Mode
-
Service: Usage
-[++CMD --printhelp --exit ++/CMD or some such]
+=item --include, -I
-=item -I
-
Prepend directory to @*INC.
-Category: Dynamic
-
Service: Lib
Notes: this is unspecced elsewhere, so may not survive long.
@@ -459,10 +432,10 @@
=item -m[-]module, -M[-]module, -M[-]'module ...', -[mM][-]module=arg[,arg]...
+{{TODO needs new or extended syntax}}
+
use/no module.
-Category: Dynamic
-
Service: Meta
Notes: Maybe this happens before or affects which services are loaded.
@@ -474,61 +447,54 @@
the given code with extra "use" directives. The syntax could probably
use some refactoring though.]
-=item -n
+=item --autoloop-no-print, -n
Act like awk.
-Category: Dynamic
-
Service: Autoloop
-Notes: Consumes the -e function, returns a new function and assigns to MAIN.
+Notes: Desugars to C<++parser --prelude=Perl6-autoloop-no-print ++/parser>.
-[has nothing to do with -e or MAIN]
+=item --output-format, -O [format]
-[more like ++PARSER --prelude=Perl6_loop_noprint ++/PARSER]
+Specify the file format for the output file requested with C<--output-file>.
+Defaults to 'exe', which represents the target platform's idea of an
+executable. Other valid values are implementation-specific, so consult the
+documentation for your compiler toolchain.
-=item -p
+=item --output-file, -o [filename]
-Act like sed.
+Compile to a file, rather than run immediately. If no filename is specified,
+STDOUT is used. Specify the output format with C<--output-format>.
-Category: Dynamic
+=item autoloop-print, -p
+Act like sed.
+
Service: Autoloop
-Notes: Consumes the -e function, returns a new function and assigns to MAIN.
+Notes: Desugars to C<++parser --prelude=Perl6-autoloop-print ++/parser>.
-[has nothing to do with -e or MAIN]
+=item --search-path, -S
-[more like ++PARSER --prelude=Perl6_loop_print ++/PARSER]
-
-=item ++RTS options --RTS, ++RTS=string options --RTS=string
-
-Send options to the run-time system. See L</"Run-time System"> below.
-
-Category: Dynamic
-
-Service: n/a
-
-[You may have noticed I like just ++string ... ++/string now :) ]
-
-=item -S
-
Use path to search for program.
-Category: Static
-
Service: Runtime
[you need a story for when the first argument is treated as
the program name. e.g. when you *don't* use -e to supply the program.]
-=item -v, --version
+=item --taint, -T
-Display program name, version, patchlevel, etc.
+Turns on "taint" checking. See L<...> for details.
-Category: Mode
+Notes: Commits very early. Recommend putting this option as early on the
+command-line as possible.
+=item --version, -v
+
+Display program name, version, patchlevel, etc.
+
Service: Usage
[maybe wants to propagate -v to ++CMD, ++PARSER, ++RTS, and any
@@ -536,12 +502,12 @@
[or maybe -v is ++TOWHOMITMAYCONCERN --print_version_and_exit]
-=item -V
+{{TODO}}
+=item --verbose-config, -V
+
Display configuration details.
-Category: Mode
-
Service: Usage
[likewise]
@@ -672,23 +638,9 @@
sandboxing? maybe-r
-[need a -T story too; gotta have tainting even if we don't do sandboxing]
-
env var? maybe -E
[could be posed in terms of substituting a different prelude]
-
--e multiple args or multiple times, to affect later -e's
-
-[suggest sticking to p5 policy that each -e represents one input line with
-an implicit \n on the end]
-
-[-o for separately compiled output, .pbc or .so or .jar or .exe or whatever?]
-
-[some variant of -o that requests a particular output format without
-having to specify an extension, or even if a filename if sent to
-stdout. maybe -O=pbc -o=myfilename or some such. ]
-
}}
=for vim:set expandtab sw=4:
