OpenEuphoria

8.2 Command Line Handling

8.2.1 Constants

8.2.1.1 NO_PARAMETER

include std/cmdline.e
namespace cmdline
public constant NO_PARAMETER

This option switch does not have a parameter. See cmd_parse

8.2.1.2 HAS_PARAMETER

include std/cmdline.e
namespace cmdline
public constant HAS_PARAMETER

This option switch does have a parameter. See cmd_parse

8.2.1.3 NO_CASE

include std/cmdline.e
namespace cmdline
public constant NO_CASE

This option switch is not case sensitive. See cmd_parse

8.2.1.4 HAS_CASE

include std/cmdline.e
namespace cmdline
public constant HAS_CASE

This option switch is case sensitive. See cmd_parse

8.2.1.5 MANDATORY

include std/cmdline.e
namespace cmdline
public constant MANDATORY

This option switch must be supplied on command line. See cmd_parse

8.2.1.6 OPTIONAL

include std/cmdline.e
namespace cmdline
public constant OPTIONAL

This option switch does not have to be on command line. See cmd_parse

8.2.1.7 ONCE

include std/cmdline.e
namespace cmdline
public constant ONCE

This option switch must only occur once on the command line. See cmd_parse

8.2.1.8 MULTIPLE

include std/cmdline.e
namespace cmdline
public constant MULTIPLE

This option switch may occur multiple times on a command line. See cmd_parse

8.2.1.9 HELP

include std/cmdline.e
namespace cmdline
public constant HELP

This option switch triggers the 'help' display. See cmd_parse

8.2.1.10 VERSIONING

include std/cmdline.e
namespace cmdline
public constant VERSIONING

This option switch sets the program version information. If this optionis chosen by the user cmd_parse will display the program version information and then end the program with a zero error code.

8.2.1.11 HELP_RID

include std/cmdline.e
namespace cmdline
public enum HELP_RID

Additional help routine id. See cmd_parse

8.2.1.12 VALIDATE_ALL

include std/cmdline.e
namespace cmdline
public enum VALIDATE_ALL

Validate all parameters (default). See cmd_parse

8.2.1.13 NO_VALIDATION

include std/cmdline.e
namespace cmdline
public enum NO_VALIDATION

Do not cause an error for an invalid parameter. See cmd_parse

8.2.1.14 NO_VALIDATION_AFTER_FIRST_EXTRA

include std/cmdline.e
namespace cmdline
public enum NO_VALIDATION_AFTER_FIRST_EXTRA

Do not cause an error for an invalid parameter after the first extra item has been found. This can be helpful for processes such as the Interpreter itself that must deal with command line parameters that it is not meant to handle. At expansions after the first extra are also disabled.

For instance:

eui -D TEST greet.ex -name John -greeting Bye -D TEST is meant for eui, but -name and -greeting options are meant for greet.ex. See cmd_parse

eui @euopts.txt greet.ex @hotmail.com here 'hotmail.com' is not expanded into the command line but 'euopts.txt' is.

8.2.1.15 SHOW_ONLY_OPTIONS

include std/cmdline.e
namespace cmdline
public enum SHOW_ONLY_OPTIONS

Only display the option list in show_help. Do not display other information such as program name, options, etc... See cmd_parse

8.2.1.16 AT_EXPANSION

include std/cmdline.e
namespace cmdline
public enum AT_EXPANSION

Expand arguments that begin with '@' into the command line. (default) For example, @filename will expand the contents of file named 'filename' as if the file's contents were passed in on the command line. Arguments that come after the first extra will not be expanded when NO_VALIDATION_AFTER_FIRST_EXTRA is specified.

8.2.1.17 NO_AT_EXPANSION

include std/cmdline.e
namespace cmdline
public enum NO_AT_EXPANSION

Do not expand arguments that begin with '@' into the command line. Normally @filename will expand the file names contents as if the file's contents were passed in on the command line. This option supresses this behavior.

8.2.1.18 PAUSE_MSG

include std/cmdline.e
namespace cmdline
public enum PAUSE_MSG

Supply a message to display and pause just prior to abort() being called.

8.2.1.19 NO_HELP

include std/cmdline.e
namespace cmdline
public enum NO_HELP

Disable the automatic inclusion of -h, -? and --help as help switches.

8.2.1.20 NO_HELP_ON_ERROR

include std/cmdline.e
namespace cmdline
public enum NO_HELP_ON_ERROR

Disable the automatic display of all of the possible options on error.

8.2.1.21 OPT_IDX

include std/cmdline.e
namespace cmdline
public enum OPT_IDX

An index into the opts list. See cmd_parse

8.2.1.22 OPT_CNT

include std/cmdline.e
namespace cmdline
public enum OPT_CNT

The number of times that the routine has been called by cmd_parse for this option. See cmd_parse

8.2.1.23 OPT_VAL

include std/cmdline.e
namespace cmdline
public enum OPT_VAL

The option's value as found on the command line. See cmd_parse

8.2.1.24 OPT_REV

include std/cmdline.e
namespace cmdline
public enum OPT_REV

The value 1 if the command line indicates that this option is to remove any earlier occurrences of it. See cmd_parse

8.2.1.25 EXTRAS

include std/cmdline.e
namespace cmdline
public constant EXTRAS

The extra parameters on the cmd line, not associated with any specific option. See cmd_parse

8.2.2 Routines

8.2.2.1 command_line

<built-in> function command_line()

A sequence, of strings, where each string is a word from the command-line that started your program.

Returns:

1. The path, to either the Euphoria executable, (eui, eui.exe, euid.exe euiw.exe) or to your bound executable file.
2. The next word, is either the name of your Euphoria main file, or (again) the path to your bound executable file.
3. Any extra words, typed by the user. You can use these words in your program.

There are as many entries as words, plus the two mentioned above.

The Euphoria interpreter itself does not use any command-line options. You are free to use any options for your own program. It does have command line switches though.

The user can put quotes around a series of words to make them into a single argument.

If you convert your program into an executable file, either by binding it, or translating it to C, you will find that all command-line arguments remain the same, except for the first two, even though your user no longer types "eui" on the command-line (see examples below).

Example 1:

-- The user types:  eui myprog myfile.dat 12345 "the end"

cmd = command_line()

-- cmd will be:
      {
       "myprog",
       "myfile.dat",
       "12345",
       "the end"}

Example 2:

-- Your program is bound with the name "myprog.exe"
-- and is stored in the directory c:\myfiles
-- The user types:  myprog myfile.dat 12345 "the end"

cmd = command_line()

-- cmd will be:
       {
        
        "myfile.dat",
        "12345",
        "the end"
        }

-- Note that all arguments remain the same as example 1
-- except for the first two. The second argument is always
-- the same as the first and is inserted to keep the numbering
-- of the subsequent arguments the same, whether your program
-- is bound or translated as a .exe, or not.

See Also:

build_commandline, option_switches, getenv, cmd_parse, show_help

8.2.2.2 option_switches

<built-in> function option_switches()

Retrieves the list of switches passed to the interpreter on the command line.

Returns:

A sequence, of strings, each containing a word related to switches.

Comments:

All switches are recorded in upper case.

Example 1:

euiw -d helLo
-- will result in
-- option_switches() being {"-D","helLo"}

See Also:

Command line switches

8.2.2.3 show_help

include std/cmdline.e
namespace cmdline
public procedure show_help(sequence opts, object add_help_rid = - 1,
        sequence cmds = command_line(), object parse_options = {})

Show help message for the given opts.

Parameters:

1. opts : a sequence of options. See the cmd_parse for details.
2. add_help_rid : an object. Either a routine_id or a set of text strings. The default is -1 meaning that no additional help text will be used.
3. cmds : a sequence of strings. By default this is the output from command_line()
4. parse_options : An option set of behavior modifiers. See the cmd_parse for details.

Comments:

• opts is identical to the one used by cmd_parse
• add_help_rid can be used to provide additional help text. By default, just the option switches and their descriptions will be displayed. However you can provide additional text by either supplying a routine_id of a procedure that accepts no parameters; this procedure is expected to write text to the stdout device. Or you can supply one or more lines of text that will be displayed.

Example 1:

-- in myfile.ex
constant description = {
       "Creates a file containing an analysis of the weather.",
       "The analysis includes temperature and rainfall data",
       "for the past week."
    }

show_help({
    {"q", "silent", "Suppresses any output to console", NO_PARAMETER, -1},
    {"r", 0, "Sets how many lines the console should display", 
    {HAS_PARAMETER,"lines"}, -1}}, description)

Outputs:

myfile.ex options:
-q, --silent      Suppresses any output to console
-r lines          Sets how many lines the console should display

Creates a file containing an analysis of the weather.
The analysis includes temperature and rainfall data
for the past week.

Example 2:

-- in myfile.ex
constant description = {
       "Creates a file containing an analysis of the weather.",
       "The analysis includes temperature and rainfall data",
       "for the past week."
    }
procedure sh()
  for i = 1 to length(description) do
     printf(1, " >> %s <<\n", {description[i]})
  end for
end procedure

show_help({
    {"q", "silent", "Suppresses any output to console", NO_PARAMETER, -1},
    {"r", 0, "Sets how many lines the console should display", 
     {HAS_PARAMETER,"lines"}, -1}}, routine_id("sh"))

Outputs:

myfile.ex options:
-q, --silent      Suppresses any output to console
-r lines          Sets how many lines the console should display

>> Creates a file containing an analysis of the weather. <<
>> The analysis includes temperature and rainfall data  <<
>> for the past week.  <<

8.2.2.4 cmd_parse

include std/cmdline.e
namespace cmdline
public function cmd_parse(sequence opts, object parse_options = {},
        sequence cmds = command_line())

Parse command line options, and optionally call procedures that relate to these options

Parameters:

1. opts : a sequence of records that define the various command line switches and options that are valid for the application: See Comments: section for details
2. parse_options : an optional list of special behavior modifiers: See Parse Options section for details
3. cmds : an optional sequence of command line arguments. If omitted the output from command_line() is used.

Returns:

A map, containing the set of actual options used in cmds. The returned map has one special key, EXTRAS that are values passed on the command line that are not part of any of the defined options. This is commonly used to get the list of files entered on the command line. For instance, if the command line used was myprog -verbose file1.txt file2.txt then the EXTRAS data value would be {"file1.txt", "file2.txt"}.

When any command item begins with an @ symbol then it is assumed that it prefixes a file name. That file will then be opened and its contents used to add to the command line, as if the file contents had actually been entered as part of the original command line.

Parse Options:

parse_options is used to provide a set of behavior modifiers that change the default rules for parsing the command line. If used, it is a list of values that will affect the parsing of the command line options.

These modifers can be any combination of :

1. VALIDATE_ALL -- The default. All options will be validated for all possible errors.
2. NO_VALIDATION -- Do not validate any parameter.
3. NO_VALIDATION_AFTER_FIRST_EXTRA -- Do not validate any parameter after the first extra was encountered. This is helpful for programs such as the Interpreter itself: eui -D TEST greet.ex -name John. -D TEST should be validated but anything after "greet.ex" should not as it is meant for greet.ex to handle, not eui.
4. HELP_RID -- The next Parse Option must either a routine id or a set of text strings. The routine is called or the text is displayed when a parse error (invalid option given, mandatory option not given, no parameter given for an option that requires a parameter, etc...) occurs. This can be used to provide additional help text. By default, just the option switches and their descriptions will be displayed. However you can provide additional text by either supplying a routine_id of a procedure that accepts no parameters, or a sequence containing lines of text (one line per element). The procedure is expected to write text to the stdout device.
5. NO_HELP_ON_ERROR -- Do not show a list of options on a command line error.
6. NO_HELP -- Do not automatically add the switches '-h', '-?', and '--help' to display the help text (if any).
7. NO_AT_EXPANSION -- Do not expand arguments that begin with '@.'
8. AT_EXPANSION -- Expand arguments that begin with '@'. The name that follows @ will be opened as a file, read, and each trimmed non-empty line that does not begin with a '#' character will be inserted as arguments in the command line. These lines replace the original '@' argument as if they had been entered on the original command line.
   
   • If the name following the '@' begins with another '@', the extra '@' is removed and the remainder is the name of the file. However, if that file cannot be read, it is simply ignored. This allows optional files to be included on the command line. Normally, with just a single '@', if the file cannot be found the program aborts.
   • Lines whose first non-whitespace character is '#' are treated as a comment and thus ignored.
   • Lines enclosed with double quotes will have the quotes stripped off and the result is used as an argument. This can be used for arguments that begin with a '#' character, for example.
   • Lines enclosed with single quotes will have the quotes stripped off and the line is then further split up use the space character as a delimiter. The resulting 'words' are then all treated as individual arguments on the command line.

An example of parse options:

{ HELP_RID, routine_id("my_help"), NO_VALIDATION }

Comments:

Token types recognized on the command line:

1. a single '-'. Simply added to the 'extras' list
2. a single "--". This signals the end of command line options. What remains of the command line is added to the 'extras' list, and the parsing terminates.
3. -shortName. The option will be looked up in the short name field of opts.
4. /shortName. Same as -shortName.
5. -!shortName. If the 'shortName' has already been found the option is removed.
6. /!shortName. Same as -!shortName
7. --longName. The option will be looked up in the long name field of opts.
8. --!longName. If the 'longName' has already been found the option is removed.
9. anything else. The word is simply added to the 'extras' list.

For those options that require a parameter to also be supplied, the parameter can be given as either the next command line argument, or by appending '=' or ':' to the command option then appending the parameter data.
For example, -path=/usr/local or as -path /usr/local.

On a failed lookup, the program shows the help by calling show_help(opts, add_help_rid, cmds) and terminates with status code 1.

If you do not explicitly define the switches -h, -?, or --help, these will be automatically added to the list of valid switches and will be set to call the show_help routine.

You can remove any of these as default 'help' switches simply by explicitly using them for something else.

You can also remove all of these switches as automatic help switches by using the NO_HELP parsing option. This just means that these switches are not automatically used as 'help' switches, regardless of whether they are used explicitly or not. So if NO_HELP is used, and you want to give the user the ability to display the 'help' then you must explicitly set up your own switch to do so. N.B, the 'help' is still displayed if an invalid command line switch is used at runtime, regardless of whether NO_HELP is used or not.

Option records have the following structure:

1. a sequence representing the (short name) text that will follow the "-" option format. Use an atom if not relevant
2. a sequence representing the (long name) text that will follow the "--" option format. Use an atom if not relevant
3. a sequence, text that describes the option's purpose. Usually short as it is displayed when "-h"/"--help" is on the command line. Use an atom if not required.
4. An object ...
   • If an atom then it can be either HAS_PARAMETER or anything else if there is no parameter for this option. This format also implies that the option is optional, case-sensitive and can only occur once.
   • If a sequence, it can containing zero or more processing flags in any order ...
     • MANDATORY to indicate that the option must always be supplied.
     • HAS_PARAMETER to indicate that the option must have a parameter following it. You can optionally have a name for the parameter immediately follow the HAS_PARAMETER flag. If one isn't there, the help text will show "x" otherwise it shows the supplied name.
     • NO_CASE to indicate that the case of the supplied option is not significant.
     • ONCE to indicate that the option must only occur once on the command line.
     • MULTIPLE to indicate that the option can occur any number of times on the command line.
   • If both ONCE and MULTIPLE are omitted then switches that also have HAS_PARAMETER are only allowed once but switches without HAS_PARAMETER can have multuple occurances but only one is recorded in the output map.
5. an integer; a routine_id. This function will be called when the option is located on the command line and before it updates the map.
   Use -1 if cmd_parse is not to invoke a function for this option.
   The user defined function must accept a single sequence parameter containing four values. If the function returns 1 then the command option does not update the map. You can use the predefined index values OPT_IDX, OPT_CNT, OPT_VAL, OPT_REV when referencing the function's parameter elements.
   1. An index into the opts list.
   2. The number of times that the routine has been called by cmd_parse for this option
   3. The option's value as found on the command line
   4. 1 if the command line indicates that this option is to remove any earlier occurrences of it.

When assigning a value to the resulting map, the key is the long name if present, otherwise it uses the short name. For options, you must supply a short name, a long name or both.

If you want cmd_parse() to call a user routine for the extra command line values, you need to specify an Option Record that has neither a short name or a long name, in which case only the routine_id field is used.

For more details on how the command line is being pre-parsed, see command_line.

Example:

sequence option_definition
integer gVerbose = 0
sequence gOutFile = {}
sequence gInFile = {}
function opt_verbose( sequence value)
   if value[OPT_VAL] = -1 then -- (-!v used on command line)
   	gVerbose = 0
   else
     if value[OPT_CNT] = 1 then
        gVerbose = 1
     else
        gVerbose += 1
     end if
   end if
	return 1
end function

function opt_output_filename( sequence value)
   gOutFile = value[OPT_VAL]
	return 1
end function

function extras( sequence value)
   if not file_exists(value[OPT_VAL]) then
       show_help(option_definition, sprintf("Cannot find '%s'", 
                 {value[OPT_VAL]}) )
       abort(1)
   end if
   gInFile = append(gInFile, value[OPT_VAL])
	return 1
end function

option_definition = {
    { "v", "verbose", "Verbose output",   { NO_PARAMETER }, routine_id("opt_verbose") },
    { "h", "hash",    "Calc hash values", { NO_PARAMETER }, -1 },
    { "o", "output",  "Output filename",  { MANDATORY, HAS_PARAMETER, ONCE } , 
                                            routine_id("opt_output_filename") },
    { "i", "import",  "An import path",   { HAS_PARAMETER, MULTIPLE}, -1 },
    { "e", "version", "Display version",  { VERSIONING, "myprog v1.0" } },
    {  0, 0, 0, 0, routine_id("extras")}
}

map:map opts = cmd_parse(option_definition, NO_HELP)

-- When run as: 
--             eui myprog.ex -v @output.txt -i /etc/app input1.txt input2.txt
-- and the file "output.txt" contains the two lines ...
--   --output=john.txt
--   '-i /usr/local'
--
-- map:get(opts, "verbose") --> 1
-- map:get(opts, "hash") --> 0 (not supplied on command line)
-- map:get(opts, "output") --> "john.txt"
-- map:get(opts, "import") --> {"/usr/local", "/etc/app"}
-- map:get(opts, EXTRAS) --> {"input1.txt", "input2.txt"}

See Also:

show_help, command_line

8.2.2.5 build_commandline

include std/cmdline.e
namespace cmdline
public function build_commandline(sequence cmds)

Returns a text string based on the set of supplied strings. Typically, this is used to ensure that arguments on a command line are properly formed before submitting it to the shell.

Parameters:

1. cmds : A sequence. Contains zero or more strings.

Returns:

A sequence, which is a text string. Each of the strings in cmds is quoted if they contain spaces, and then concatenated to form a single string.

Comments:

Though this function does the quoting for you it is not going to protect your programs from globing *, ?. And it is not specied here what happens if you pass redirection or piping characters.

When passing a result from with build_commandline to system_exec, file arguments will benefit from using canonical_path with the TO_SHORT. On Windows, this is required for file arguments to always work. There is a complication with files that contain spaces. On other platforms, this call will also return a useable filename.

Alternatively, you can leave out calls to canonical_path and use system instead.

Example 1:

s = build_commandline( { "-d", canonical_path("/usr/my docs/",,TO_SHORT)} )
-- s now contains a short name equivalent to '-d "/usr/my docs/"'

Example 2:

You can use this to run things that might be difficult to quote out:

Suppose you want to run a program that requires quotes on its command line? Use this function to pass quotation marks:

s = build_commandline( { "awk", "-e", "'{ print $1"x"$2; }'" } )
system(s,0)

See Also:

parse_commandline, system, system_exec, command_line, canonical_path, TO_SHORT

8.2.2.6 parse_commandline

include std/cmdline.e
namespace cmdline
public function parse_commandline(sequence cmdline)

Parse a command line string breaking it into a sequence of command line options.

Parameters:

1. cmdline : Command line sequence (string)

Returns:

A sequence, of command line options

Example 1:

sequence opts = parse_commandline("-v -f '%Y-%m-%d %H:%M'")
-- opts = { "-v", "-f", "%Y-%m-%d %H:%M" }

See Also:

build_commandline