Re: SIMPLE question [Was: Re: TIP #193: Simple Syntax Help System

• Previous message: Bryan Oakley: "Re: Ways of quitting a TCL/TK application."
• In reply to: lvirden_at_yahoo.com: "SIMPLE question [Was: Re: TIP #193: Simple Syntax Help System"
• Next in thread: Bryan Oakley: "Re: SIMPLE question [Was: Re: TIP #193: Simple Syntax Help System"
• Reply: Bryan Oakley: "Re: SIMPLE question [Was: Re: TIP #193: Simple Syntax Help System"
• Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

Date: 12 May 2004 11:02:25 -0700

lvirden@yahoo.com wrote in message news:<c7qiai$3as$5@srv38.cas.org>...
> According to Juan C. Gil <jgil@gmv.es>:
> :} -arguments {
> : { a integer {An integer}}
> : {-b boolflag {A boolean flag}}
> : {-c word default {A flag}}
> :}
>
> In this part of the example, do these lines correspond to
> something similar to tcllib's cmdline extension - i.e. a
> getopt type definition of what arguments are permitted, what
> type values they should be, which are required and which are
> optional, etc. with argument checking and appropriate error/help
> messages?
>
Sorry for the long post, but, Larry, you asked for it ...

* Short answer: yes! :-)

* Medium length answer:

  Quite yes, although the syntax and functionality is closer to
  that of the "opt" package (command arguments) than to that of
  the "cmdline" package (command line arguments); The Simple
  Development Library also includes a command line parser though!
  (see the section COMMAND LINE PARSER below).

  As for the argument checking, checking for type conformance is
  possible, and the checking of the pairing between defined and
  actual arguments is simple, that is, the system does not try to
  be too clever. For example, the position and order of the
  flags must be honored as declared.

  % proc-ext foo {
     { a integer {}}
     {-b boolflag {}}
     {-c word bar {}}
     {?d? string gee {}}
  } {
     puts "{$a} {$b} {$c} {$d}"
  }

  % foo 7 8
  {7} {0} {bar} {8}

  % foo 7 -b
  {7} {1} {bar} {gee}

  % foo -b
  {-b} {0} {bar} {gee} <-- "a" takes the value "-b"

  % foo 7 8 -b <-- out of order flag
  called "foo" with too many arguments

  As for the appropriate error/help messages, in
  general yes, although there are cases in which Tcl
  produces the error and, consequently, may not be
  "correct":

  % foo 7 -c
  no parameter given for flag "-c" to "foo"

  % foo
  wrong # args: should be "foo a args" <-- incorrect

  I wonder whether I could use command traces to
  correct this last one case...

* (Very) long answer:

ARGUMENTS SYNTAX

The syntax for command and method arguments in The Simple
Development library derives from that of the "opt" package
distributed with Tcl, so the upgrade should be easy; in fact I
implemented that as an evolution of the "opt" package for two
reasons: 1) "opt" is *SLOW* and 2) it was deprecated from Tcl
8.1 (although it is still distributed with Tcl).

The argument syntax is {name type ?value? description}.
More details follow:

Argument Name

Arguments whose name starts by a hyphen are flags whose presence
in the procedure call actual argument list is optional.

Flags whose type is /boolflag/ are boolean flags and do not
require a parameter. For each boolean flag in the argument list,
a variable is created in the procedure body with the same name as
the flag (excluding the hyphen) and whose value is true or false
depending on whether the flag is given or not in the procedure
call actual argument list.

Flags whose type is not /boolflag/ are regular flags and require
a parameter; the flag type is the expected parameter type. For
each regular flag in the argument list, a variable is created in
the procedure body with the same name as the flag (excluding the
hyphen) and whose value is the parameter supplied after the flag,
or its default value if the flag was not given in the procedure
call actual argument list. The presence or absence of a regular
flag in the procedure call actual argument list can be obtained
via the [::Simple::Arguments::information flaggiven] procedure.

The list of all flags in the procedure call actual argument list
together with their parameters can be obtained via the
[::Simple::Arguments::information givenflags].

Arguments whose name is enclosed between question marks are
optional. They differ from the flags in that they behave exactly
as optional arguments to the [proc] command, that is, they must
appear at the end of the argument list.

As with the [proc] command, the /args/ special argument collects
all remaining arguments in the actual argument list and combines
them into a list which is available in the procedure body in the
variable name /args/. If given, the /args/ special argument must
be the last one.

Argument Type

The argument type must be a type known by The Simple Development
Library, that is, any built-in type or added via the
[::Simple::Type::add] procedure.

The Simple Development Library comes with some 40 built-in types:
integer, float, hexadecimal, ..., pattern, regular expression,
list, widget, URL, choice, ...; "derived" types are also
possible: list of patterns, array of words, range of integers,
... An actual argument whose type is /choice/ can only hold one
of the values specified in the argument declaration default value
field. See also the /boolflag/ type in the argument name section
above.

Argument Default Value or Choice List

An argument declaration can specify this field if and only if its
type is /choice/ or is an optional argument whose type is not
/boolflag/. For arguments of type /choice/, this field specifies
the list of allowed choices otherwise the default value for
optional argument. For optional arguments of type /choice/, the
default value is the first choice.

Argument Description

This is simply a description of the argument.

RUN-TIME HANDLING

Upon declaring a procedure or method, the /-checktype/ flag
allows to override the package option of the same name for the
procedure being created. This option controls whether a run-time
type check is performed to check whether the arguments contents
match their type. This has a performance penalty which should be
considered. The overhead comes from two fronts. First, the
contents of each argument must be checked. Second, it is not
possible to apply the improving performance tricks described in
the details section below.

The /-parseflags/ flag allows to disable the flag parsing which
is delegated to the user. This results in better performance
(the procedure call is equivalent to a regular Tcl [proc]
procedure) at the cost of some hassle and restrictions:

* The arguments from the first flag are replaced by the "args"
  special argument. It is the user responsibility to handle
  the "args" special argument to attain the desired behaviour.

* No run-time type checking of the procedure arguments is
  performed. As a result, it is not allowed to supply both the
  /-parseflags/ and /-checktype/ flags. If the /-checktype/
  package option is set to true, it is not honored.

COMMAND LINE PARSER

The Simple Development Library comes with a powerful command line
options parser. Features include:

* Each option has a primary flag and an optional secondary flag,
  so that the command line can refer to any of the two as
  aliases.

* Each option can optionally have a name which is used in the
  command line option usage string and other references to the
  option.

* Each option has a type to which the option values must conform.
  Usable types are as for command and method arguments.

* Options with numeric types can optionally have a numeric range
  to which the option values must conform.

* Options with /choice/ type or derived from it have a list of
  allowed choices to which the option values must conform.

* Each option can optionally have a default value.

* For each option a range of values can be specified to which the
  option number of values must conform. By default, each
  option admits a single value.

* Options can be optional or compulsory (not really "options"
  then, as Harald Kirsh, clig's author, first noted).

* The presence or absence of certain options can be made
  optional, compulsory or disallowed depending on the presence
  or absence of other options. For two options, the
  possibilites are:

  -a -b: both -a and -b are compulsory

  -a [-b]: -a is compulsory and -b is optional

  [-a -b]: -a and -b are optional, but if one is given the other
  must be also given.

  [-a [-b]]: -a and -b are optional, but -b can not be given
  unless -a is also present.

  (-a | -b): one of -a or -b must be given.

  [(-a | -b)]: -a and -b are optional, but both can not be
  given.

These basic usage relations between two options can be combined
to yield almost any imaginable usage relations between three or
more options.

The system builds the command line options usage string.

Procedures are provided to declare options, declare their usage
relations, reset the declared options and their usage relations,
parse a command line with respect to the declared options and
usage relations and get the command line options usage string.
After a command line has been parsed, procedurers are provided to
assess whether a certain option has been given in the command
line, to assess wether it is available (that is, whether it has a
default value or has been given in the command line), to get the
value of an available option and to assess whether the value of
an available option is that option default value.

Juan Carlos---

• Previous message: Bryan Oakley: "Re: Ways of quitting a TCL/TK application."
• In reply to: lvirden_at_yahoo.com: "SIMPLE question [Was: Re: TIP #193: Simple Syntax Help System"
• Next in thread: Bryan Oakley: "Re: SIMPLE question [Was: Re: TIP #193: Simple Syntax Help System"
• Reply: Bryan Oakley: "Re: SIMPLE question [Was: Re: TIP #193: Simple Syntax Help System"
• Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]