dgtools - argvparse - recover - repo - shistory
dgtools::argvparse - command line parsing package similar to Pythons argparse library.
package require snit
package require dgtools::argvparse
namespace import ::dgtools::argvparse
argvparse cmdName options
cmdName cget option
cmdName configure option value
cmdName argument shortopt longopt description ?key ...?
cmdName parse argv
cmdName usage
dgtools::argvparse - is a snit type for parsing command line arguments for Tcl applications in the spirit of Pythons argparse library. Parsing command line options for this package is a three step process. First create the parser object with application specific options, like application name and author, in the second step define one or more arguments using the argument method for each option and at last use the parse function for parsing the argv array.
dgtools::argvparse cmdName ?options?
Creates and configures the dgtools::argvparse type using the given command name and options.
-appname string
Will be used as the application name shown in the standard help page.
-author string
Will be used as the author name shown in the standard help page.
-description string
Will be used as description string shown in the standard help page.
-usage string
Will be used as the usage string without the scriptname shown in the standard help page.
The argvparse type supports the following commands to parse command line arguments:
cmdName argument shortopt longopt description ?key value ...?
Installs a command line option using the given short- and longoption flags and the option description. The latter will be used in the standard help message. The following key-value pairs are supported:
cmdName cget option
Retrieves the given option value for the argvparse type. See options for a list of available options.
cmdName configure option value ?option value ...?
Configures the given option for the argvparse type. See options for a list of available options.
cmdName parse argv
Does the actual parsing of the argv array. Returns the parsing result as a key-value list.
cmdName usage ?msg?
Standard usage message for the terminal if the user did not provide the correct command line arguments or if the user requests the help message using either the with giving the short option -h or the long option --help.
package require dgtools::argvparse
# simulate: tclsh script.tcl --filename test.txt -v 1 -h
# on the terminal by manually setting argv
set argv [list --filename test.txt -v 1 -h]
proc mproc {args} {
puts "proc mproc is executed with args $args"
}
set ap [::dgtools::argvparse %AUTO% -appname "Test Application" \
-author "Detlef Groth" -usage "-f filename ?-t -m -v number -h?"]
$ap argument -f --filename "filename (input file)" -required true
$ap argument -t --test "(test flag)" -boolean true
$ap argument -m --mproc "(execute procedure mproc)" -script mproc
$ap argument -v --verbosity "number (specifying verbosity, values from 0 to 5)" \
-type integer -default 0
set res [$ap parse $argv]
If this script is executed it gives the following help message:
===============================
Test Application - Detlef Groth
===============================
Usage: argvparse.tcl -f filename ?-t -m -v number -h?
Mandatory arguments:
-f, --filename filename (input file)
Optional arguments:
-h, --help (show this help page)
-m, --mproc (execute procedure mproc)
-t, --test (test flag)
-v, --verbosity number (specifying verbosity, values from 0 to 5)
Installation is easy, you can install and use the dgtools::argvparse package if you have a working install of:
For installation you copy the complete dgtools folder into a path of your auto_path list of Tcl or you append the auto_path list with the parent dir of the dgtools directory. Alternatively you can install the package as a Tcl module by creating a file dgtools/argvparse-0.2.tm in your Tcl module path. The latter in many cases can be achieved by using the --install option of argvparse.tcl. Try "tclsh argvparse.tcl --install" for this purpose in the terminal.
Example code for this package can be executed by running this file using the following command line:
$ tclsh argvparse.tcl --demo
The example code used for this demo can be seen in the terminal by using the following command line:
$ tclsh argvparse.tcl --code
Some tcltest's are embedded in the source file as well, to run those tests you should execute the following comamnd line:
$ tclsh argvparse.tcl --test
The script contains embedded the documentation in Markdown format. To extract the documentation you should use the following command line:
$ tclsh argvparse.tcl --markdown
This will extract the embedded manual pages in standard Markdown format. You can as well use this markdown output directly to create html pages for the documentation by using the --html flag.
$ tclsh argvparse.tcl --html
This will directly create a HTML page argvparse.html which contains the formatted documentation.
Github-Markdown can be extracted by using the --man switch:
The output of this command can be used to feed a markdown processor for conversion into a man page, a html or a pdf document. If you have pandoc installed for instance, you could execute the following commands:
# man page
tclsh argvparse.tcl --man | pandoc -s -f markdown -t man - > argvparse.n
# html page
tclsh ../argvparse.tcl --man > argvparse.md
pandoc -i argvparse.md -s -o argvparse.html
# pdf
pandoc -i argvparse.md -s -o argvparse.tex
pdflatex argvparse.tex
The argvparse snit type was written by Detlef Groth, Schwielowsee, Germany.
Command line parsing library dgtools::argvparse, version 0.2.
Copyright (c) 2019 Dr. Detlef Groth, E-mail: detlef(at)dgroth(dot)de
This library is free software; you can use, modify, and redistribute it for any purpose, provided that existing copyright notices are retained in all copies and that this notice is included verbatim in any distributions.
This software is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.