<commit_before>
=encoding utf8

=head1 TITLE

DRAFT: Synopsis 19: Command Line Interface


=head1 AUTHORS

    <NAME> <<EMAIL>>

=head1 VERSION

    Created: 12 Dec 2008

    Last Modified: 26 Oct 2009
    Version: 26

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
clarity, consistency, and extensibility. Many of the syntax revisions are
extensions, so you'll find that much of the Perl 5 syntax embedded in your
muscle memory will still work.

Notable features described in the sections below include:

=over 4

=item *

A smart default command-line processor in the core

=item *

All options have a long, descriptive name for increased clarity

=item *

Common options have a short, single-character name, and allow clustering

=item *

Extended option syntax provides the ability to set boolean true/false

=item *

New C<++> metasyntax allows options to be passed through to subsystems

=back

This interface to Perl 6 is special in that it occurs at the intersection of
the program and the operating system's command line shell, and thus is not
accessed via a consistent syntax everywhere. A few assumptions are made here,
which will hopefully stand the test of time: All command-line arguments are
assumed to be in Unicode unless proven otherwise; and Perl is born of Unix,
and as such the syntax presented in this document is expected to work in a
Unix-style shell. To explore the particularities of other operating systems,
see L<Synopsis 25|S25-portability> (TBD).


=head1 Command Line Elements

The command line is broken down into two basic elements: a I<program>, and
I<arguments>. Each command line element is whitespace separated, so elements
containing whitespace must be quoted. The I<program> processes the arguments
and performs the requested actions. It looks something like F</usr/bin/perl6>,
F<parrot perl6.pbc>, or F<rakudo> (or F<mono niecza.exe>, et cetera),
and is followed by zero or more I<arguments>.
Perl 6 does not do any processing of the I<program> portion of the command
line, but it is made available at run-time via the C<< PROCESS::<$PROGRAM_NAME> >>
variable.

Command line I<arguments> are broken down into I<options> and I<values>.
Each option may take zero or more values. After all options have been
processed, the remaining values (if any) generally consist of the name of a
script for Perl to execute, followed by arguments for that script. If no
values remain, Perl 6 implicitly opens STDIN to read the script. If you wish
to pass arguments to a script read from STDIN, you must specify STDIN by name
(C<-> on most operating systems).


=head1 Backward (In)compatibility

You may find yourself typing your favorite Perl 5 options, even after
Christmas has arrived.  As you'll see below, common options are provided
which behave similarly.  Less common options, however, may not be available
or may have changed syntax.  If you provide Perl with unrecognized command-line
syntax, Perl gives you a friendly error message.  If the unrecognized
syntax is a valid Perl 5 option, Perl provides helpful suggestions to allow
you to perform the same action using the current syntax.


=head2 Unchanged Syntactic Features

Several features have not changed from Perl 5, including:

=over 4

=item *

The most common options have a single-character short name

=item *

Single-character options may be clustered with the same syntax and semantics

=item *

Many command-line options behave similarly, for example:

  Option...                            Still means...
  -a                                   Autosplit
  -c                                   Check syntax
  -e *line*                            Execute
  -F *expression*                      Specify autosplit field separator
  -h                                   Display help and exit
  -I *directory*[,*directory*[,...]]   Add include paths
  -n                                   Act like awk
  -p                                   Act like sed
  -S                                   Search PATH for script
  -T                                   Enable taint mode
  -v                                   Display version info
  -V                                   Display verbose config info

All of these options have extended syntax, and some may have slightly
different semantics, so see L</"Option Reference"> below for the details.

=back


=head2 Removed Syntactic Features

Some Perl 5 command-line features are no longer available, either because
there's a new and different way to do it in Perl 6, or because they're
no longer relevant.  Here's a breakdown of what's been removed:

=over 4

=item -0 *octal/hex*

Sets input record separator.  Missing due to lack of specification in
L<Synopsis 16|S16-io>.  There is a comment about this in the L</"Notes">
section at the end of this document.

=item -C *number/list*

Control unicode features.  Perl 6 has unicode semantics, and assumes a
UTF-8 command-line interface (until proven otherwise, at which point this
functionality may be readdressed).

=item -d, -dt, -d:foo, -D, etc.

Debugging commands.  Replaced with the C<++BUG> metasyntactic option.

=item -E *line*

Execute a line of code, with all features enabled.  This is specific to
Perl 5.10, and not relevant to Perl 6, where C<-e> performs this function.

=item -i *extension*

Modify files in-place.  Haven't thought about it enough to add yet, but
I'm certain it has a strong following. {{TODO review decision here}}

=item -l

Enable automatic line-ending processing.  This is the default behavior.

=item -M *module*, -m *module*, etc.

use/no module.  Replaced by C<--use>.

=item -P

Run option through C preprocessor. This caused problems for Perl 5, and is completely obsolete now.

=item -s

Enable rudimentary switch parsing.  By default, Perl 6 parses the
arguments passed to a script using the signature supplied by the user
in the MAIN routine (see L<S06-subroutines/"Declaring a MAIN subroutine">).

=item -t

Enable taint warnings mode.  Taint mode needs more thought, but it's
much more likely that the C<-T> switch will take options rather than
use a second command-line flag to implement related behavior.

=item -u

Dump the core after parsing the program. This has been deemed obsolete.

=item -U

Allow unsafe operations.  This is extremely dangerous and infrequently
used, and doesn't deserve its own command-line option.

=item -w

Enable warnings.  This is the default behavior.

=item -W

Enable all warnings.  This is infrequently used, and doesn't deserve its
own command-line option.

=item -X

Disable all warnings.  This is infrequently used, and doesn't deserve its
own command-line option.

=back


=head1 Options and Values

Command line options are parsed using the following rules:

=over 4

=item *

Options must begin with one of the following symbols: C<-->, C<->, or C<:>.

=item *

Options are case sensitive. C<-o> and C<-O> are not the same option.

=item *

All options have a multi-character, descriptive name for increased clarity.
Multi-character option names always begin with C<--> or C<:>.

=item *

Common options have a short, one-character name for speed.
Single-character names always begin with C<->.

=item *

Single-character options may be clustered. C<-ab> means C<-a -b>. When a
single-character option which requires a value is clustered, the option may
appear only in the final position of the cluster.

=item *

Options may be negated with C</>, for example C<--/name>, C<:/name>, C<-/n>.
Negated single-character options cannot appear in a cluster.  In practice,
negated options are rare anyway, as most boolean options default to False.

=item *

Option names follow Perl 6 identifier naming convention, except C<'> is not
allowed, and single-character options may be any character or number.

=item *

The special option C<--> signals the parser to stop option processing.
Arguments following a bare C<--> (with no identifier) are always parsed as
a list of values, even if they look like valid options.

=back


Delimited options allow you to transparently pass one or more options through to
a subsystem, as specified by the special options that delimit those options.
They are parsed according to the following rules:

=over 4

=item *

The opening and closing delimiters begin with two or more plus characters,
for example C<++>.  You'll usually use two plus characters, but more are
allowed to avoid ambiguity when nesting delimited options.

=item *

Opening and closing delimited option names follow option identifier naming
convention, defined above.

=item *

If the closing delimiter is omitted, the rest of the command line is consumed.

=item *

Inside a delimited option, the C<--> option does not suppress searching for
the closing delimiter.  That is, only the rest of the arguments within
the delimiters are treated as values.

=item *

Eager matching semantics are used, so the first closing delimiter found
completes the match.

=item *

Delimited options cannot be negated.  However, the final delimiter takes
a slash indicating the termination of the delimited processing, much
like a closing HTML tag.

=back

These options are made available in dynamic variables matching their name,
and are invisible to C<MAIN()> except as C<< %*OPTS<name> >>.  For example:

  ++PARSER --setting=Perl6-autoloop-no-print ++/PARSER

is available inside your script as C<< %*OPTS<PARSER> >>, and contains
C<--setting=Perl6-autoloop-no-print>.  Since eager matching is used, if you
need to pass something like:

  ++foo -bar ++foo baz ++/foo ++/foo

you'll end up with

  %*OPTS<foo> = '-bar ++foo baz';

which is probably not what you wanted. Instead, add extra C<+> characters

  +++foo -bar ++foo baz ++/foo +++/foo

which will give you

  %*OPTS<foo> = '-bar ++foo baz ++/foo';

allowing you to properly nest delimited options.

The actual storage location of C<%*OPTS> may be either in C<< PROCESS::<%OPTS> >>
or C<< GLOBAL::<%OPTS> >>, depending on how the process sets up its interpreters.


Values are parsed with the following rules:<commit_msg>[S19] break up unintentional pod formatting code<commit_after>
=encoding utf8

=head1 TITLE

DRAFT: Synopsis 19: Command Line Interface


=head1 AUTHORS

    <NAME> <<EMAIL>>

=head1 VERSION

    Created: 12 Dec 2008

    Last Modified: 26 Oct 2009
    Version: 26

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
clarity, consistency, and extensibility. Many of the syntax revisions are
extensions, so you'll find that much of the Perl 5 syntax embedded in your
muscle memory will still work.

Notable features described in the sections below include:

=over 4

=item *

A smart default command-line processor in the core

=item *

All options have a long, descriptive name for increased clarity

=item *

Common options have a short, single-character name, and allow clustering

=item *

Extended option syntax provides the ability to set boolean true/false

=item *

New C<++> metasyntax allows options to be passed through to subsystems

=back

This interface to Perl 6 is special in that it occurs at the intersection of
the program and the operating system's command line shell, and thus is not
accessed via a consistent syntax everywhere. A few assumptions are made here,
which will hopefully stand the test of time: All command-line arguments are
assumed to be in Unicode unless proven otherwise; and Perl is born of Unix,
and as such the syntax presented in this document is expected to work in a
Unix-style shell. To explore the particularities of other operating systems,
see L<Synopsis 25|S25-portability> (TBD).


=head1 Command Line Elements

The command line is broken down into two basic elements: a I<program>, and
I<arguments>. Each command line element is whitespace separated, so elements
containing whitespace must be quoted. The I<program> processes the arguments
and performs the requested actions. It looks something like F</usr/bin/perl6>,
F<parrot perl6.pbc>, or F<rakudo> (or F<mono niecza.exe>, et cetera),
and is followed by zero or more I<arguments>.
Perl 6 does not do any processing of the I<program> portion of the command
line, but it is made available at run-time via the C<< PROCESS::<$PROGRAM_NAME> >>
variable.

Command line I<arguments> are broken down into I<options> and I<values>.
Each option may take zero or more values. After all options have been
processed, the remaining values (if any) generally consist of the name of a
script for Perl to execute, followed by arguments for that script. If no
values remain, Perl 6 implicitly opens STDIN to read the script. If you wish
to pass arguments to a script read from STDIN, you must specify STDIN by name
(C<-> on most operating systems).


=head1 Backward (In)compatibility

You may find yourself typing your favorite Perl 5 options, even after
Christmas has arrived.  As you'll see below, common options are provided
which behave similarly.  Less common options, however, may not be available
or may have changed syntax.  If you provide Perl with unrecognized command-line
syntax, Perl gives you a friendly error message.  If the unrecognized
syntax is a valid Perl 5 option, Perl provides helpful suggestions to allow
you to perform the same action using the current syntax.


=head2 Unchanged Syntactic Features

Several features have not changed from Perl 5, including:

=over 4

=item *

The most common options have a single-character short name

=item *

Single-character options may be clustered with the same syntax and semantics

=item *

Many command-line options behave similarly, for example:

  Option...                            Still means...
  -a                                   Autosplit
  -c                                   Check syntax
  -e *line*                            Execute
  -F *expression*                      Specify autosplit field separator
  -h                                   Display help and exit
  -I *directory*[,*directory*[,...]]   Add include paths
  -n                                   Act like awk
  -p                                   Act like sed
  -S                                   Search PATH for script
  -T                                   Enable taint mode
  -v                                   Display version info
  -V                                   Display verbose config info

All of these options have extended syntax, and some may have slightly
different semantics, so see L</"Option Reference"> below for the details.

=back


=head2 Removed Syntactic Features

Some Perl 5 command-line features are no longer available, either because
there's a new and different way to do it in Perl 6, or because they're
no longer relevant.  Here's a breakdown of what's been removed:

=over 4

=item -0 *octal/hex*

Sets input record separator.  Missing due to lack of specification in
L<Synopsis 16|S16-io>.  There is a comment about this in the L</"Notes">
section at the end of this document.

=item -C *number/list*

Control unicode features.  Perl 6 has unicode semantics, and assumes a
UTF-8 command-line interface (until proven otherwise, at which point this
functionality may be readdressed).

=item -d, -dt, -d:foo, -D, etc.

Debugging commands.  Replaced with the C<++BUG> metasyntactic option.

=item -E *line*

Execute a line of code, with all features enabled.  This is specific to
Perl 5.10, and not relevant to Perl 6, where C<-e> performs this function.

=item -i *extension*

Modify files in-place.  Haven't thought about it enough to add yet, but
I'm certain it has a strong following. {{TODO review decision here}}

=item -l

Enable automatic line-ending processing.  This is the default behavior.

=item -M *module*, -m *module*, etc.

use/no module.  Replaced by C<--use>.

=item -P

Run option through C preprocessor. This caused problems for Perl 5, and is completely obsolete now.

=item -s

Enable rudimentary switch parsing.  By default, Perl 6 parses the
arguments passed to a script using the signature supplied by the user
in the MAIN routine (see L<S06-subroutines/"Declaring a MAIN subroutine">).

=item -t

Enable taint warnings mode.  Taint mode needs more thought, but it's
much more likely that the C<-T> switch will take options rather than
use a second command-line flag to implement related behavior.

=item -u

Dump the core after parsing the program. This has been deemed obsolete.

=item -U

Allow unsafe operations.  This is extremely dangerous and infrequently
used, and doesn't deserve its own command-line option.

=item -w

Enable warnings.  This is the default behavior.

=item -W

Enable all warnings.  This is infrequently used, and doesn't deserve its
own command-line option.

=item -X

Disable all warnings.  This is infrequently used, and doesn't deserve its
own command-line option.

=back


=head1 Options and Values

Command line options are parsed using the following rules:

=over 4

=item *

Options must begin with one of the following symbols: C<-->, C<->, or C<:>.

=item *

Options are case sensitive. C<-o> and C<-O> are not the same option.

=item *

All options have a multi-character, descriptive name for increased clarity.
Multi-character option names always begin with C<--> or C<:>.

=item *

Common options have a short, one-character name for speed.
Single-character names always begin with C<->.

=item *

Single-character options may be clustered. C<-ab> means C<-a -b>. When a
single-character option which requires a value is clustered, the option may
appear only in the final position of the cluster.

=item *

Options may be negated with C</>, for example C<--/name>, C<:/name>, C<-/n>.
Negated single-character options cannot appear in a cluster.  In practice,
negated options are rare anyway, as most boolean options default to False.

=item *

Option names follow Perl 6 identifier naming convention, except C<'> is not
allowed, and single-character options may be any character or number.

=item *

The special option C<--> signals the parser to stop option processing.
Arguments following a bare C<--> (with no identifier) are always parsed as
a list of values, even if they look like valid options.

=back


Delimited options allow you to transparently pass one or more options through to
a subsystem, as specified by the special options that delimit those options.
They are parsed according to the following rules:

=over 4

=item *

The opening and closing delimiters begin with two or more plus characters,
for example C<++>.  You'll usually use two plus characters, but more are
allowed to avoid ambiguity when nesting delimited options.

=item *

Opening and closing delimited option names follow option identifier naming
convention, defined above.

=item *

If the closing delimiter is omitted, the rest of the command line is consumed.

=item *

Inside a delimited option, the C<--> option does not suppress searching for
the closing delimiter.  That is, only the rest of the arguments within
the delimiters are treated as values.

=item *

Eager matching semantics are used, so the first closing delimiter found
completes the match.

=item *

Delimited options cannot be negated.  However, the final delimiter takes
a slash indicating the termination of the delimited processing, much
like a closing HTML tag.

=back

These options are made available in dynamic variables matching their name,
and are invisible to C<MAIN()> except as C<< %*OPTSZ<><name> >>.  For example:

  ++PARSER --setting=Perl6-autoloop-no-print ++/PARSER

is available inside your script as C<< %*OPTSZ<><PARSER> >>, and contains
C<--setting=Perl6-autoloop-no-print>.  Since eager matching is used, if you
need to pass something like:

  ++foo -bar ++foo baz ++/foo ++/foo

you'll end up with

  %*OPTS<foo> = '-bar ++foo baz';

which is probably not what you wanted. Instead, add extra C<+> characters

  +++foo -bar ++foo baz ++/foo +++/foo

which will give you

  %*OPTS<foo> = '-bar ++foo baz ++/foo';

allowing you to properly nest delimited options.

The actual storage location of C<%*OPTS> may be either in C<< PROCESS::<%OPTS> >>
or C<< GLOBAL::<%OPTS> >>, depending on how the process sets up its interpreters.


Values are parsed with the following rules:
{'fraction_non_alphanumeric': 0.0660280029476787, 'fraction_numerical': 0.006288381233112258, 'mean_word_length': 3.4012972972972975, 'pattern_counts': {'":': 0, '<': 137, '<?xml version=': 0, '>': 137, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 18, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5587922', 'n_tokens_mistral': 5766, 'n_tokens_neox': 5379, 'n_words': 2955}