Author: particle
Date: 2008-12-31 00:55:46 +0100 (Wed, 31 Dec 2008)
New Revision: 24697

[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 <>
   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
-Category: Mode
 Service: Doc
-[++COMPILER --CHECK_compiles_ok --CHECK_dump_perldoc ++/COMPILER]
+Notes: Desugars to
+C<++compiler '--CHECK{ compiles_ok(); }' '--CHECK{ dump_perldoc(); }' 
-=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
+=item --verbose-config, -V
 Display configuration details.
-Category: Mode
 Service: Usage
@@ -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:

Reply via email to