[ Impressum ]

LiveCode ValidatorLib

www.Rozek.de > LiveCode > ValidatorLib
The "ValidatorLib" is a small LiveCode [1] "Library Stack" with a number of commands for the validation of required or optional arguments.

Download and Installation

The "ValidatorLib" is available as an unencrypted LiveCode stack and can be downloaded from here:
After downloading, just place the "ValidatorLib" in a directory of your choice - an explicit installation is not required.

Usage Instructions

The "ValidatorLib" has been implemented as a LiveCode "library stack" and must therefore be attached to a "MainStack" prior to its use using

start using stack "ValidatorLib"

Appropriately, this statement is executed in the context of a preOpenStack procedure of a MainStack.

Should the MainStack later be converted into a standalone application, the "ValidatorLib" must also become part of the list of "Stack Files" in this MainStack (this is easiest done by using the "Standalone Application Settings" from the LiveCode development environment).

Usage Instructions for mobile Applications

The "ValidatorLib" can also be used in mobile applications. However - and unlike for standalone desktop applications - it must then be included in the list of "non-stack files" and attached to the MainStack using

start using stack (specialFolderPath("engine") & "/ValidatorLib.livecode")

The list of "non-stack files" can likewise be found on the "Copy Files" page in the "Standalone Application Settings" of the LiveCode development environment.

Command Overview

The "ValidatorLib" mainly contains commands to validate given arguments. If validation is successful, the commands complete without further incident and the calling script may continue. But if it fails, an appropriate exception is thrown the calling script can handle.

Validation of optional Arguments

The first half of commands (those whose name begins with "allow") validates optional arguments - these procedures differ from the second half insofar as the given argument may also be empty. The commands are (in alphabetic order):

allowArray <ArgName>, <ArgValue>


allowArray ensures that the passed ArgValue is either absent (i.e. empty) or represents a numerically indexed LiveCode array.

The indexes have to start at 0 and end at n-1, where n is the number of keys in ArgValue. This convention has been introduced to ensure a certain degree of compatibility with JSON arrays - should your LiveCode array not fulfill this requirement, it would be better to use allowObject instead.

ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

allowBoolean <ArgName>, <ArgValue>


allowBoolean ensures that the passed ArgValue is either absent (i.e. empty) or can be recognized by LiveCode as a valid boolean value. ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

allowColor <ArgName>, <ArgValue>


allowColor ensures that the passed ArgValue is either absent (i.e. empty) or can be recognized by LiveCode as a valid (numeric or symbolic) color specification. ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

allowDate <ArgName>, <ArgValue>


allowDate ensures that the passed ArgValue is either absent (i.e. empty) or can be recognized by LiveCode as a valid date specification. ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

allowIdentifier <ArgName>, <ArgValue>


allowIdentifier ensures that the passed ArgValue is either absent (i.e. empty) or can be recognized as an identifier (consisting of letters, digits and underlines - but not beginning with a digit) which is valid in many programming languages. ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

allowInteger <ArgName>, <ArgValue> [, minValue [, maxValue]]


allowInteger ensures that the passed ArgValue is either absent (i.e. empty) or can be recognized by LiveCode as a valid integral number.

If given (and non-empty), minValue specifies the lowest acceptable and maxValue the largest acceptable value for ArgValue.

ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

allowNumber <ArgName>, <ArgValue> [, minValue [, maxValue [, withoutMin [, withoutMax]]]]


allowNumber ensures that the passed ArgValue is either absent (i.e. empty) or can be recognized by LiveCode as a valid number.

If given (and non-empty), minValue specifies the lowest acceptable and maxValue the largest acceptable value for ArgValue. If set to true, withoutMin specifies that minValue itself is not part of the allowed range, and withoutMax that maxValue is excluded, resp.

ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

allowObject <ArgName>, <ArgValue> [, requiredKey [, ...]]


allowObject ensures that the passed ArgValue is either absent (i.e. empty) or represents a valid LiveCode array.

Any further arguments (requiredKey et al.) specify keys which must exist in the given array for allowObject to succeed (regardless of the values of the respective array elements).

ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

allowOneOf <ArgName>, <ArgValue>, foreseenValue [, ...]


allowOneOf ensures that the passed ArgValue is either absent (i.e. empty) or among the list of allowed values (foreseenValue et al). ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

allowPoint <ArgName>, <ArgValue>


allowPoint ensures that the passed ArgValue is either absent (i.e. empty) or can be recognized by LiveCode as a valid coordinate pair for a point. ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

allowRectangle <ArgName>, <ArgValue>


allowRectangle ensures that the passed ArgValue is either absent (i.e. empty) or can be recognized by LiveCode as a valid coordinate quadruple for a rectangle. ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

allowString <ArgName>, <ArgValue>


allowString ensures that the passed ArgValue is either absent (i.e. empty) or can be recognized by LiveCode as a valid string - which actually means that ArgValue is not a LiveCode array. ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

Validation of mandatory Arguments

The second half of commands (those whose name begins with "expect") validates mandatory arguments - these procedures differ from the second half insofar as the given argument must usually not be empty. The commands are (in alphabetic order):

expectArray <ArgName>, <ArgValue>


expectArray ensures that the passed ArgValue exists (i.e., is not empty) and represents a numerically indexed LiveCode array.

The indexes have to start at 0 and end at n-1, where n is the number of keys in ArgValue. This convention has been introduced to ensure a certain degree of compatibility with JSON arrays - should your LiveCode array not fulfill this requirement, it would be better to use expectObject instead.

ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

expectBoolean <ArgName>, <ArgValue>


expectBoolean ensures that the passed ArgValue exists (i.e., is not empty) and can be recognized by LiveCode as a valid boolean value. ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

expectColor <ArgName>, <ArgValue>


expectColor ensures that the passed ArgValue exists (i.e., is not empty) and can be recognized by LiveCode as a valid (numeric or symbolic) color specification. ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

expectDate <ArgName>, <ArgValue>


expectDate ensures that the passed ArgValue exists (i.e., is not empty) and can be recognized by LiveCode as a valid date specification. ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

expectIdentifier <ArgName>, <ArgValue>


expectIdentifier ensures that the passed ArgValue exists (i.e., is not empty) and can be recognized as an identifier (consisting of letters, digits and underlines - but not beginning with a digit) which is valid in many programming languages. ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

expectInteger <ArgName>, <ArgValue> [, minValue [, maxValue]]


expectInteger ensures that the passed ArgValue exists (i.e., is not empty) and can be recognized by LiveCode as a valid integral number.

If given (and non-empty), minValue specifies the lowest acceptable and maxValue the largest acceptable value for ArgValue.

ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

expectNumber <ArgName>, <ArgValue> [, minValue [, maxValue [, withoutMin [, withoutMax]]]]


expectNumber ensures that the passed ArgValue exists (i.e., is not empty) and can be recognized by LiveCode as a valid number.

If given (and non-empty), minValue specifies the lowest acceptable and maxValue the largest acceptable value for ArgValue. If set to true, withoutMin specifies that minValue itself is not part of the allowed range, and withoutMax that maxValue is excluded, resp.

ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

expectObject <ArgName>, <ArgValue> [, requiredKey [, ...]]


expectObject ensures that the passed ArgValue exists (i.e., is not empty) and represents a valid LiveCode array.

Any further arguments (requiredKey et al.) specify keys which must exist in the given array for allowObject to succeed (regardless of the values of the respective array elements).

ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

expectOneOf <ArgName>, <ArgValue>, foreseenValue [, ...]


expectOneOf ensures that the passed ArgValue exists (i.e., is not empty) and among the list of allowed values (foreseenValue et al). ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

expectPoint <ArgName>, <ArgValue>


expectPoint ensures that the passed ArgValue exists (i.e., is not empty) and can be recognized by LiveCode as a valid coordinate pair for a point. ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

expectRectangle <ArgName>, <ArgValue>


expectRectangle ensures that the passed ArgValue exists (i.e., is not empty) and can be recognized by LiveCode as a valid coordinate quadruple for a rectangle. ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

expectString <ArgName>, <ArgValue> [, nonEmpty]


expectString ensures that the passed ArgValue can be recognized by LiveCode as a valid string - which actually means that ArgValue is not a LiveCode array. ArgValue may exceptionally be empty here - unless nonEmpty is set to true. ArgName must be a syntactically correct, non-empty LiveCode identifier and is used to form a meaningful error message should an exception be thrown.

System Requirements

The "ValidatorLib" requires LiveCode 6.x or later, and works regardless of the operating system on both stationary and mobile platforms.

Dependencies

Internally, the "ValidatorLib" uses my "BasicLib" - when using the "ValidatorLib" it must therefore also be present.

Automated Tests

There is also a separate stack with automated tests of the "ValidatorLib":
When this stack is opened, the command performTests is executed, which is responsible for running the actual tests. In the end, the "Message Box" of the LiveCode development environment should appear and display the message

all tests passed

Otherwise, an error message with information about the failed test should be shown instead.

Known Bugs

There are currently no known bugs in the "ValidatorLib".

License Information

The "ValidatorLib" and its tests are licensed under a "Creative Commons Attribution 4.0 Unported license", which essentially means that you may both use and modify them (even in a commercial context) - provided that your changes have been marked as such and there is a reference to me as the original author at an appropriate place.

                       
Have fun with LiveCode and my libraries! Creative Commons License

Bibliography

[1]
(RunRev Ltd.)
LiveCode | Create apps for multiple platforms. Quickly. Easily. Free
LiveCode is a development environment for both stationary (Windows, Linux, MacOS X) and mobile (iOS, Android) applications modeled after the legendary Apple HyperCard. A visual editor allows fast design of user interfaces, a programming language inspired by the english language allows even non-professional programmers to develop professional applications and the concept of "modifying a running program" simplifies testing and troubleshooting.