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

# cmdr::validate::common(n) 1.2 doc "Cmdr, a framework for command line parsing and dispatch"

## Name

cmdr::validate::common - Cmdr - Utilities for Validation Types

## Table Of Contents

## Synopsis

- package require cmdr::validate::common

- ::cmdr::validate::common fail p code type x ?context?
- ::cmdr::validate::common fail-unknown-thing p code type x ?context?
- ::cmdr::validate::common fail-unknown-thing-msg msg p code type x ?context?
- ::cmdr::validate::common fail-unknown-simple p code type x ?context?
- ::cmdr::validate::common fail-unknown-simple-msg msg p code type x ?context?
- ::cmdr::validate::common fail-known-thing p code type x ?context?
- ::cmdr::validate::common fail-known-thing-msg msg p code type x ?context?
- ::cmdr::validate::common fail-known-simple p code type x ?context?
- ::cmdr::validate::common fail-known-simple-msg msg p code type x ?context?
- ::cmdr::validate::common complete-enum choices nocase buffer
- ::cmdr::validate::common complete-substr choices nocase buffer
- ::cmdr::validate::common complete-glob filter buffer
- ::cmdr::validate::common ok-directory path
- ::cmdr::validate::common lead-in text

## Description

Welcome to the Cmdr project, written by Andreas Kupries.

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

This package publicly exports three commands for use in the implementation of validation types. The standard validation types defined in package cmdr::validate make use of these commands.

## API

::cmdr::validate::common fail p code type x ?context?

  When invoked this command throws an error indicating a validation type failure. The arguments provide the information used to construct both error message and code.

  The generated string has the form:

          Expected $type for $p.type "$x"$context, got "$x"

  cmdr::parameter p

    The cmdr::parameter instance whose validation failed. The error message will contain this parameter's type and label (flag in case of an option).

  list code

    A list of additional elements for the error code to throw. Should detail the internal name of the validation type triggering the error.

  string type

    A string holding a human-readable name for the validation type triggering the error. (Conversely to the code, which is for machine-readability, i.e. trapping)

  string x

    The string value which failed the validation.

  string context

    Additional context to show in the message. Defaults to the empty string.

::cmdr::validate::common fail-unknown-thing p code type x ?context?

  When invoked this command throws an error indicating a validation type failure. The arguments provide the information used to construct both error message and code.

  The generated string has the form:

          Found a problem with $p.type "$p.the-name":
          A(n) $type named "$x" does not exist$context.
           Please use a different value.

  cmdr::parameter p

    The cmdr::parameter instance whose validation failed. The error message will contain this parameter's type and label (flag in case of an option).

  list code

    A list of additional elements for the error code to throw. Should detail the internal name of the validation type triggering the error.

  string type

    A string holding a human-readable name for the validation type triggering the error. (Conversely to the code, which is for machine-readability, i.e. trapping)

  string x

    The string value which failed the validation.

  string context

    Additional context to show in the message. Defaults to the empty string.

::cmdr::validate::common fail-unknown-thing-msg msg p code type x ?context?

  A variant of fail-unknown-thing which takes an additional user-specified message text as the first argument.

  When invoked this command throws an error indicating a validation type failure. The arguments provide the information used to construct both error message and code.

  The generated string has the form:

          Found a problem with $p.type "$p.the-name":
          A(n) $type named "$x" does not exist$context.
           $msg.

  string msg

    A custom message to put into the generated error message. See the example above.

  cmdr::parameter p

    The cmdr::parameter instance whose validation failed. The error message will contain this parameter's type and label (flag in case of an option).

  list code

    A list of additional elements for the error code to throw. Should detail the internal name of the validation type triggering the error.

  string type

    A string holding a human-readable name for the validation type triggering the error. (Conversely to the code, which is for machine-readability, i.e. trapping)

  string x

    The string value which failed the validation.

  string context

    Additional context to show in the message. Defaults to the empty string.

::cmdr::validate::common fail-unknown-simple p code type x ?context?

  When invoked this command throws an error indicating a validation type failure. The arguments provide the information used to construct both error message and code.

  The generated string has the form:

          $type "$x" does not exist$context.
           Please use a different value.

  cmdr::parameter p

    The cmdr::parameter instance whose validation failed. The error message will contain this parameter's type and label (flag in case of an option).

  list code

    A list of additional elements for the error code to throw. Should detail the internal name of the validation type triggering the error.

  string type

    A string holding a human-readable name for the validation type triggering the error. (Conversely to the code, which is for machine-readability, i.e. trapping)

  string x

    The string value which failed the validation.

  string context

    Additional context to show in the message. Defaults to the empty string.

::cmdr::validate::common fail-unknown-simple-msg msg p code type x ?context?

  A variant of fail-unknown-simple which takes an additional user-specified message text as the first argument.

  When invoked this command throws an error indicating a validation type failure. The arguments provide the information used to construct both error message and code.

  The generated string has the form:

          $type "$x" does not exist$context.
           $msg.

  string msg

    A custom message to put into the generated error message. See the example above.

  cmdr::parameter p

    The cmdr::parameter instance whose validation failed. The error message will contain this parameter's type and label (flag in case of an option).

  list code

    A list of additional elements for the error code to throw. Should detail the internal name of the validation type triggering the error.

  string type

    A string holding a human-readable name for the validation type triggering the error. (Conversely to the code, which is for machine-readability, i.e. trapping)

  string x

    The string value which failed the validation.

  string context

    Additional context to show in the message. Defaults to the empty string.

::cmdr::validate::common fail-known-thing p code type x ?context?

  When invoked this command throws an error indicating a validation type failure. The arguments provide the information used to construct both error message and code.

  The generated string has the form:

          Found a problem with $p.type "$p.the-name":
          A(n) $type named "$x" already exists$context.
           Please use a different name.

  cmdr::parameter p

    The cmdr::parameter instance whose validation failed. The error message will contain this parameter's type and label (flag in case of an option).

  list code

    A list of additional elements for the error code to throw. Should detail the internal name of the validation type triggering the error.

  string type

    A string holding a human-readable name for the validation type triggering the error. (Conversely to the code, which is for machine-readability, i.e. trapping)

  string x

    The string value which failed the validation.

  string context

    Additional context to show in the message. Defaults to the empty string.

::cmdr::validate::common fail-known-thing-msg msg p code type x ?context?

  A variant of fail-known-thing which takes an additional user-specified message text as the first argument.

  When invoked this command throws an error indicating a validation type failure. The arguments provide the information used to construct both error message and code.

  The generated string has the form:

          Found a problem with $p.type "$p.the-name":
          A(n) $type named "$x" already exists$context.
           $msg.

  string msg

    A custom message to put into the generated error message. See the example above.

  cmdr::parameter p

    The cmdr::parameter instance whose validation failed. The error message will contain this parameter's type and label (flag in case of an option).

  list code

    A list of additional elements for the error code to throw. Should detail the internal name of the validation type triggering the error.

  string type

    A string holding a human-readable name for the validation type triggering the error. (Conversely to the code, which is for machine-readability, i.e. trapping)

  string x

    The string value which failed the validation.

  string context

    Additional context to show in the message. Defaults to the empty string.

::cmdr::validate::common fail-known-simple p code type x ?context?

  When invoked this command throws an error indicating a validation type failure. The arguments provide the information used to construct both error message and code.

  The generated string has the form:

          $type named "$x" already exists$context.
           Please use a different name.

  cmdr::parameter p

    The cmdr::parameter instance whose validation failed. The error message will contain this parameter's type and label (flag in case of an option).

  list code

    A list of additional elements for the error code to throw. Should detail the internal name of the validation type triggering the error.

  string type

    A string holding a human-readable name for the validation type triggering the error. (Conversely to the code, which is for machine-readability, i.e. trapping)

  string x

    The string value which failed the validation.

  string context

    Additional context to show in the message. Defaults to the empty string.

::cmdr::validate::common fail-known-simple-msg msg p code type x ?context?

  A variant of fail-known-simple which takes an additional user-specified message text as the first argument.

  When invoked this command throws an error indicating a validation type failure. The arguments provide the information used to construct both error message and code.

  The generated string has the form:

          $type named "$x" already exists$context.
           $msg.

  string msg

    A custom message to put into the generated error message. See the example above.

  cmdr::parameter p

    The cmdr::parameter instance whose validation failed. The error message will contain this parameter's type and label (flag in case of an option).

  list code

    A list of additional elements for the error code to throw. Should detail the internal name of the validation type triggering the error.

  string type

    A string holding a human-readable name for the validation type triggering the error. (Conversely to the code, which is for machine-readability, i.e. trapping)

  string x

    The string value which failed the validation.

  string context

    Additional context to show in the message. Defaults to the empty string.

::cmdr::validate::common complete-enum choices nocase buffer

  When invoked this command returns a list of strings containing just the elements of choices the value of buffer is a prefix of. When nocase is set the command will ignore letter case and treat the string in buffer as all-lowercase.

  list choices

    The list of values which can complete the data in buffer.

  boolean nocase

    A boolean flag specifying if the completion is done ignoring letter-case (true, nocase), or not (false)).

  string buffer

    The string to complete via the list of choices.

::cmdr::validate::common complete-substr choices nocase buffer

  When invoked this command returns a list of strings containing just the elements of choices the value of buffer is a substring of. When nocase is set the command will ignore letter case and treat the string in buffer as all-lowercase.

  list choices

    The list of values which can complete the data in buffer.

  boolean nocase

    A boolean flag specifying if the completion is done ignoring letter-case (true, nocase), or not (false)).

  string buffer

    The string to complete via the list of choices.

::cmdr::validate::common complete-glob filter buffer

  When invoked this command returns a list of strings, the paths in the filesystem the value of buffer is a prefix of, and not rejected by the filter command (prefix).

  Note that when the value of buffer is a relative path the current working directory is used to locate matches.

  cmd-prefix filter

    A command prefix taking a single argument, the candidate path, and returning a boolean value indicating (non-)acceptance of the path. A result of true accepts the candidate, false rejects it.

  string buffer

    The string, a partial path, to complete.

::cmdr::validate::common ok-directory path

  When invoked this command checks if the specified path is suitable as a directory and returns the boolean value true if so, and false else.

  for the path to be suitable the following conditions must hold:

  1. If the path exists:

     1. The path has to refer to a directory.

     2. The referenced directory must be writable.

  2. Else:

     1. The parent path has to pass ok-directory.

     2. The above recursion stops at the root directory, and then fails.

  string path

    The path to check.

::cmdr::validate::common lead-in text

  A utility command supporting the construction of error messages. Given the text the command returns a modified text with a proper prefix of either A or An.

  The basic heuristics is to use An if text begins with a vocal, and A otherwise. This heuristic is bypassed if the the text already has a prefix of An or A separated by a space from the remainder of the string. In that case the text is returned as-is.

  This command is used by fail, fail-known-thing and fail-unknown-thing provided by this package. All apply it to their type argument.

  string text

    The string to prefix with a leading A or An.

## 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

## Copyright

Copyright © 2013-2016 Andreas Kupries
Copyright © 2013-2016 Documentation, Andreas Kupries