Documention for: filtered-import.r
Created by: chrisrg
 on: 30-Apr-2007
Last updated by: chrisrg on: 11-Sep-2008
Format: text/editable
Downloaded on: 19-Apr-2024

Import and Validate User Input

    A Brief Guide

    Christopher Ross-Gill
    30 April, 2007

===Introduction

This script allows you to Import and Validate user input.

===Basic Usage

%filtered-import.r defines two global functions: 'import and 'as.  This documentation focusses on 'import.

---Import

Import takes user input in the form [name value name value ...] where name is of word! type:

    user-data: [name "Chris" age "Not telling" start-date "5 May 2007"]

Import provides rules for which values you want, and how they must conform:

    personal-data-rule: [
        name: string!
    ]

This is a very basic rule that will select the name value and ensure that value is a valid string.

    >> import user-data personal-data-rule
    == [name "Chris"]

===Validation

---Implicit

Import will fail if any value does not meet the specification:

    name: string!
    age: integer!

---Format

You can specify the format of the value, including the use of predifined charsets:

    name: string! [chars-ua some chars la]

---Optional

You can make a value optional:

    name: opt string!

In this case, if the 'name value is empty or not present, 'name in the result block will be set to none!.  Otherwise the 'name value must pass the validation rules.

---Acceptance

    terms-of-service: logic! is accepted

---Comparison

You can provide some parameters that any value must conform to:

    name: string! is not within ["Carl"]
    age: integer! is between [18 65]
    start-date: date! is after 30-April-2007

---Length Comparison

You can also provide parameters to the length of a value:

    name: string!
    length is more-than 3

---Confirmation

You can confirm two values match:

    address: email! is confirmed by :address-confirm

===On Failure

---Why did it fail?

As standard, import will return none! if validation fails.  You can optionally pass a word that will be set with a list of validation failure notices:

    import/else user-data personal-data-rule 'errors

---Custom notices

You can define a notice for each individual validation rule:

    name: string! or "Need a name here!"
    is not within ["Carl"] or "You can't be Carl!"
    length is between [2 50] or "Your name doesn't fit"