punkshell_module_punk::args(0) 0.1.0 doc "args to option-value dict and values dict"

Concepts

There are 2 main conventions for parsing a proc args list

1. leading option-value pairs followed by a list of values (Tk style)

2. leading list of values followed by option-value pairs (Tcl style)

punk::args is focused on the 1st convention (Tk style): parsing of args in leading option-value pair style - even for non-Tk usage.

The proc can still contain some leading required values e.g

proc dostuff {arg1 arg2 args} {...}}

but having the core values elements at the end of args is more generally useful - especially in cases where the number of trailing values is unknown and/or the proc is to be called in a functional 'pipeline' style.

The basic principle is that a call to punk::args::opts_vals is made near the beginning of the proc e.g

   proc dofilestuff {args} {
       lassign [dict values [punk::args {
           -directory   -default ""
           -translation -default binary
       } $args]] opts values
       puts "translation is [dict get $opts -translation]"
       foreach f [dict values $values] {
           puts "doing stuff with file: $f"
       }
   }

Notes

There are alternative args parsing packages such as:

1. argp

2. The tcllib set of TEPAM modules

   TEPAM requires an alternative procedure declaration syntax instead of proc - but has support for Tk and documentation generation.

punk::args was designed initially without specific reference to TEPAM - and to handle some edge cases in specific projects where TEPAM wasn't suitable.

In subsequent revisions of punk::args - some features were made to operate in a way that is similar to TEPAM - to avoid gratuitous differences where possible, but of course there are differences

and those used TEPAM or mixing TEPAM and punk::args should take care to assess the differences.

TEPAM is a mature solution and is widely available as it is included in tcllib.

Serious consideration should be given to using TEPAM if suitable for your project.

dependencies

packages used by punk::args

• Tcl 8.6-

Namespace punk::args::class

class definitions

Namespace punk::args

Core API functions for punk::args

opts_values optionspecs rawargs ?option value...?

Parse rawargs as a sequence of zero or more option-value pairs followed by zero or more values

Returns a dict of the form: opts <options_dict> values <values_dict>

ARGUMENTS:

multiline-string optionspecs

This a block of text with records delimited by newlines (lf or crlf) - but with multiline values allowed if properly quoted/braced

'info complete' is used to determine if a record spans multiple lines due to multiline values

Each optionspec line must be of the form:

-optionname -key val -key2 val2...

where the valid keys for each option specification are: -default -type -range -choices -optional

list rawargs

This is a list of the arguments to parse. Usually it will be the \$args value from the containing proc

Namespace punk::args::lib

Secondary functions that are part of the API

Namespace punk::args::system

Internal functions that are not part of the API