sub MAIN
Documentation for sub MAIN
assembled from the following types:
language documentation Functions
From Functions
(Functions) sub MAIN
Declaring a sub MAIN
is not compulsory in Perl 6 scripts, but you can provide one to create a command line interface for your script.
language documentation Command line interface
(Command line interface) sub MAIN
The sub with the special name MAIN
will be executed after all relevant entry phasers (BEGIN
, CHECK
, INIT
, PRE
, ENTER
) have been run and the mainline of the script has been executed. No error will occur if there is no MAIN
sub: your script will then just have to do the work, such as argument parsing, in the mainline of the script.
Any normal exit from the MAIN
sub will result in an exit code of 0
, indicating success. Any return value of the MAIN
sub will be ignored. If an exception is thrown that is not handled inside the MAIN
sub, then the exit code will be 1
. If the dispatch to MAIN
failed, a usage message will be displayed on STDERR and the exit code will be 2
.
The command line parameters are present in the @*ARGS
dynamic variable and may be altered in the mainline of the script before the MAIN
unit is called.
The signature of (the candidates of the multi) sub MAIN
determines which candidate will actually be called using the standard multi dispatch semantics.
A simple example:
# inside file 'hello.p6'sub MAIN()
If you call that script without any parameters, you get the following usage message:
$ perl6 hello.p6Usage:hello.p6 <name>
However, if you give a default value for the parameter, running the script either with or without specifying a name will always work:
# inside file 'hello.p6'sub MAIN( = 'bashful')
$ perl6 hello.p6Hello bashful, how are you?
$ perl6 hello.p6 LizHello Liz, how are you?
Another way to do this is to make sub MAIN
a multi sub
:
# inside file 'hello.p6'multi sub MAIN()multi sub MAIN()
Which would give the same output as the examples above. Whether you should use either method to achieve the desired goal is entirely up to you.
A more complicated example using a single positional and multiple named parameters:
# inside "frobnicate.p6"sub MAIN(Str where *.IO.f = 'file.dat',Int : = 24,Bool :)
With file.dat
present, this will work this way:
$ perl6 frobnicate.p624file.datVerbosity off
Or this way with --verbose
:
$ perl6 frobnicate.p6 --verbose24file.datVerbosity on
If the file file.dat
is not present, or you've specified another filename that doesn't exist, you would get the standard usage message created from introspection of the MAIN
sub:
$ perl6 frobnicate.p6 doesntexist.datUsage:frobnicate.p6 [--length=<Int>] [--verbose] [<file>]
Although you don't have to do anything in your code to do this, it may still be regarded as a bit terse. But there's an easy way to make that usage message better by providing hints using pod features:
# inside "frobnicate.p6"sub MAIN(Str where *.IO.f = 'file.dat', #= an existing file to frobnicateInt : = 24, #= length needed for frobnicationBool :, #= required verbosity)
Which would improve the usage message like this:
$ perl6 frobnicate.p6 doesntexist.datUsage:frobnicate.p6 [--length=<Int>] [--verbose] [<file>][<file>] an existing file to frobnicate--length=<Int> length needed for frobnication--verbose required verbosity
As any other subroutine, MAIN
can define aliases for its named parameters.
sub MAIN(Str where *.IO.f = 'file.dat', #= an existing file to frobnicateInt :size(:) = 24, #= length/size needed for frobnicationBool :, #= required verbosity)
In which case, these aliases will also be listed as alternatives with --help
:
Usage:frobnicate.p6 [--size|--length=<Int>] [--verbose] [<file>][<file>] an existing file to frobnicate--size|--length=<Int> length needed for frobnication--verbose required verbosity
%*SUB-MAIN-OPTS
It's possible to alter how arguments are processed before they're passed to sub MAIN {}
by setting options in the %*SUB-MAIN-OPTS
hash. Due to the nature of dynamic variables, it is required to set up the %*SUB-MAIN-OPTS
hash and fill it with the appropriate settings. For instance:
my =:named-anywhere, # allow named variables at any location# other possible future options / custom options;sub MAIN (, , :, :)
Available options are:
named-anywhere
By default, named arguments passed to the program (i.e., MAIN
) cannot appear after any positional argument. However, if %*SUB-MAIN-OPTS<named-anywhere>
is set to a true value, named arguments can be specified anywhere, even after positional parameter. For example, the above program can be called with:
$ perl6 example.p6 1 --c=2 3 --d=4
is hidden-from-USAGE
Sometimes you want to exclude a MAIN
candidate from being shown in any automatically generated usage message. This can be achieved by adding a hidden-from-USAGE
trait to the specification of the MAIN
candidate you do not want to show. Expanding on an earlier example:
# inside file 'hello.p6'multi sub MAIN() is hidden-from-USAGEmulti sub MAIN()
So, if you would call this script with just a named variable, you would get the following usage:
$ perl6 hello.p6 --verboseUsage:hello.p6 <name> -- the name by which you would like to be called
Without the hidden-from-USAGE
trait on the first candidate, it would have looked like this:
$ perl6 hello.p6 --verboseUsage:hello.p6hello.p6 <name> -- the name by which you would like to be called
Which, although technically correct, doesn't read as well.