SimpleType v1.0 

 The Simple Development Library types handling 

Project: the Simple Development Library.

Table of contents

1. Package description

Synopsis: the Simple Development Library types handling.

Keywords: type, decimal, hexadecimal, binary, octal, base, convert, range and array.

1.1 Overview

This package allows to handle types. A type associates a type name to a matching script used to assess whether a value conforms to the type.

Procedures are provided to declare (although a wealth of predefined types are supplied) delete and modify types, get information about a type and obtain the list of types, as well as several others to convert between different types. ::Simple::Type::is allows to assess whether a value conforms to a type.

1.2 Usage

Types are declared via ::Simple::Type::declare or embedded within programs (declare-program) or packages (declare-package). Types can be deleted via ::Simple::Type::delete or modified via ::Simple::Type::modify. The ::Simple::Type::information procedure provides several subcommands to query information about types: exists, declared, description and matchingscript.

The ::Simple::Type::convert set of procedures convert a value between different types. The ::Simple::Type::is procedure returns whether a value conforms to a type.

There are two kind of types: basic and derived. Derived types are derived from basic types and are denoted as basic type-derivation where basic type is the basic type name (such as integer) and derivation is the kind of derivation. All basic types can be derived but boolflag. Four derivations are currently supported: arrays, pairs, lists and ranges:

• Derived array types (basic type-array) denote the name of an array whose elements conform to the type. Non-existing arrays conform to all types.

• Derived pair types (basic type-pairs) denote a list with an even number of elements suitable to be given as argument to the array get command. The second element in each pair conforms to the basic type.

• Derived list types (basic type-list) denote a list whose elements conform to the basic type.

• Derived range types (numeric-range) denote a range whose limits conform to the type which must be numeric, i.e., one of integer, float, decimal, hexadecimal, binary, octal, anybase or number. The form of the range is lower limit:upper limit where the lower, the upper or even both limits may be missing. The colon may also be missing if just one limit is given: the range is restricted then to that exact value; this also happens if both limits are equal.

The double derivation numeric-range-list is also valid and corresponds to a list of numeric ranges, such as {1 -2:3 :100} for the integer-range-list type. As the double derivation type-list-array is always valid for any type but boolflag, it follows that the triple derivation numeric-range-list-array is also valid.

Derived types are only accepted by the ::Simple::Type::is and ::Simple::Type::information exists procedures.

1.3 Examples

# Install the package
package require SimplePackage
::Simple::Package::require-and-install SimpleType

# Configure The Simple Development Library to store the metadata
::Simple::configure -storemetadata true

# Declare a type bar which can only hold either bar or BAR
::Simple::Type::declare {
   bar
} -description {
   can only hold either bar or BAR
} -matchingscript {
   return [expr\ 
      {![string compare $value bar] || ![string compare $value BAR]}]
}

# Assert the type bar exists
# This displays the following:
#   |The type bar exists
if {[::Simple::Type::information exists bar]} {
   puts {The type bar exists}
}

# Get some information about the type bar
# This displays the following:
#   |The type bar can only hold either bar or BAR
puts "The type bar [::Simple::Type::information description bar]"

# Check the allowed contents for a variable of type bar
# This displays the following:
#   |"bar" is of type bar
#   |"foo" is NOT of type bar
#   |"BAR" is of type bar
#   |"bAR" is NOT of type bar
foreach contents {bar foo BAR bAR} {
   puts -nonewline "\"$contents\" is "
   if {![::Simple::Type::is bar $contents]} {
      puts -nonewline {NOT }
   }
   puts {of type bar}
}

# Get rid of the type bar
::Simple::Type::delete bar

# Assert the type bar no longer exists
# This displays the following:
#   |The type bar no longer exists
if {![::Simple::Type::information exists bar]} {
   puts {The type bar no longer exists}
}

# More fun. A type made of three elements:
# an integer, a boolean and an alphabetic
::Simple::Type::declare {
   foo
} -description {
   integer + boolean + alphabetic
} -matchingscript {
   foreach localType [list integer boolean alphabetic] localValue $value {
      if {![::Simple::Type::is $localType $localValue]} {
         return 0
      }
   }
   return 1
}

# Check the allowed contents for a variable of type foo
# This displays the following:
#   |"2 1 bar" is of type foo
#   |"2 x bar" is NOT of type foo
foreach contents {{2 1 bar} {2 x bar}} {
   puts -nonewline "\"$contents\" is "
   if {![::Simple::Type::is foo $contents]} {
      puts -nonewline {NOT }
   }
   puts {of type foo}
}

# Derived list type
# This displays the following:
#   |"-2:1" is a proper integer range
#   |"2:1" is NOT a proper integer range
foreach contents {{-2:1} {2:1}} {
   puts -nonewline "\"$contents\" is "
   if {![::Simple::Type::is integer-range $contents]} {
      puts -nonewline {NOT }
   }
   puts {a proper integer range}
}

# Derived range type
# This displays the following:
#   |"1.0 3 -1.E-2" is a proper list of floats
#   |"1.0 foo -2.1" is NOT a proper list of floats
foreach contents {{1.0 3 -1.E-2} {1.0 foo -2.1}} {
   puts -nonewline "\"$contents\" is "
   if {![::Simple::Type::is float-list $contents]} {
      puts -nonewline {NOT }
   }
   puts {a proper list of floats}
}

1.4 History

1.5 Copyright

Copyright (C) 1999-2005, Juan C. Gil (jgil@gmv.es).

2. Package public API

Paradigm: procedural.

Requisites: SimpleSubcommand 1.0.

2.1 Types

2.1.1 integer

Description: integer number: +1, 0, -192, ...

2.1.2 float

Description: floating point number: -1.2e23, +3.0, ...

2.1.3 decimal

Description: decimal number: 1234, ...

2.1.4 hexadecimal

Description: hexadecimal number: xF12, ...

2.1.5 binary

Description: binary number: b01011, ...

2.1.6 octal

Description: octal number: 0723, ...

2.1.7 anybase

Description: decimal, hexadecimal, binary or octal number.

2.1.8 number

Description: any number.

2.1.9 character

Description: character.

2.1.10 string

Description: string.

2.1.11 alphabetic

Description: alphabetic (letters only).

2.1.12 alphanumeric

Description: alphanumeric (letters and digits).

2.1.13 boolean

Description: boolean: 0 or 1.

2.1.14 extbool

Description: Tcl extended boolean: 0, 1, true, false, ...

2.1.15 word

Description: Tcl word.

2.1.16 script

Description: Tcl script.

2.1.17 expression

Description: Tcl expression: 2 + 3, ...

2.1.18 list

Description: Tcl list.

2.1.19 channel

Description: Tcl channel: stdin, file0, sock2, ...

2.1.20 namespace

Description: Tcl namespace: ::foo::bar, ...

2.1.21 qualifiedname

Description: Tcl qualified name: ::foo::Bar, ::foo::bar, ...

2.1.22 unqualifiedname

Description: Tcl unqualified name: foo, Bar, ...

2.1.23 name

Description: Tcl qualified or unqualified name: foo, ::Bar, ...

2.1.24 commandname

Description: Tcl command name with optional subcommand: foo bar, ::Gee zuu, ...

2.1.25 unqualifiedcommandname

Description: Tcl command name with optional subcommand: foo bar, Gee zuu, ...

2.1.26 qualifiedvariablename

Description: Tcl qualified variable name: ::foo::Bar, ::foo::bar(gee), ...

2.1.27 unqualifiedvariablename

Description: Tcl unqualified variable name: foo, Bar(gee), ...

2.1.28 variablename

Description: Tcl qualified or unqualified variable name: foo, ::Bar(gee), ...

2.1.29 variableorcommandname

Description: Tcl qualified or unqualified variable or command name: ::Bar(gee), bar gee, ...

2.1.30 pattern

Description: Tcl pattern: foo*bar, ...

2.1.31 regexp

Description: Tcl regular expression: [A-Z]+, ...

2.1.32 formatstring

Description: Tcl format string.

2.1.33 widget

Description: Tk widget: .foo.bar, ...

2.1.34 type

Description: type name: integer, ...

2.1.35 flag

Description: flag: -name, ...

2.1.36 optional

Description: optional variable: ?name?, ...

2.1.37 declaration

Description: item declaration: a list containing a class, command, ... declaration.

2.1.38 date

Description: date: Fri Feb 03 19:09:35 WET 1984, ...

2.1.39 choice

Description: choice list: {one two three}, ...

2.1.40 any

Description: any value.

2.1.41 boolflag

Description: boolean flag.

2.1.42 url

Description: URL: http://wiki.tcl.tk.

2.2 Options

None.

2.3 Namespaces

1. ::Simple::Type

2. ::Simple::Type::Priv

2.4 Commands

2.4.1 ::Simple::Type::assert-is type value ?extra? ?description?

Synopsis: throws an error if a value does not conform to a type.

Details: see section 4.1.

2.4.2 ::Simple::Type::cget

Synopsis: gets the package options.

Details: see section 4.2.

2.4.3 ::Simple::Type::configure

Synopsis: configures the package options.

Details: see section 4.3.

2.4.4 ::Simple::Type::convert binary integer

Synopsis: converts an integer in any base to binary.

Details: see section 4.4.

2.4.5 ::Simple::Type::convert boolean extBoolean

Synopsis: converts an extended boolean to boolean.

Details: see section 4.5.

2.4.6 ::Simple::Type::convert decimal integer

Synopsis: converts an integer in any base to decimal.

Details: see section 4.6.

2.4.7 ::Simple::Type::convert flag flag

Synopsis: converts a flag to an unqualified name.

Details: see section 4.7.

2.4.8 ::Simple::Type::convert hexadecimal integer

Synopsis: converts an integer in any base to hexadecimal.

Details: see section 4.8.

2.4.9 ::Simple::Type::convert octal integer

Synopsis: converts an integer in any base to octal.

Details: see section 4.9.

2.4.10 ::Simple::Type::convert optional optional

Synopsis: converts an optional value to an unqualified name.

Details: see section 4.10.

2.4.11 ::Simple::Type::declare type ?-description string? ?-matchingscript script?

Synopsis: declares a type.

Details: see section 4.11.

2.4.12 ::Simple::Type::delete type

Synopsis: deletes a type.

Details: see section 4.12.

2.4.13 ::Simple::Type::information declared ?typePattern?

Synopsis: returns the list of declared types.

Details: see section 4.13.

2.4.14 ::Simple::Type::information description type

Synopsis: returns a type description.

Details: see section 4.14.

2.4.15 ::Simple::Type::information exists type

Synopsis: returns whether a type exists.

Details: see section 4.15.

2.4.16 ::Simple::Type::information matchingscript type

Synopsis: returns a type matching script.

Details: see section 4.16.

2.4.17 ::Simple::Type::is type value ?extra?

Synopsis: returns whether a value conforms to a type.

Details: see section 4.17.

2.4.18 ::Simple::Type::modify description type description

Synopsis: modifies a type description.

Details: see section 4.18.

2.4.19 ::Simple::Type::modify matchingscript type matchingScript

Synopsis: modifies a type matching script.

Details: see section 4.19.

2.4.20 ::Simple::Type::outside-range range value

Synopsis: returns whether a numeric value is outside a numeric range.

Details: see section 4.20.

2.5 Errors

2.5.1 ::Simple::Type::BAD-DERIVED-TYPE

Message: invalid derived type "derived type".

Explanation: the derived type derived type is invalid. All basic types can be derived but "boolflag". The only derived range types valid are those in which the basic type is one of integer, float, decimal, hexadecimal, binary, octal, anybase or number.

2.5.2 ::Simple::Type::DERIVED-TYPE-OUT-OF-CONTEXT

Message: a derived type such as "derived type" is not valid in this context.

Explanation: derived type is a derived type, but these types are valid for the ::Simple::Type::is and ::Simple::Type::information exists procedures only.

2.5.3 ::Simple::Type::NEGATIVE-INT

Message: negative integer "integer".

Explanation: the integer integer is negative but a positive integer was expected.

2.5.4 ::Simple::Type::ALREADY-EXISTS

Message: type "type" already exists.

Explanation: type type could not be created because it already exists.

Corrective action: delete the type.

3. Package further information

3.1 Details

• This package supports the concept of hidden types for internal use by The Simple Development Library. Hidden types are similar to regular types, but they remain hidden to the public API. The purpose is that packages that define new types may use those types for other entities (variables, attributes, commands arguments, ...) but the types remain hidden until package installation.

3.2 Todo

• Extend the concept of derived types to support arbitrary nested extensions of lists such as integer-list-list. Not only that, but derivations such as integer-pairs-list or word-pairs-array should be handled correctly. The ::Simple::Type::is and ::Simple::Type::information exists procedures should be adapted to invoke themselves recursively for such multiple derivations.

• It would be nice to have a procedure which guesses the type of a given value.

• The basic name regular expression ([_a-zA-Z0-9%][-_a-zA-Z0-9%]*) should be a package option. All type matching scripts requiring it should reference the package option. Alternatively, for maximum performance, upon changing this option, all types matching scripts using it should be recreated.

4. Package command details

4.1 ::Simple::Type::assert-is type value ?extra? ?description?

4.1.1 Command description

Synopsis: throws an error if a value does not conform to a type.

Access mode: public.

4.1.1.1 Overview

This procedure throws an error if a value does not conform to a type. The message uses the description, if given; otherwise, the type description is used, if it was stored when the type was created; otherwise, the type name is used.

4.1.2 Command public API

Arguments:

Returns: error if the value does not conform to the type.

4.1.3 Command further information

4.1.3.1 Remarks

• The value %DEFAULT% conforms to all types

4.2 ::Simple::Type::cget

4.2.1 Command description

Synopsis: gets the package options.

Access mode: public.

4.2.2 Command public API

Arguments: none.

Returns: the requested option value or the whole list of options if none specified.

4.3 ::Simple::Type::configure

4.3.1 Command description

Synopsis: configures the package options.

Access mode: public.

4.3.2 Command public API

Arguments: none.

Returns: the "package with no options" error is thrown.

4.4 ::Simple::Type::convert binary integer

4.4.1 Command description

Synopsis: converts an integer in any base to binary.

Access mode: public.

Keywords: decimal, hexadecimal, binary, octal, base and convert.

4.4.1.1 Overview

Converts a decimal, hexadecimal, binary or octal integer to binary base. The resulting binary constant is of the form 0bbinary-digits. where binary-digits are a sequence of 0s and 1s.

4.4.2 Command public API

Arguments:

Returns: the converted integer.

4.5 ::Simple::Type::convert boolean extBoolean

4.5.1 Command description

Synopsis: converts an extended boolean to boolean.

Access mode: public.

Keywords: boolean and convert.

4.5.1.1 Overview

This procedure converts from extended booleans (true/false, yes/no or on/off) to 1/0 because the Tcl expr and if commands can't use non-numeric string as operand of "!" (sic).

4.5.1.2 Examples

# A robust negation test
if {![::Simple::Type::convert boolean $extbool]} {
   puts "$extbool is false"
}

4.5.2 Command public API

Arguments:

Returns: the converted boolean.

4.6 ::Simple::Type::convert decimal integer

4.6.1 Command description

Synopsis: converts an integer in any base to decimal.

Access mode: public.

Keywords: decimal, hexadecimal, binary, octal, base and convert.

4.6.1.1 Overview

Converts a decimal, hexadecimal, binary or octal integer to decimal base.

4.6.2 Command public API

Arguments:

Returns: the converted integer.

4.7 ::Simple::Type::convert flag flag

4.7.1 Command description

Synopsis: converts a flag to an unqualified name.

Access mode: public.

4.7.2 Command public API

Arguments:

Returns: the flag name.

4.8 ::Simple::Type::convert hexadecimal integer

4.8.1 Command description

Synopsis: converts an integer in any base to hexadecimal.

Access mode: public.

Keywords: decimal, hexadecimal, binary, octal, base and convert.

4.8.1.1 Overview

Converts a decimal, hexadecimal, binary or octal integer to hexadecimal base. The resulting hexadecimal constant is of the form 0xhexadecimal-digits where hexadecimal-digits are a sequence of uppercase hexadecimal digits, that is, the "0x" prefix contains a lowercase "x" but the actual digits are uppercase. This is different from the result of the "%#X" format specifier which returns an uppercase "X".

4.8.2 Command public API

Arguments:

Returns: the converted integer.

4.9 ::Simple::Type::convert octal integer

4.9.1 Command description

Synopsis: converts an integer in any base to octal.

Access mode: public.

Keywords: decimal, hexadecimal, binary, octal, base and convert.

4.9.1.1 Overview

Converts a decimal, hexadecimal, binary or octal integer to octal base.

4.9.2 Command public API

Arguments:

Returns: the converted integer.

4.10 ::Simple::Type::convert optional optional

4.10.1 Command description

Synopsis: converts an optional value to an unqualified name.

Access mode: public.

4.10.2 Command public API

Arguments:

Returns: the optional value name.

4.11 ::Simple::Type::declare type ?-description string? ?-matchingscript script?

4.11.1 Command description

Synopsis: declares a type.

Access mode: public.

4.11.1.1 Overview

This procedure is used to declare a new type.

A type is made of three elements:

1. the type name,

2. the type description and

3. type matching script.

The type name is an all-lowercase string. The type matching script is a Tcl script used to check whether a value conforms to the type. It shall assume that the value to be checked is passed in the value variable, and shall return either 1 or 0 depending on whether the value conforms to the type or not; throwing an error is also a valid action for non-conforming values. It gets evaluated as a procedure, so use upvar and uplevel to access the current stack level if needed.

A type with no empty matching script may hold any value.

4.11.1.2 Examples

# Declare a type "foo" which may hold any value
::Simple::Type::declare foo

# Declare a type bar which can only hold either bar or BAR
::Simple::Type::declare -matchingscript {
   return [expr {![string compare $value bar] || ![string compare $value BAR]}]
}

4.11.2 Command public API

Arguments:

Returns: the empty string.

Effects:

• Creates the type matching procedure named ::Simple::Type::Priv::%MATCHING%-type.

4.11.3 Command further information

4.11.3.1 Remarks

• The order of the flags is irrelevant but their parameters can not start by an hyphen.

4.12 ::Simple::Type::delete type

4.12.1 Command description

Synopsis: deletes a type.

Access mode: public.

4.12.2 Command public API

Arguments:

Returns: the empty string.

Effects:

• Deletes the type matching procedure named ::Simple::Type::Priv::%MATCHING%-type.

4.13 ::Simple::Type::information declared ?typePattern?

4.13.1 Command description

Synopsis: returns the list of declared types.

Access mode: public.

4.13.1.1 Overview

This procedure returns the list of declared types matching the given pattern. This includes native The Simple Development Library types as well as others declared via the ::Simple::Type::declare procedure.

4.13.2 Command public API

Arguments:

Returns: the list of types matching the given pattern.

4.13.3 Command further information

4.13.3.1 Remarks

• Use no pattern to obtain the complete list of types.

4.14 ::Simple::Type::information description type

4.14.1 Command description

Synopsis: returns a type description.

Access mode: public.

4.14.2 Command public API

Arguments:

Returns: the type description.

4.15 ::Simple::Type::information exists type

4.15.1 Command description

Synopsis: returns whether a type exists.

Access mode: public.

4.15.1.1 Overview

This procedure returns whether a type exists. This includes native The Simple Development Library types as well as others declared via the ::Simple::Type::declare procedure. For derived types, the procedure returns whether the basic type exists.

4.15.2 Command public API

Arguments:

Returns: whether the type exists.

4.16 ::Simple::Type::information matchingscript type

4.16.1 Command description

Synopsis: returns a type matching script.

Access mode: public.

4.16.2 Command public API

Arguments:

Returns: the type matching script.

4.17 ::Simple::Type::is type value ?extra?

4.17.1 Command description

Synopsis: returns whether a value conforms to a type.

Access mode: public.

Keywords: type.

4.17.1.1 Overview

This procedure returns whether a value conforms to a type.

If the type is a derived list type, the value is considered a list of values, and the procedure returns whether all of them conform to the basic type. Empty lists conform to all types.

If the type is a derived array type, the value is considered the name of an array of values in the calling scope, and the procedure returns whether all of them conform to the basic type. Non-existing arrays conform to all types.

If the type is a derived range type, the value is considered a range whose limits are of the basic type.

4.17.2 Command public API

Arguments:

Returns: whether the value conforms to the type.

4.17.3 Command further information

4.17.3.1 Remarks

• The value %DEFAULT% conforms to all types

4.18 ::Simple::Type::modify description type description

4.18.1 Command description

Synopsis: modifies a type description.

Access mode: public.

4.18.2 Command public API

Arguments:

Returns: the empty string.

4.19 ::Simple::Type::modify matchingscript type matchingScript

4.19.1 Command description

Synopsis: modifies a type matching script.

Access mode: public.

4.19.2 Command public API

Arguments:

Returns: the empty string.

Effects:

• Recreates the type matching procedure named ::Simple::Type::Priv::%MATCHING%-type.

4.20 ::Simple::Type::outside-range range value

4.20.1 Command description

Synopsis: returns whether a numeric value is outside a numeric range.

Access mode: public.

4.20.2 Command public API

Arguments:

Returns: -1, 0 or 1, depending on whether the value is lower than the lower range limit, within the range or greater than the upper range limit.