'\"
'\" Generated from file 'cmdr_vtypes\&.man' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2013-2016 Andreas Kupries
'\" Copyright (c) 2013-2016 Documentation, Andreas Kupries
'\"
.TH "cmdr-user-vtypes" n 1 doc "Cmdr, a framework for command line parsing and dispatch"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive
.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"
.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..
.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
cmdr-user-vtypes \- Cmdr - Writing custom validation types
.SH SYNOPSIS
package require \fBcmdr::validate \fR
.sp
\fB<v-type>\fR \fBcomplete\fR \fIp\fR \fIx\fR
.sp
\fB<v-type>\fR \fBdefault\fR \fIp\fR
.sp
\fB<v-type>\fR \fBrelease\fR \fIp\fR \fIx\fR
.sp
\fB<v-type>\fR \fBvalidate\fR \fIp\fR \fIx\fR
.sp
.BE
.SH DESCRIPTION
.PP
Welcome to the Cmdr project, written by Andreas Kupries\&.
.PP
For availability please read \fICmdr - How To Get The Sources\fR\&.
.PP
This document describes the API expected of \fIvalidation types\fR
to make them usable within the Cmdr framework, and how to
write a custom validation type\&.
.PP
Readers interested in the standard validation types of the
framework should read \fICmdr - Standard validation types for parameters\fR\&.
.SH BACKGROUND
Validation types are Cmdr's answer to the necessity of moving
between the string and internal representations of
\fBcmdr::parameter\fR instances\&.
Given a \fIstring representation\fR they either return the
associated \fIinternal representation\fR 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\&.
.PP
The general concept of \fIvalidation types\fR was taken from
\fBsnit\fR, 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 \fIfour\fR
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
\fBAPI\fR below\&.
.PP
As an example the implementation of the standard boolean
validation type is shown in section \fBExample\fR\&.
.PP
It should be noted that while \fBsnit\fR'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\&.
.PP
The \fBvalidate\fR and \fBrelease\fR methods are primarily used
during either \fICompletion\fR or \fIExecution\fR phases, depending
on the chosen deferal state\&.
They may also be used during the \fIParsing\fR phase, for optional
\fIinputs\fR under the \fBtest\fR-regime]\&.
.PP
The \fBcomplete\fR method will be used whereever the system
activates an interactive command line shell where arguments may be
assigned to parameters\&.
.PP
The \fBdefault\fR method on the other hand can expect to be
invoked during the \fIDispatch\fR phase, as part of the system's
declaration processing, if not preempted by \fBdefault\fR and
\fBgenerate\fR declarations for the parameter\&.
Note here that the \fBdefault\fR method has the same signature as a
paramete's \fBgenerate\fR 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 \fBgenerate\fR to change the timing of its invokation\&.
.SH API
In the descriptions below the \fB<v-type>\fR is a placeholder for the
actual command prefix, most often a main command, of the validation
type\&.
.TP
\fB<v-type>\fR \fBcomplete\fR \fIp\fR \fIx\fR
This method is invoked during command completion done by the framework\&.
.sp
It has to return the list of legal string representations for
the type and parameter instance \fIp\fR which have the incomplete word
\fIx\fR as their prefix\&.
.RS
.TP
\fBcmdr::parameter\fR \fIp\fR
The \fBcmdr::parameter\fR 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\&.
.TP
string \fIx\fR
The string value to complete\&.
.RE
.TP
\fB<v-type>\fR \fBdefault\fR \fIp\fR
This method is invoked when the framework has to determine the
internal representation of a parameter which has no user-specified
string representation\&.
.sp
It has to return the default internal representation for
the type and parameter instance \fIp\fR\&.
.RS
.TP
\fBcmdr::parameter\fR \fIp\fR
The \fBcmdr::parameter\fR 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\&.
.RE
.TP
\fB<v-type>\fR \fBrelease\fR \fIp\fR \fIx\fR
This method is invoked when the framework has to get rid of an
internal representation for a parameter\&.
.sp
It has to release any resources associated with the internal
representation \fIx\fR of parameter instance \fIp\fR\&.
.sp
Note that the result of this method, if there is any, is
ignored by the framework\&.
.RS
.TP
\fBcmdr::parameter\fR \fIp\fR
The \fBcmdr::parameter\fR 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\&.
.TP
string \fIx\fR
The internal representation to release\&.
.RE
.TP
\fB<v-type>\fR \fBvalidate\fR \fIp\fR \fIx\fR
This method is invoked during to validate and convert a string
representation\&.
.sp
It has to verify that \fIx\fR is a legal string representation
for the parameter instance \fIp\fR, and return the associated internal
representation\&.
.RS
.TP
\fBcmdr::parameter\fR \fIp\fR
The \fBcmdr::parameter\fR 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 \fIUtilities for Validation Types\fR for commands helping
with keeping validation error messages uniform\&.
.TP
string \fIx\fR
The string value to validate cand convert\&.
.RE
.PP
.SH EXAMPLE
As an example the implementation of the standard boolean validation
type is shown here\&.
.PP
Note that while this example uses a \fBnamespace ensemble\fR
other methods are possible too, i\&.e\&. all the various object systems
for Tcl would be suitable as well\&.
.CS


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
}

.CE
.SH "BUGS, IDEAS, FEEDBACK"
Both the package(s) and this documentation will undoubtedly contain
bugs and other problems\&.
Please report such at
\fICmdr Tickets\fR [https:/core\&.tcl\&.tk/akupries/cmdr]\&.
.PP
Please also report any ideas you may have for enhancements of
either package(s) and/or documentation\&.
.SH 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
.SH COPYRIGHT
.nf
Copyright (c) 2013-2016 Andreas Kupries
Copyright (c) 2013-2016 Documentation, Andreas Kupries

.fi