--****

-- == Command Line Handling

--

-- <>

namespace cmdline

include std/text.e

include std/sequence.e as seq

include std/map.e

include std/error.e

include std/os.e

include std/io.e

include std/console.e

include std/types.e

--****

-- === Constants

public constant

--** This option switch does not have a parameter. See [[:cmd_parse]]

--** This option switch does have a parameter. See [[:cmd_parse]]

--** This option switch is not case sensitive. See [[:cmd_parse]]

--** This option switch is case sensitive. See [[:cmd_parse]]

--** This option switch must be supplied on command line. See [[:cmd_parse]]

--** This option switch does not have to be on command line. See [[:cmd_parse]]

--** This option switch must only occur once on the command line. See [[:cmd_parse]]

--** This option switch may occur multiple times on a command line. See [[:cmd_parse]]

--** This option switch triggers the 'help' display. See [[:cmd_parse]]

public constant

public enum

--**

-- Additional help routine id. See [[:cmd_parse]]

--**

-- Validate all parameters (default). See [[:cmd_parse]]

--**

-- Do not cause an error for an invalid parameter. See [[:cmd_parse]]

--**

-- 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.

--**

-- Only display the option list in show_help. Do not display other

-- information such as program name, options, etc... See [[:cmd_parse]]

--**

-- 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.

--**

-- 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.

--**

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

$

--

public enum

--**

-- An index into the ##opts## list. See [[:cmd_parse]]

--**

-- The number of times that the routine has been called

-- by cmd_parse for this option. See [[:cmd_parse]]

--**

-- The option's value as found on the command line. See [[:cmd_parse]]

--**

-- The value ##1## if the command line indicates that this option is to remove

-- any earlier occurrences of it. See [[:cmd_parse]]

-- Record fields in 'opts' argument.

enum

end if

-- Local routine to validate and reformat option records if they are not in the standard format.

end if

end if

end if

else

end if

end if

end if

end if

else

end if

else

end if

end if

end if

end if

end if

end if

end if

end if

end if

end if

end if

end if

else

end if

end if

end if

-- Check for duplicate option records.

{ opt[SHORTNAME]})

end if

end if

{opt[LONGNAME]})

end if

end if

-- Insert the default 'help' option if one is not already there.

end if

-- We have to standardize the above additions

end if

end function

integer pad_size

integer this_size

sequence cmd

sequence param_name

integer has_param

integer is_mandatory

end if

-- Calculate the size of the padding required to keep option text aligned.

end if

-- Ignore 'extras' record

end if

end if

end if

end if

end if

end if

--has_param += 1

else

end if

else

end if

end if

end if

end if

-- Ignore 'extras' record

end if

else

end if

else

end if

end if

end if

end if

end if

end if

end if

end if

end if

end if

else

end if

else

end if

end if

end if

else

end if

end if

end if

end if

--****

-- === Routines

--****

-- Signature:

-- function command_line()

--

-- Description:

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

--

-- Returns:

-- # The ##path##, to either the Euphoria executable, (eui, eui.exe, euid.exe euiw.exe) or to your bound

-- executable file.

-- # The ##next word##, is either the name of your Euphoria main file, or

-- (again) the path to your bound executable file.

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

-- {"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 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]]

--****

-- Signature:

-- function option_switches()

--

-- Description:

-- 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]]

--**

-- Show help message for the given opts.

--

-- Parameters:

-- # ##opts## : a sequence of options. See the [[:cmd_parse]] for details.

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

-- # ##cmds## : a sequence of strings. By default this is the output from [[:command_line]]()

--

-- 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. <<

-- }}}

--

---

integer slash

sequence opt_name

object opt_param

-- Strip off any enclosing quotes

end if

end if

end if

end if

end if

end if

-- Strip off any enclosing quotes

end if

end if

end if

end if

else

end if

end if

end if

end if

else

end if

end if

end if

end if

else

end if

end if

end function

--**

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

--

-- Parameters:

-- # ##opts## : a sequence of valid option records: See Comments: section for details

-- # ##parse_options## : an optional sequence of parse options: See Parse Options section for details

-- # ##cmds## : an optional sequence of command line arguments. If omitted the output from

-- ##command_line##() is used.

--

-- Returns:

-- A **map**, containing the options set. The returned map has one special key named "extras"

-- which are values passed on the command line that are not part of any option, for instance

-- a list of files ##myprog -verbose file1.txt file2.txt##. If any command element begins

-- with an @ symbol then that file will be opened and its contents used to add to the command line.

--

-- Parse Options:

-- ##parse_options## can be a sequence of options that will affect the parsing of

-- the command line options. Options can be:

--

-- # ##VALIDATE_ALL## ~-- The default. All options will be validated for all possible errors.

-- # ##NO_VALIDATION## ~-- Do not validate any parameter.

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

-- # ##HELP_RID## ~-- Specify a routine id to call in the event of a parse error (invalid option

-- given, mandatory option not given, no parameter given for an option that requires a

-- parameter, etc...) or a set of text strings. 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; 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.

-- # ##NO_AT_EXPANSION## ~-- Do not expand arguments that begin with '@.'

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

-- # a single '-'. Simply added to the 'extras' list

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

-- # -shortName. The option will be looked up in the short name field of ##opts##.

-- # /shortName. Same as -shortName.

-- # -!shortName. If the 'shortName' has already been found the option is removed.

-- # /!shortName. Same as -!shortName

-- # ~-~-longName. The option will be looked up in the long name field of ##opts##.

-- # ~-~-!longName. If the 'longName' has already been found the option is removed.

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

--

-- Option records have the following structure:

-- # a sequence representing the (short name) text that will follow the "-" option format.

-- Use an atom if not relevant

-- # a sequence representing the (long name) text that will follow the "~-~-" option format.

-- Use an atom if not relevant

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

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

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

-- ## An index into the ##opts## list.

-- ## The number of times that the routine has been called

-- by cmd_parse for this option

-- ## The option's value as found on the command line

-- ## 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 = {}

-- procedure 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

-- end procedure

--

-- procedure opt_output_filename( sequence value)

-- gOutFile = value[OPT_VAL]

-- end procedure

--

-- procedure opt_extras( sequence value)

-- if not file_exists(value[OPT_VAL]) then

-- show_help(option_definitions, sprintf("Cannot find '%s'", value[OPT_VAL]))

-- abort(1)

-- end if

-- gInFile = append(gInFile, value[OPT_VAL])

-- end procedure

--

-- option_definition = {

-- { "v", "verbose", "Verbose output",{NO_PARAMETER}, routine_id("opt_verbose")},

-- { "h", "hash", "Calculate 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 },

-- { 0, 0, 0, 0, routine_id("opt_extras")}

-- }

--

-- map:map opts = cmd_parse(option_definition)

--

-- -- 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]]

integer arg_idx, opts_done

sequence cmd

object param

sequence find_result

sequence type_

integer from_

sequence help_opts

sequence call_count

case HELP_RID then

else

end if

case VALIDATE_ALL then

case NO_VALIDATION then

case NO_VALIDATION_AFTER_FIRST_EXTRA then

case NO_AT_EXPANSION then

case AT_EXPANSION then

case PAUSE_MSG then

else

end if

end switch

end if

-- Find if there are any user-defined help options.

end if

end if

end if

end if

end if

-- Read in the lines from the optional file.

-- File didn't exist but this is not an error, so just

-- remove it from the commands.

end if

else

-- Read in the lines from the file.

end if

end if

-- Parse the 'at' commands removing comment lines and empty lines,

-- and stripping off any enclosing quotes from lines.

end if

-- Replace the '@' argument with the contents of the file.

end if

then

else

end if

end if

end if

else -- found /opt

end if

end ifdef

end if

end if

(validation = NO_VALIDATION_AFTER_FIRST_EXTRA and has_extra = 0)

then

-- something is wrong with the option

end if

end if

end if

else

end if

validation = NO_VALIDATION_AFTER_FIRST_EXTRA))

then

end if

else

end if

else

end if

-- OPT_IDX OPT_CNT OPT_VAL OPT_REV

end if

end if

else

(validation = NO_VALIDATION_AFTER_FIRST_EXTRA))

then

end if

else

end if

else

end if

end if

-- Check that all mandatory options have been supplied.

end if

else

end if

end if

end if

end function

--**

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

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

--

-- Example 1:

--

-- s = build_commandline( { "-d", "/usr/my docs/"} )

-- -- s now contains '-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]]

end function

--**

-- Parse a command line string breaking it into a sequence of command line

-- options.

--

-- Parameters:

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

--

end function