jparseargs.tcl

Introduction

The jparseargs.tcl library file is distributed as part of the jstools package. It consists of procedures to process procedure and application arguments: both those that take arguments in the typical Tcl `-option value' format and those that take no arguments.

This document describes jparseargs.tcl version 0.1.

Usage

Accessing the Library

In order to use the jparseargs.tcl library, it (and any other libraries it depends on) must be in your Tcl auto_path, described in tclvars(n). Information about how to arrange that, and other conventions common to the jstools libraries, is in the Usage section of The jstools Libraries.

Credits and Copyright

Author

Jay Sekora
js@aq.org
http://www.aq.org/~js/

Copyright

The library is copyright © 1992-1995 by Jay Sekora, but may be freely redistributed under the conditions at the top of the file.

Overview

Procedures

::jstools::parse_args - search for option values in parent procedure's arguments
::jstools::parse_argv - search for option values in script's arguments ($argv)
::jstools::parse_boolean_args - check whether options occur in parent's option list
::jstools::parse_boolean_argv - check whether options occur in script's arguments

::jstools::parse_args

Usage

proc procname { args } {
::jstools::parse_args
arglist
...}

Argument

arglist - list of {option default} pairs

Example

proc alert { args } {
::jstools::parse_args {
{title "Alert"}
{text "Alert!"}
{ok "OK"}
}
toplevel .foo
wm title .foo $title
message .foo.msg -text $text
button .foo.btn -text $ok -command {destroy .foo}
pack .foo.msg .foo.btn
}

Description

This procedure is used by almost all the other procedures in the jstools libraries. It extracts options from the variable args in the parent procedure, and sets corresponding variables, also in the parent procedure. (See the proc(1) manual page for an explanation of the args variable.) Its argument is a list of {option default} sublists. For each pair, the parent's args variable is scanned for elements matching option, preceded by a hyphen. (For instance, if an option is `title', ::jstools::parse_args searches for `-title'.) If a match is found, the following word is used as the value of that parameter, and a variable with the name option is set to that value in the parent procedure. (To continue the example, the parent's variable title would be set to the element following `-title' in $args.) If no match is found, the parent's option variable is set to the value of default.

It removes any items it processes from the parent's argc variable.

Although not as flexible as getopt(3), this procedure makes it fairly easy to process lists of optional arguments.

::jstools::parse_argv

Usage

::jstools::parse_argv arglist

Argument

arglist - list of {option default} pairs

Example

::jstools::parse_argv {
{font Courier10}
{headerfont Times-Bold12}
{columns 1}
{orient portrait}
}

Description

This procedure is almost identical to ::jstools::parse_args, but instead of parsing the args variable in a procedure, it parses the global argv variable. I.e., instead of parsing procedure arguments, it parses script arguments.

It removes any items it processes from argv, and sets argc to the length of argv when it's done.

For more information about the argv and argc variables, see the wish(1) or tclsh(1) manual page.

::jstools::parse_boolean_args

Usage

proc procname { args } {
::jstools::parse_boolean_args
arglist
...}

Argument

arglist - list of options

Example

proc beep { args } {
::jstools::parse_boolean_args {
{tty}
}

if $tty {
puts stderr "\a"
} else {
j:beep .
}
}

Description

This procedure searches for options from the variable args in the parent procedure, and sets corresponding variables, also in the parent procedure, to 1 or 0 depending on whether they are found. (See the proc(1) manual page for an explanation of the args variable.) Its argument is a list of options. The parent's args variable is scanned for elements matching option, preceded by a hyphen. If a match is found, and a variable with the name option is set to 1 in the parent procedure. If no match is found, the parent's option variable is set to 0.

It removes any items it processes from the parent's argc variable.

::jstools::parse_boolean_argv

Usage

::jstools::parse_boolean_argv arglist

Argument

arglist - list of options

Example

::jstools::parse_boolean_argv {
reverse
sort
reformat
justify
}

if $reverse {...}
if $sort {...}
[...]

Description

This procedure is almost identical to ::jstools::parse_boolean_args, but instead of parsing the args variable in a procedure, it parses the global argv variable. I.e., instead of parsing procedure arguments, it parses script arguments.

It removes any items it processes from argv, and sets argc to the length of argv when it's done.

For more information about the argv and argc variables, see the wish(1) or tclsh(1) manual page.

Future Directions