|Author||Dr John A.R. Williams|
|Status||Initial Public Release|
|Copyright||© 2010 J.A.R. Williams|
DATA-FORMAT-VALIDATION is a library for Common Lisp providing a consistent regular interface for converting (and validating) external data (in the form of strings usually) into internal data types and for formatting internal data back into external presentable strings, all according to a conversion or type specification.
DATA-FORMAT-VALIDATION together with this documentation can be downloaded from the git repository at <git://github.com/willijar/cl-data-format-validation.git> or from <http://www.jarw.org.uk/lisp/cl-data-format-validation.tar.gz>. The current release version is 0.1.6.
DATA-FORMAT-VALIDATION is made available under the terms of the GPL v3 license - see the file LICENSE.txt for details.
For questions, bug reports, feature requests, improvements, or patches please email <J.A.R.Williams@jarw.org.uk>.
Validate and parse user input according to specification, returning the validated object. Throws an invalid-input condition if input is invalid. If specification is a list the first element specifies the actual validation method and the rest of the list are passed as keyword arguments to the specific method:
(parse-input '(integer :min 0) input)
will return the integer value from strin if it is >0, or signal and invalid-input error if not and:
(parse-input '(member :type integer :set (1 5 7)) input)
will return it only if it has a value in the set.
The use-value restart may be used to provide substitute value if the input is invalid.
Return a string representation of value formatted according to a specification. If specification is a list the first element specifies the actual validation method and the rest of the list are passed as keyword arguments to the specific method e.g.:
(format-output '(date :fmt :rfc2822) (get-universal-time)) >"Mon, 10 Jul 2006 15:43:45 +00"
Formatter which outputs its numerical argument arg in engineering format to stream os. It takes arguments d,padchar,exponentchar where d is the number of decimal places to display after the decimal point padchar is the character to pad the start of the number exponentchar is the character to use to display between radix and exponent It also takes the : modifier which will cause it to output the exponent as an SI units prefix rather than a number.
e.g. (format nil \" /eng/\" 35000) => \"35.00e+3\"
Formatter which formats a universal time for output as a date and time
os: an output stream designator
arg: a universal time
If true use month and day names in date
(sortable) format rather than dd-mm-yyy
7 includes timezone, a negative number counts backward.
If nil no timezone used and time is in current timezone adjusted for daylight saving time.
e.g. (format nil \" /date/\" (get-universal-time)) => \"19-03-2009 08:30\""
A type specification is an S-expression composed of a symbol specifying the particular conversion and a keyword argument list of qualifiers. Specific methods of parse-input and format-output are specialised on the conversion type symbol and take the remainder of the S-expression as an argument list. Adding your own conversions is simply a matter of providing appropriately specialised methods. The intended semantics are that the if the output from format-output is read back in using parse-input with thye same type specifications then an equivalent object should result.
Many conversions take the nil-allowed argument which convert an empty or all whitespace string to nil corresponding to a null input, otherwise an empty string is considered invalid input. Methods specialisations are provided for the following types:
Jim Healy and Daniel Barlow to convert to internal universal time in specified timezone zone which to defaults to special variable *timezone* for output but to nil for parsing input. If zone is nil the time will be in the current timezone allowing for local daylight savings time - otherwise it is in the specified timezone, which will be written out.
fmt is a keyword specifying the output format to be used as follows.
A stand alone formatter of the same name is also provided.
:RFC2822 - output as per RFC2822 for internet messages :SHORT - output in a shorter format (same as :ISO) :TIME-ONLY - outputs time as hh:mm:ss :DATE-ONLY - outputs date as dd-mm-yyyy :ISO - output as per ISO 8602 (default)
Converts between a string which includes units and normal scaling suffixes and a cons of the numerical value and the base units string. padchar and decimal-places are as per eng.
A dimensional comparator is equivalent if the numerical values and the units are equivalent.
preserve-newlines-p termination-test if-no-specification` Parse or format internet message style headers. parse-input takes either a string or stream as the input value.
field-specifications is either an a-list by field name of giving the parse type specification to be applied recursively for that field or a function which returns the parse type specification and a present-p values in the usual way. if-no-specification specifies either a type specification to be used if the field is not found in field-specifications, :error for this case to be flagged as an error or :ignore to ignore fields without specifications. If defaults to nil i.e. value is passed through as a string without parsing.
skip-blanks-p will allow the parser to skip leading blank lines on the input. termination-test is a test function which of one argument (a string - a line) which should return true if the argument terminates the headers - default tests for a zero length line. If preserve-newlines-p is true then continuation lines will keep their newline characters, otherwise the newlines and first continuation character are removed.
format-output will write its output to stream if it is given, otherwise it will return a string containing the output headers.
Converts to a general number between min and max (inclusive, and if specified). radix specified the base (in the usual way). format specifies the format control string to be used for output. The parse-number library of Matthew Danish is used to do the conversion.
tol is the tolerance to be used for equivalence testing - it can either be a multiplier applied to the reference value or a function of two arguments - the input and the reference value.
Matthew Danish for the parse-number library used and enclosed with this.
Daniel Barlow and Jim Healey for the parse-time library.