{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.
} {{{list:level:1 {113.0 114.0}} {jhtml:anchor:anchorname {2.0 3.0 6.0 7.0 9.0 10.0 16.0 17.0 22.0 23.0 48.0 49.0 66.0 67.0 89.0 90.0 112.0 113.0}} {jdoc:anchor:anchorname {2.0 3.0 6.0 7.0 9.0 10.0 16.0 17.0 22.0 23.0 48.0 49.0 66.0 67.0 89.0 90.0}} {jdoc:xref:link {3.62 3.69 8.215 8.236 8.244 8.261 8.265 8.286 18.0 18.21 19.0 19.21 20.0 20.29 21.0 21.29 43.61 43.82 61.38 61.59 107.38 107.67}} {jdoc:xref:manpage {8.131 8.138 43.227 43.231 47.28 47.34 65.64 65.68 65.75 65.80 86.205 86.209 111.64 111.68 111.75 111.80}} {richtext:font:roman {3.0 3.4 3.18 3.62 3.69 3.205 3.218 5.24 5.38 6.0 8.0 8.20 8.34 8.107 8.116 8.131 8.138 8.219 8.226 8.248 8.253 8.265 8.286 9.0 11.0 12.0 12.9 13.0 13.22 14.0 15.0 16.0 18.21 19.0 19.21 19.72 19.77 20.0 20.29 21.0 21.29 22.0 28.0 28.1 28.8 28.19 28.35 29.0 43.0 43.65 43.72 43.123 43.127 43.227 43.231 43.273 43.277 43.316 43.332 43.372 43.376 43.419 43.425 43.471 43.477 43.482 43.487 43.490 43.511 43.526 43.532 43.646 43.652 43.748 43.753 43.793 43.799 43.804 43.809 43.848 43.854 43.887 43.894 45.52 45.56 47.28 47.34 48.0 52.0 52.1 52.8 52.19 52.35 53.0 61.0 61.38 61.59 61.88 61.92 61.139 61.143 63.39 63.43 63.54 63.58 63.76 63.80 65.31 65.35 65.40 65.44 65.64 65.68 65.75 65.80 66.0 72.0 72.1 72.8 72.19 72.25 73.0 86.0 86.54 86.58 86.151 86.152 86.156 86.157 86.205 86.209 86.251 86.255 86.294 86.300 86.317 86.321 86.364 86.370 86.445 86.451 86.525 86.531 88.52 88.56 89.0 93.0 93.1 93.8 93.19 93.25 94.0 105.0 106.0 107.0 107.38 107.67 107.96 107.100 107.147 107.151 109.39 109.43 109.54 109.58 109.76 109.80 111.31 111.35 111.40 111.44 111.64 111.68 111.75 111.80 112.0 113.0 113.83 113.86 113.103 113.115 114.0}} {richtext:font:italic {3.213 3.218 25.25 25.32 28.1 28.8 28.20 28.26 28.27 28.34 43.317 43.323 43.324 43.331 43.419 43.425 43.471 43.477 43.646 43.652 43.848 43.854 43.887 43.894 50.23 50.30 52.1 52.8 52.20 52.26 52.27 52.34 69.33 69.40 72.1 72.8 72.19 72.25 86.294 86.300 86.364 86.370 86.445 86.451 86.525 86.531 91.31 91.38 93.1 93.8 93.19 93.25}} {richtext:font:bold {3.4 3.18 3.62 3.69 5.24 5.38 8.20 8.34 8.219 8.226 43.65 43.72}} {richtext:font:bolditalic {8.248 8.253 8.265 8.286}} {richtext:font:typewriter {3.205 3.213 8.107 8.116 8.131 8.138 12.0 12.9 13.0 13.22 18.0 18.21 19.0 19.21 19.72 19.77 20.0 20.29 21.0 21.29 24.0 25.25 25.32 27.0 28.19 28.20 28.26 28.27 28.34 28.35 30.0 42.0 43.123 43.127 43.227 43.231 43.273 43.277 43.316 43.317 43.323 43.324 43.331 43.332 43.372 43.376 43.482 43.487 43.490 43.511 43.526 43.532 43.748 43.753 43.793 43.799 43.804 43.809 45.52 45.56 47.28 47.34 50.0 50.23 50.30 51.0 52.19 52.20 52.26 52.27 52.34 52.35 54.0 60.0 61.38 61.59 61.88 61.92 61.139 61.143 63.39 63.43 63.54 63.58 63.76 63.80 65.31 65.35 65.40 65.44 65.64 65.68 65.75 65.80 68.0 69.33 69.40 71.0 74.0 85.0 86.54 86.58 86.151 86.152 86.156 86.157 86.205 86.209 86.251 86.255 86.317 86.321 88.52 88.56 91.0 91.31 91.38 92.0 95.0 105.0 107.38 107.67 107.96 107.100 107.147 107.151 109.39 109.43 109.54 109.58 109.76 109.80 111.31 111.35 111.40 111.44 111.64 111.68 111.75 111.80 113.83 113.86 113.103 113.115}} {richtext:font:heading0 {1.0 2.0}} {richtext:font:heading1 {2.0 3.0 6.0 7.0 9.0 10.0 16.0 17.0 22.0 23.0 48.0 49.0 66.0 67.0 89.0 90.0 112.0 113.0}} {richtext:font:heading2 {7.0 8.0 10.0 11.0 14.0 15.0 17.0 18.0 23.0 24.0 27.0 28.0 29.0 30.0 42.0 43.0 49.0 50.0 51.0 52.0 53.0 54.0 60.0 61.0 67.0 68.0 71.0 72.0 73.0 74.0 85.0 86.0 90.0 91.0 92.0 93.0 94.0 95.0 106.0 107.0}} {jdoc:link:jstools.jdoc {3.62 3.69}} {jdoc:manpage:tclvars {8.131 8.138}} {jdoc:link:jslibraries.tcl {8.215 8.236}} {jdoc:link:jslibraries.jdoc#Usage {8.244 8.261}} {jdoc:link:jslibraries.jdoc {8.265 8.286 43.61 43.82}} {{} {9.0 15.0 17.0 17.10}} {jdoc:manpage:proc {43.227 43.231 86.205 86.209}} {jdoc:manpage:getopt {47.28 47.34}} {jdoc:anchorname:j:parse_args {22.0 23.0}} {jdoc:anchorname:Overview {16.0 17.0}} {jdoc:anchorname:Credits_and_Copyright {9.0 10.0}} {jdoc:anchorname:Usage {6.0 7.0}} {jdoc:anchorname:Introduction {2.0 3.0}} {jdoc:anchorname:j:parse_argv {48.0 49.0}} {jdoc:manpage:tclsh {65.75 65.80 111.75 111.80}} {jdoc:manpage:wish {65.64 65.68 111.64 111.68}} {list:1:ul {113.0 114.0}} {jdoc:anchorname:j:parse_boolean_args {66.0 67.0}} {jdoc:anchorname:j:parse_boolean_argv {89.0 90.0}} {jdoc:link:#::jstools::parse_args {18.0 18.21 61.38 61.59}} {jdoc:link:#::jstools::parse_argv {19.0 19.21}} {jdoc:link:#::jstools::parse_boolean_args {20.0 20.29 107.38 107.67}} {jdoc:link:#::jstools::parse_boolean_argv {21.0 21.29}} {jhtml:anchorname:Credits_and_Copyright {9.0 10.0}} {jhtml:anchorname:Introduction {2.0 3.0}} {jhtml:anchorname:Usage {6.0 7.0}} {jhtml:anchorname:Overview {16.0 17.0}} {jhtml:anchorname:::jstools::parse_args {22.0 23.0}} {jhtml:anchorname:::jstools::parse_argv {48.0 49.0}} {jhtml:anchorname:::jstools::parse_boolean_args {66.0 67.0}} {jhtml:anchorname:::jstools::parse_boolean_argv {89.0 90.0}} {jhtml:anchorname:Future_Directions {112.0 113.0}} {special:list_item:1 {113.0 113.1}}} {{convert:place:58.30 50.30} {convert:place:74.68 65.68} {convert:place:121.76 109.76} {convert:place:52.56 45.56} {convert:place:12.0 9.0} {richptr 114.0} {convert:place:121.80 109.80} {convert:place:10.138 8.138} {convert:place:33.0 27.0} {convert:place:119.38 107.38} {convert:place:74.75 65.75} {convert:place:74.80 65.80} {current 105.0} {convert:place:50.887 43.887} {convert:place:4.200 3.205} {convert:place:96.0 85.0} {convert:place:106.0 94.0} {convert:place:8.0 6.0} {convert:place:97.251 86.251} {convert:place:127.0 114.0} {convert:place:50.894 43.894} {convert:place:29.0 23.0} {convert:place:30.0 24.0} {convert:place:97.255 86.255} {convert:place:4.208 3.213} {convert:place:50.273 43.273} {convert:place:4.213 3.218} {convert:place:103.0 91.0} {convert:place:50.277 43.277} {convert:place:79.33 69.33} {convert:place:26.0 21.0} {convert:place:119.67 107.67} {convert:place:79.40 69.40} {convert:place:6.24 5.24} {convert:place:68.0 60.0} {convert:place:2.0 2.0} {convert:place:23.0 18.0} {convert:place:6.38 5.38} {convert:place:97.300 86.300} {convert:place:72.39 63.39} {convert:place:50.316 43.316} {convert:place:97.294 86.294} {convert:place:50.317 43.317} {convert:place:72.43 63.43} {abbrevend 5.58} {convert:place:117.0 105.0} {convert:place:19.0 15.0} {convert:place:119.96 107.96} {convert:place:50.323 43.323} {convert:place:50.324 43.324} {convert:place:62.0 54.0} {convert:place:10.215 8.215} {convert:place:72.54 63.54} {convert:place:83.0 73.0} {convert:place:97.317 86.317} {convert:place:50.331 43.331} {convert:place:126.83 113.83} {convert:place:126.103 113.103} {convert:place:10.219 8.219} {convert:place:50.332 43.332} {convert:place:50.646 43.646} {convert:place:72.58 63.58} {convert:place:97.321 86.321} {convert:place:126.86 113.86} {convert:place:16.0 13.0} {convert:place:103.31 91.31} {convert:place:50.652 43.652} {convert:place:10.226 8.226} {convert:place:58.0 50.0} {convert:place:103.38 91.38} {convert:place:126.115 113.115} {convert:place:34.20 28.20} {convert:place:34.19 28.19} {convert:place:50.61 43.61} {convert:place:10.236 8.236} {convert:place:13.0 10.0} {convert:place:72.76 63.76} {convert:place:34.26 28.26} {convert:place:34.0 28.0} {convert:place:34.27 28.27} {convert:place:34.1 28.1} {convert:place:50.65 43.65} {convert:place:72.80 63.80} {convert:place:10.244 8.244} {convert:place:76.0 66.0} {convert:place:34.34 28.34} {convert:place:50.72 43.72} {convert:place:10.248 8.248} {convert:place:34.8 28.8} {convert:place:34.35 28.35} {convert:place:107.0 95.0} {convert:place:97.0 86.0} {convert:place:9.0 7.0} {convert:place:10.0 8.0} {convert:place:128.0 115.0} {convert:place:10.253 8.253} {anchor 114.0} {insert 114.0} {convert:place:50.82 43.82} {convert:place:50.372 43.372} {convert:place:10.261 8.261} {convert:place:26.29 21.29} {convert:place:104.0 92.0} {convert:place:4.18 3.18} {convert:place:50.376 43.376} {convert:place:97.364 86.364} {convert:place:10.265 8.265} {abbrevstart 5.57} {convert:place:125.0 112.0} {convert:place:99.52 88.52} {convert:place:97.370 86.370} {convert:place:48.0 42.0} {convert:place:99.56 88.56} {convert:place:69.0 60.0} {convert:place:70.0 61.0} {convert:place:101.0 89.0} {convert:place:3.0 2.0} {convert:place:119.100 107.100} {convert:place:24.0 19.0} {convert:place:10.286 8.286} {convert:place:70.38 61.38} {convert:place:118.0 106.0} {convert:place:123.31 111.31} {convert:place:21.0 16.0} {convert:place:50.419 43.419} {convert:place:123.35 111.35} {convert:place:4.57 3.77} {convert:place:50.425 43.425} {convert:place:25.29 20.29} {convert:place:123.40 111.40} {convert:place:84.0 74.0} {convert:place:70.59 61.59} {convert:place:4.64 3.77} {convert:place:123.44 111.44} {convert:place:50.748 43.748} {convert:place:50.123 43.123} {convert:place:54.28 47.28} {convert:place:50.753 43.753} {convert:place:59.0 51.0} {convert:place:60.0 52.0} {convert:place:50.127 43.127} {convert:place:60.1 52.1} {convert:place:54.34 47.34} {convert:place:81.0 71.0} {convert:place:14.0 11.0} {convert:place:60.8 52.8} {convert:place:119.147 107.147} {convert:place:35.0 29.0} {convert:place:123.64 111.64} {convert:place:119.151 107.151} {convert:place:10.20 8.20} {convert:place:56.0 48.0} {convert:place:123.68 111.68} {convert:place:97.445 86.445} {convert:place:77.0 67.0} {convert:place:70.88 61.88} {convert:place:24.21 19.21} {convert:place:70.92 61.92} {convert:place:97.451 86.451} {convert:place:123.75 111.75} {convert:place:123.80 111.80} {convert:place:10.34 8.34} {convert:place:50.471 43.471} {convert:place:95.0 85.0} {convert:place:105.0 93.0} {convert:place:50.477 43.477} {convert:place:97.151 86.151} {convert:place:105.1 93.1} {convert:place:50.793 43.793} {convert:place:97.152 86.152} {convert:place:126.0 113.0} {convert:place:50.804 43.804} {convert:place:97.54 86.54} {convert:place:126.1 113.1} {convert:place:28.0 22.0} {convert:place:16.22 13.22} {convert:place:50.482 43.482} {convert:place:82.19 72.19} {convert:place:97.156 86.156} {convert:place:49.0 42.0} {convert:place:50.0 43.0} {convert:place:97.58 86.58} {convert:place:97.157 86.157} {convert:place:50.799 43.799} {convert:place:50.809 43.809} {convert:place:105.8 93.8} {convert:place:50.487 43.487} {convert:place:82.25 72.25} {convert:place:50.490 43.490} {convert:place:102.0 90.0} {convert:place:31.25 25.25} {convert:place:4.0 3.0} {convert:place:25.0 20.0} {convert:place:60.20 52.20} {convert:place:4.4 3.4} {convert:place:60.19 52.19} {convert:place:31.32 25.32} {convert:place:50.511 43.511} {convert:place:60.26 52.26} {convert:place:60.27 52.27} {convert:place:23.21 18.21} {convert:place:1.0 1.0} {convert:place:119.0 107.0} {convert:place:22.0 17.0} {convert:place:60.34 52.34} {convert:place:60.35 52.35} {convert:place:24.72 19.72} {convert:place:74.31 65.31} {convert:place:121.39 109.39} {convert:place:50.526 43.526} {convert:place:74.35 65.35} {convert:place:121.43 109.43} {convert:place:24.77 19.77} {convert:place:50.532 43.532} {convert:place:74.40 65.40} {convert:place:97.205 86.205} {convert:place:18.0 14.0} {convert:place:10.107 8.107} {convert:place:50.848 43.848} {convert:place:74.44 65.44} {convert:place:97.209 86.209} {convert:place:97.525 86.525} {convert:place:121.54 109.54} {convert:place:50.854 43.854} {convert:place:61.0 53.0} {convert:place:50.227 43.227} {convert:place:105.19 93.19} {convert:place:10.116 8.116} {convert:place:97.531 86.531} {convert:place:121.58 109.58} {convert:place:82.0 72.0} {convert:place:50.231 43.231} {convert:place:82.1 72.1} {convert:place:105.25 93.25} {convert:place:15.0 12.0} {convert:place:36.0 30.0} {convert:place:58.23 50.23} {convert:place:82.8 72.8} {convert:place:57.0 49.0} {convert:place:70.139 61.139} {convert:place:74.64 65.64} {convert:place:10.131 8.131} {convert:place:52.52 45.52} {convert:place:78.0 68.0} {convert:place:15.9 12.9} {convert:place:70.143 61.143}}} {{body_alink #ff0000} {body_vlink #000080} {body_link #0000ff} {body_text #000000} {body_bgcolor #ffffff}}