[ Home | Main Table Of Contents | Table Of Contents | Keyword Index ]

cmdr-user-vtypes(n) 1.0 doc "Cmdr, a framework for command line parsing and dispatch"

Name

cmdr-user-vtypes - Cmdr - Writing custom validation types

Table Of Contents

Synopsis

Description

Welcome to the Cmdr project, written by Andreas Kupries.

For availability please read Cmdr - How To Get The Sources.

This document describes the API expected of validation types to make them usable within the Cmdr framework, and how to write a custom validation type.

Readers interested in the standard validation types of the framework should read Cmdr - Standard validation types for parameters.

Background

Validation types are Cmdr's answer to the necessity of moving between the string and internal representations of cmdr::parameter instances. Given a string representation they either return the associated internal representation or raise an error, signaling that the string was illegal. This part of their work, the verification of the legality of the input string gave them their name.

The general concept of validation types was taken from snit, and modified to suit Cmdr. Where snit's types expect only a single method to validate the input Cmdr expects all types to support an ensemble of four methods. One for the basic validation and transformation of the input, another for the release of any internal representation so generated, plus two more for delivery of a default representation and support for command line completion. The details (method names, signatures, etc.) can be found in section API below.

As an example the implementation of the standard boolean validation type is shown in section Example.

It should be noted that while snit's validation types in principle allow for the transformation of input into a disparate internal representation, they never went so far as to allow complex representations which might require the release of resources after use.

The validate and release methods are primarily used during either Completion or Execution phases, depending on the chosen deferal state. They may also be used during the Parsing phase, for optional inputs under the test-regime].

The complete method will be used whereever the system activates an interactive command line shell where arguments may be assigned to parameters.

The default method on the other hand can expect to be invoked during the Dispatch phase, as part of the system's declaration processing, if not preempted by default and generate declarations for the parameter. Note here that the default method has the same signature as a paramete's generate callback and can be used as such. This is actually needed and useful when the default internal representation for a validation type cannot be expressed as a fixed value and its creation while parsing the specification itself is too early. We can still use the validation type for its generation, by hooking it explicitly into generate to change the timing of its invokation.

API

In the descriptions below the <v-type> is a placeholder for the actual command prefix, most often a main command, of the validation type.

<v-type> complete p x

This method is invoked during command completion done by the framework.

It has to return the list of legal string representations for the type and parameter instance p which have the incomplete word x as their prefix.

cmdr::parameter p

The cmdr::parameter instance governing the completion process. While the standard validation types do not make use of it a custom type may have need for access to the context of the completion.

string x

The string value to complete.

<v-type> default p

This method is invoked when the framework has to determine the internal representation of a parameter which has no user-specified string representation.

It has to return the default internal representation for the type and parameter instance p.

cmdr::parameter p

The cmdr::parameter instance whose default internal representation is to be computed. While the standard validation types do not make use of it a custom type may have need for access to the context.

<v-type> release p x

This method is invoked when the framework has to get rid of an internal representation for a parameter.

It has to release any resources associated with the internal representation x of parameter instance p.

Note that the result of this method, if there is any, is ignored by the framework.

cmdr::parameter p

The cmdr::parameter instance holding the internal representation to release. While the standard validation types do not make use of it a custom type may have need for access to the context of the completion.

string x

The internal representation to release.

<v-type> validate p x

This method is invoked during to validate and convert a string representation.

It has to verify that x is a legal string representation for the parameter instance p, and return the associated internal representation.

cmdr::parameter p

The cmdr::parameter instance governing the validation process. The standard validation types make use of it in case of a validation failure to generate a proper error message. See also Utilities for Validation Types for commands helping with keeping validation error messages uniform.

string x

The string value to validate cand convert.

Example

As an example the implementation of the standard boolean validation type is shown here.

Note that while this example uses a namespace ensemble other methods are possible too, i.e. all the various object systems for Tcl would be suitable as well.

package require cmdr::validate::common
namespace eval ::cmdr::validate::boolean {
    namespace export default validate complete release
    namespace ensemble create
    namespace import ::cmdr::validate::common::fail
    namespace import ::cmdr::validate::common::complete-enum
}
proc ::cmdr::validate::boolean::release {p x} {
    # Simple internal representation. Nothing to release.
    return
}
proc ::cmdr::validate::boolean::default {p}  {
    return no
}
proc ::cmdr::validate::boolean::complete {p x} {
    # x is string representation. Result as well.
    return [complete-enum {
	yes no false true on off 0 1
    } 1 $x]
}
proc ::cmdr::validate::boolean::validate {p x} {
    # x is string representation. Result is internal representation.
    if {[string is boolean -strict $x]} {
	return $x
    }
    fail $p BOOLEAN "a boolean" $x
}

Bugs, Ideas, Feedback

Both the package(s) and this documentation will undoubtedly contain bugs and other problems. Please report such at Cmdr Tickets.

Please also report any ideas you may have for enhancements of either package(s) and/or documentation.

Keywords

arguments, command hierarchy, command line completion, command line handling, command tree, editing command line, help for command line, hierarchy of commands, interactive command shell, optional arguments, options, parameters, processing command line, tree of commands