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

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

- There should be a way to make aliases for existing options, in the same way that `-bd` is an alias for `-borderwidth` in Tk.

`
`