NAME
Rakudo::Options - Rakudo Command Line Options
SYNOPSIS
use Rakudo::Options;
say "running with --ll-exception" if $*RAKUDO-OPTIONS.ll-exception;
say "running as a one liner" if $*RAKUDO-OPTIONS.e;
Rakudo::Options.new(program => "script").run;
if $*RAKUDO-OPTIONS.run-with-environment-variable(
(MVM_SPESH_LOG => "log")
) -> $proc {
say "Produced spesh log in '{"log".IO.absolute}'";
}
DESCRIPTION
Rakudo::Options is a multi-faceted tool, intended for Rakudo tool builders. It provides an API to the command line functions of the currently running Rakudo process for introspection in a dynamic variable $*RAKUDO-OPTIONS.
It also allows you to create an adhoc object that allows you to tweak values of the currently running Rakudo process to run (again).
DYNAMIC VARIABLE
Loading the Rakudo::Options module, creates the $*RAKUDO-OPTIONS dynamic variable, which contains the settings of the currently running Rakudo process (as a Rakudo::Options object).
BUILD PARAMETERS
The following named arguments can be supplied to a call to .new to override what the currently running Rakudo process already provides:
The Raku code that should be considered to have been specified with -e.
The string of the --encoding flag to be considered specified.
String or IO::Path object indicating the executable with which the process is supposed to be running.
The List of the names of the directories that should be considered to have been specified with -I.
Whether the --ll-exception flag is considered to be specified. Expected to be a truthy / falsey value.
The List of names of the modules that should be considered loaded with -M.
Whether the -n flag is considered to be specified. Expected to be a truthy / falsey value.
The string of the --optimize flag to be considered specified.
Whether the -p flag is considered to be specified. Expected to be a truthy / falsey value.
Whether the --profile flag is to be specifiied. Can be given as a Bool, or as a string (indicating the type of profile requested).
A string (or an IO::Path object) with the name of the script that is supposed to be running.
Whether the --stagestats flag is considered to be specified. Expected to be a truthy / falsey value.
The string of the --target flag to be considered specified.
ACCESSORS
Please note that all accessors return Empty if they were not considered to be specified. This allows the accessors to also be used as booleans.
Also note that all of the examples use the $*RAKUDO-OPTIONS dynamic variable, but that any ad-hoc created Rakudo::Options can also be used.
Also note that each of these attributes (with the exception of e, includes and modules can be uses "as is" as parameter to the run function, or as a parameter to the creation of a Proc::Async object.
e
The code that was considered to be specified with -e. If you want to transparently run a script, or the -e code, you should use the .program accessor.
say "running as a one-liner" if $*RAKUDO-OPTIONS;
encoding
The command line parameter of the non-UTF8 encoding with which source-files are considered to be encoded.
if $*RAKUDO-OPTIONS.encoding -> $encoding {
say "Specified '$encoding' for source files";
}
executable
The string of the executable that is considered to be specified.
say "Running with the $*RAKUDO-OPTIONS.executable() executable";
I
A List of command line parameters of -I specifications, to be considered to have been specified.
if $*RAKUDO-OPTIONS.I -> @I {
say "Arguments: @I";
}
includes
A List of strings of the -I specifications to have considered to have been given.
if $*RAKUDO-OPTIONS.includes -> @includes {
say "Specified: @includes";
}
ll-exception
The command line parameter that indicates whether exceptions should throw the extended stack trace or not.
say "Will show extended stack trace" if $*RAKUDO-OPTIONS.ll-exception;
M
A List of command line parameters of -M specifications, to be considered to have been specified.
if $*RAKUDO-OPTIONS.M -> @M {
say "Arguments: @M";
}
modules
A List of strings of the -M specifications to have considered to have been given.
if $*RAKUDO-OPTIONS.modules -> @modules {
say "Specified: @modules";
}
n
The command line parameter that indicates the program should be run for each line of input.
say "Executing with -n" if $*RAKUDO-OPTIONS.n;
p
The command line parameter that indicates the program should be run for each line of input, and that $_ should be printed after each line of input.
say "Executing with -p" if $*RAKUDO-OPTIONS.p;
optimize
The command line parameter that indicates the optimization level.
say "Running with $_" with $*RAKUDO-OPTIONS.optimize;
program
The command line parameter that indicates the program to be executed. Is either a string (in which case it is the name of the script to run) or a List consisting of -e and the code to executed.
say "Running $*RAKUDO-OPTIONS.program";
profile
The command line parameter that indicates whether a profile should be made, and what type.
say "Creating a profile with $_" with $*RAKUDO-OPTIONS.profile;
stagestats
The command line parameter that indicates whether stage statistics should be shown while compiling.
say "Showed stage statistics while compiling" if $*RAKUDO-OPTIONS.stagestats;
target
The command line parameter indicating the target of the compilation.
say "Compiling for target $_" with $*RAKUDO-OPTIONS.target;
METHODS
run
The .run method returns a Proc::Async object by calling the run command with the .run-parameters of the Rakudo::Options object, and any additional positional and named arguments that you give it.
Rakudo::Options.new(
program => $*PROGRAM.sibling('run.raku')
).run(<foo bar>);
my $ro = Rakudo::Options.new(
program => $*PROGRAM.sibling('run.raku')
);
my $output = $ro.run(<foo bar>, :out).out.slurp;
run-with-environment-variable
The .run-with-environment-variable is like the .run method, but it also takes a Pair as the first positional parameter. This pair should have the key as the name of an environment variable to be set, and as value, the value that environment variable should have when calling run.
It returns the Proc::Async object in the parent process, and Nil in the child process.
# parent process
if $*RAKUDO-OPTIONS.run-with-environment-variable(
(MVM_SPESH_LOG => 'spesh-log') # note extra parentheses needed
) {
# inspect spesh-log
exit;
}
# child process, code you want spesh-logged
run-parameters
The .run-parameters method returns a Slip with all of the parameters that should be passed to the run command. It is an internal helper method, that could be used for introspection and debugging, or if you want to execute your own run commands.
my $ro := Rakudo::Options.new(
program => $*PROGRAM.sibling('run.raku')
);
run $ro.run-parameters, <foo bar>;
AUTHOR
Elizabeth Mattijsen liz@raku.rocks
COPYRIGHT AND LICENSE
Copyright 2021 Elizabeth Mattijsen
This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.