OpenEuphoria: Euphoria v4.1

# OpenEuphoria Manual

## Euphoria v4.1

routine or constant name search

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.1 Built-in Routines | Up: 8 API Reference | 8.3 Console > | 9 Release Notes >>

## 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 HEADER

    include std/cmdline.e
    namespace cmdline
    public constant HEADER

This option switch is simply a help display header to group like options together. See cmd_parse

#### 8.2.1.11 VERSIONING

    include std/cmdline.e
    namespace cmdline
    public constant VERSIONING

This option switch sets the program version information. If this option is 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.12 HELP_RID

    include std/cmdline.e
    namespace cmdline
    public enum HELP_RID

Additional help routine id. See cmd_parse

#### 8.2.1.13 VALIDATE_ALL

    include std/cmdline.e
    namespace cmdline
    public enum VALIDATE_ALL

Validate all parameters (default). See cmd_parse

#### 8.2.1.14 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.15 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.16 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, and so on) See cmd_parse

#### 8.2.1.17 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.18 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.19 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.20 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.21 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.22 OPT_IDX

    include std/cmdline.e
    namespace cmdline
    public enum OPT_IDX

An index into the `opts` list. See cmd_parse

#### 8.2.1.23 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.24 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.25 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.26 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()

returns sequence of strings containing each word entered at 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. The interpreter 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 translationg 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:
          {"C:\EUPHORIA\BIN\EUI.EXE",
           "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:
           {"C:\MYFILES\MYPROG.EXE",
            "C:\MYFILES\MYPROG.EXE", -- place holder
            "myfile.dat",
            "12345",
            "the end"
            }

    -- Note that all arguments remain the same as in 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 = {})

shows the 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())

parses command line options and optionally calls procedures based on 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.

One special circumstance exists and that is an option group header. It should contain only two elements:

1. The header constant: HEADER
2. A sequence to display as the option group header

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 1:

    -- simple usage

    map args = cmd_parse({
        { "o", 0, "Output directory", { HAS_PARAMETER } },
        { "v", 0, "Verbose mode" }
    })

    if map:get(args, "v") then
        printf(1, "Output directory is %s\n", { map:get(args, "o") })
    end if

##### Example 2:

    -- complex usage

    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 = {
        { HEADER,         "General options" },
        { "h", "hash",    "Calc hash values", { NO_PARAMETER }, -1 },
        { HEADER,         "Input and output" },
        { "o", "output",  "Output filename",  { MANDATORY, HAS_PARAMETER, ONCE } ,
                                                routine_id("opt_output_filename") },
        { "i", "import",  "An import path",   { HAS_PARAMETER, MULTIPLE}, -1 },
        { HEADER,         "Miscellaneous" },
        { "v", "verbose", "Verbose output",   { NO_PARAMETER }, routine_id("opt_verbose") },
        { "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.

##### 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:

Typically, this is used to ensure that arguments on a command line are properly formed before submitting it to the shell.

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 Unix 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"" } )
    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)

parses 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

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.1 Built-in Routines | Up: 8 API Reference | 8.3 Console > | 9 Release Notes >>