man valtype::common (3): Validation, common code

SYNOPSIS

package require Tcl 8.5

package require valtype::common ?1?

valtype::common::reject code text

valtype::common::badchar code ?text?

valtype::common::badcheck code ?text?

valtype::common::badlength code lengths ?text?

valtype::common::badprefix code prefixes ?text?

DESCRIPTION

This package implements a number of common commands used by the validation types in this module. These commands essentially encapsulate the throwing of validation errors, ensuring that a proper -errorcode is used. See section Error Codes.

API

valtype::common::reject code text: The core command of this package it throws an INVALID error with the specified text. The first argument is a list of codes extending the INVALID with detail information.
valtype::common::badchar code ?text?: This command throws an INVALID CHAR error with the specified text. The first argument is a list of codes providing details. These are inserted between the codes INVALID and CHARACTER.
valtype::common::badcheck code ?text?: This command throws an INVALID CHECK-DIGIT error with the specified text, if any, extended by the standard text "the check digit is incorrect". The first argument is a list of codes providing details. These are inserted between the codes INVALID and CHECK_DIGIT.
valtype::common::badlength code lengths ?text?: This command throws an INVALID LENGTH error with the specified text, if any, extended by the standard text "incorrect length, expected ... character(s)". The first argument is a list of codes providing details. These are inserted between the codes INVALID and LENGTH. The argument lengths is a list of the input lengths which had been expected, i.e. these are the valid lengths.
valtype::common::badprefix code prefixes ?text?: This command throws an INVALID PREFIX error with the specified text, if any, extended by the standard text "incorrect prefix, expected ...". The first argument is a list of codes providing details. These are inserted between the codes INVALID and PREFIX. The argument prefixes is a list of the input prefixes which had been expected, i.e. these are the valid prefixes.

ERROR CODES

The errors thrown by the commands of this package all use the -errorcode INVALID to distinguish the input validation failures they represent from package internal errors.

To provide more detailed information about why the validation failed the -errorCode goes actually beyond that. First, it will contain a code detailing the type itself. This is supplied by the caller. This is then followed by values detailing the reason for the failure. The full set of -errorCodes which can be thrown by this package are shown below, with <> a placeholder for both the caller-supplied type-information, the type description.

INVALID <> CHARACTER: The input value contained one or more bad characters, i.e. characters which must not occur in the input for it to be a <>.
INVALID <> CHECK-DIGIT: The check digit of the input value is wrong. This usually signals a data-entry error, with digits transposed, forgotten, etc. Of course, th input may be an outright fake too.
INVALID <> LENGTH: The input value is of the wrong length to be a <>.
INVALID <> PREFIX: The input value does not start with the magic value(s) required for it to be a <>.

BUGS, IDEAS, FEEDBACK

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category valtype of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either package and/or documentation.

KEYWORDS

Checking, Testing, Type checking, Validation, Value checking, isA

COPYRIGHT

Copyright (c) 2011 Andreas Kupries <[email protected]>