Author: lwall Date: 2008-12-20 03:06:20 +0100 (Sat, 20 Dec 2008) New Revision: 24506
Modified: docs/Perl6/Spec/S19-commandline.pod Log: [S19] random annotations for [particle]++'s consideration Modified: docs/Perl6/Spec/S19-commandline.pod =================================================================== --- docs/Perl6/Spec/S19-commandline.pod 2008-12-19 23:21:32 UTC (rev 24505) +++ docs/Perl6/Spec/S19-commandline.pod 2008-12-20 02:06:20 UTC (rev 24506) @@ -31,6 +31,8 @@ L<Synopsis 25|S25-portability> (TBD). +[my notes/conjectures below are all in square brackets --TimToady] + =head1 Command Line Elements The command line is broken down into two basic elements: a I<compiler>, and @@ -41,6 +43,18 @@ Perl 6 does not do any processing of the I<compiler> portion of the command line, but it is made available at run-time in the read-only C<$*VM> variable. +[ It seems wrong to call this a I<compiler> when (from the Unix point +of view) it's just a program to run, and the compilation may have +happened long ago. Maybe I<program> or I<processor> instead. Which +phases are invoked may well depend on the nature of the file that is +specified as a program to be interpreted, as well as the requested +form of output.] + +[ $*VM is certainly wrong for the original compiler. It would have to +be $?VM, though that may be wrong too. One could imagine a particular +compiler that ran on multiple VMs, in which case some other variable +would be needed to indicate the original compiler.] + Command line I<arguments> are further broken down into I<options> and I<values>. Unlike Perl 5, I<options> and I<values> may be intermixed on the command line. This mirrors the Perl 6 argument syntax for Routines, which @@ -49,7 +63,9 @@ command line options together, even though this is not enforced, in order to avoid confusion. +[ This policy may be counter-intuitive to current comand-line cultures. ] + =head1 Backward (In)compatibility Muscles have a long memory. You may find yourself typing your favorite Perl 5 @@ -82,6 +98,11 @@ Single-letter options must not be clustered. C<-ab> never means C<-a -b> +[Some systems allow clustering of - options but not of -- options. Obviously +such systems disallow multicharacter - options and require --foo instead of +-foo. Another option is to allow :a:b as a form of bundling since that's +unambiguous from a p6 point of view.] + =item * Options must begin with one of the following symbols: C<< < -- - + : > >> @@ -95,12 +116,19 @@ Options may be negated with C</> or C<!>, for example C<:/name> +[:/name reminds me more of an end tag than a negated, but I see +why you want it, given the history of history characters...interestingly, +:0name has the same effect in current p6, since we generalized :3x +and such.] + =item * The special option C<--> signals the parser to stop option processing. Arguments following C<--> are always parsed as a list of values, even if they look like valid options. +[Distinguish here from --foo options? "...with no identifier" or some such] + =back @@ -108,11 +136,13 @@ delimiters on either end, allowing options to be passed through for later processing, and are parsed with the following rules: +[ s/for later processing/to specified subsystems/ would be clearer, I think. ] + =over 4 =item * -The opening delimeter begins with C<++>, the closing delimiter with C<-->. +The opening delimiter begins with C<++>, the closing delimiter with C<-->. =item * @@ -128,11 +158,28 @@ run-time component. For example, C<++RTS=parser ... --RTS=parser> directs the delimited options to the parser (see L</"Option Reference"> below). +[This seems a bit bogus insofar as --RTS=parser is still officially +ambiguous with switches inside. Plus it's not at all clear why this +isn't just ++PARSER ... --PARSER. What's the parser got to do with +the run-time system? + +Other options that keep the metasyntax further away from ordinary switch +syntax: + + :+PARSER ... :-PARSER + ++BEGIN=PARSER ... ++END=PARSER + ++PARSER ... ++/PARSER + +The last one having reverberations of html tags. But in any case +I think I like the consistent ++ escape for metasyntax.] + =item * When an optional parameter is given, it must be specified on both the opening and closing delimited options. +[To me this just means you allow names with = in the middle.] + =item * If the closing delimiter is omitted, the rest of the command line is consumed. @@ -141,13 +188,22 @@ The C<--> option has no effect within a delimited option. +[How do you know? That's up to the subprocessor, surely? What if they +want to treat the rest of the arguments as data even if they happen +to start with '--'? I think what you mean is that it does not suppress +searching for the closer.] + =item * Delimited options cannot be negated. =back +[From the P6 viewpoint, these options should probably be shoved into +context variables and be invisible to MAIN except as %+OPTS<PARSER> +or @+PARSER_ARGS or some such.] + Values are parsed with the following rules: =over 4 @@ -168,6 +224,10 @@ Multiple values are passed using commas without intervening whitespace, as in C<-option=val1,'val 2',etc> +[Again, -option instead of --option makes it very difficult to detect +the attempt to use P5 options. This is probably why GNU rules require +-- on long options. We should consider doing the same.] + =back @@ -225,16 +285,31 @@ B<Mode> flags set the operational mode of the compiler (e.g. I<--doc>, I<-e>). Only one mode flag may be specified on the command line. +[Again, we might be long gone from the "compiler" here, so a better word +is needed.] + =item * B<Dynamic> flags may be set on the command line, via the I<PERL6OPT> environment variable, or within a file. +[What file? We need to be Very Careful not to delegate the identity of +the current language to anything outside of P6. I would very much hate +to see anything resembling a .perl6rc file.] + =item * B<Static> flags may be set only on the command line, and affect the entire run of the compiler. +[s/comiler/whatever/] + +[I think this Static/Dynamic distinction is rather meaningless and +confusing. Certain commitments will be made by certain phases of +compilation/linking/running, and every switch is dynamic before the +commitment, static after. And Mode flags are just the ones that +commit so fast they exclude alternatives, seems like...] + =back For more on options and their classifications, see section @@ -252,6 +327,10 @@ {{ TODO more details needed }} +[Would like to see a use case for this mechanism. The whole Services +concept seems very nebulous, especially when you start giving services +names like "Awk"..."Autoloop" would be more meaningful.] + =head1 Option Reference Perl 6 options, descriptions, categories, and services @@ -268,6 +347,8 @@ Notes: Annotates function produced by -n | -p +[confusingly different from p5's -a switch, which turns on autosplit.] + =item --option-parser file Add a command-line parsing module. @@ -282,6 +363,9 @@ {{ TODO more details needed }} +[maybe more like ++CMD --your_ad_here ++/CMD] + + =item -c Check syntax. @@ -292,6 +376,13 @@ Notes: exits early, before MAIN(). +[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 @@ -300,6 +391,8 @@ Service: Doc +[++COMPILER --CHECK_compiles_ok --CHECK_dump_perldoc ++/COMPILER] + =item -Dletters, -Dnumbers Set debugging flags. @@ -313,6 +406,9 @@ breaking into parrot, enabling flags of perl 6 introspection, enabling a perl level debugger. So... which one? Need a debugger spec to guide this. +[little rhyme or reason to the p5 flags here, so maybe we can dehuffmanize +debugging switches and hold -D in reserve.] + =item -e commandline Execute a single-line program. @@ -326,6 +422,10 @@ Actually combines all source from all -e parameters, then compiles when there are no more -e. Assigns the generated function to MAIN. +[Not really a Mode in the sense you've defined it, but an input +redirection of a vaguely here-docish flavor. You could combine it +with -c or --doc for instance, so not exclusive.] + =item -F string Pattern to split on (used with -a). Accepts unicode strings (as long as your @@ -339,6 +439,9 @@ 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 -h, --help Print summary of options. @@ -347,6 +450,8 @@ Service: Usage +[++CMD --printhelp --exit ++/CMD or some such] + =item -I Prepend directory to @*INC. @@ -357,6 +462,10 @@ Notes: this is unspecced elsewhere, so may not survive long. +[at best, @*INC will only be the user's ad hoc libraries. The API for +searching the standard lib will not be defined in terms of @*INC so that +we can enforce the standard library policies laid out in S11.] + =item -m[-]module, -M[-]module, -M[-]'module ...', -[mM][-]module=arg[,arg]... use/no module. @@ -369,6 +478,11 @@ Or maybe there can be a UNIVERSAL service which knows about other services and is built into the interpreter. No looking at disk required? +[I have no idea what you're talking about here...these switch are in +the same category as -n and -p; they imply additional wrapping of +the given code with extra "use" directives. The syntax could probably +use some refactoring though.] + =item -n Act like awk. @@ -379,6 +493,10 @@ Notes: Consumes the -e function, returns a new function and assigns to MAIN. +[has nothing to do with -e or MAIN] + +[more like ++PARSER --prelude=Perl6_loop_noprint ++/PARSER] + =item -p Act like sed. @@ -389,6 +507,10 @@ Notes: Consumes the -e function, returns a new function and assigns to MAIN. +[has nothing to do with -e or MAIN] + +[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. @@ -397,6 +519,8 @@ Service: n/a +[You may have noticed I like just ++string ... ++/string now :) ] + =item -S Use path to search for program. @@ -405,6 +529,9 @@ 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 Display compiler name, version, patchlevel, etc. @@ -413,6 +540,11 @@ Service: Usage +[maybe wants to propagate -v to ++CMD, ++PARSER, ++RTS, and any +other known subsystems?] + +[or maybe -v is ++TOWHOMITMAYCONCERN --print_version_and_exit] + =item -V Display configuration details. @@ -421,6 +553,8 @@ Service: Usage +[likewise] + =back @@ -431,23 +565,46 @@ component of Perl. Perl itself does not parse these options, but makes them available to run-time components. +[Note that with my proposed system you can still nest without the artificial =: + ++RTS ++GC -generational ++/GC ++/RTS +] + the C<=string> variation allows for disabmiguation when the run-time system also allows the parsing of an option named C<--RTS>. For example, C<perl ++RTS=outer -a :b +C --RTS foo bar --RTS=outer> makes sure the run-time system receives C<-a :b +C --RTS foo bar>. +[perl ++RTS -a :b +C --RTS ++/RTS] + Additionally, some implementations may use this variation to pass arguments to particular subsystems. For example, Rakudo Perl may choose to implement C<perl ++RTS=parrot --runcore=gc-debug -t 7 --RTS=parrot ++RTS=PGE --disable-keepall --optimize --RTS=PGE> to mean C<--runcore=gc-debug -t 7> gets passed to parrot, and C<--disable-keepall --optimize> gets passed to PGE. +[perl ++PARROT --runcore=gc-debug -t 7 ++/PARROT ++PGE --disable-keepall --optimize ++/PGE> + {{ -jg should certain string prefixes or perhaps uppercase strings be reserved for this purpose? }} +[doesn't seem very necessary, if we make sure ++ has its own namespace. currently +that namespace is quite barren. we wouldn't even necessarily need to enforce uppercase, +since + perl ++parrot --runcore=gc-debug -t 7 ++/parrot ++pge --disable-keepall --optimize ++/pge + +is just about as readable, especially if written: + + perl ++parrot --runcore=gc-debug -t 7 ++/parrot \ + ++pge --disable-keepall --optimize ++/pge \ + foo bar baz + + +or some such.] + + =head1 Environment Variables Environment variables may be used to the same effect as command-line @@ -466,6 +623,9 @@ Note: this is speculative, as library loading is not yet specified. +[except insofar as S11 mandates various behaviors incompatible with +mere directory probing...] + =item PERL6OPT Default command-line arguments. Arguments found here are prepended to the @@ -502,13 +662,42 @@ for instance to specify the equivalent of perl 5's C<$/ = \32768;>. so far, i don't have a solution, but perhaps pass a closure that evaluates to an int? +[this should try to use whatever option does the same thing to a new +filehandle when S16 is further developed.] + do i need to address any unicode concerns? +[You can try "all command line arguments are assumed to be in unicode +unless proven otherwise" and see how well it flies. :) but this starts +to get into filenames-are-blobs kind of issues...maybe we need a way +of marking arguments as needing to be encoded into a Buf. but for sanity +we must try to settle on unicode as the default expectation. I hope POSIX +dies before Perl 6 does...] + +loading a switch parsing module by a switch, instead of using the default. +maybe via ++RTS, since it needs to happen *before* switches are evaluated. + +[suggest ++CMD --use_cmd_module ++/CMD] + 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: