basis/validators/validators-docs.factor

   1 USING: help.markup help.syntax kernel math quotations regexp
   2 strings ;
   3 IN: validators
   4
   5 HELP: v-checkbox
   6 { $values { "str" string } { "?" boolean } }
   7 { $description "Converts the string value of a checkbox component (either \"on\" or \"off\") to a boolean value." } ;
   8
   9 HELP: v-captcha
  10 { $values { "str" string } }
  11 { $description "Throws a validation error if the string is non-empty. This is used to create bait fields for spam-bots to fill in." } ;
  12
  13 HELP: v-credit-card
  14 { $values { "str" string } { "n" integer } }
  15 { $description "If the credit card number passes the Luhn algorithm, converts it to an integer, otherwise throws an error." }
  16 { $notes "See " { $url "http://en.wikipedia.org/wiki/Luhn_algorithm" } " for a description of this algorithm." } ;
  17
  18 HELP: v-default
  19 { $values { "str" string } { "def" string } { "str/def" string } }
  20 { $description "If the input string is not specified, replaces it with the default value." } ;
  21
  22 HELP: v-email
  23 { $values { "str" string } }
  24 { $description "Throws a validation error if the string is not a valid e-mail address, as determined by a regular expression." } ;
  25
  26 HELP: v-integer
  27 { $values { "str" string } { "n" integer } }
  28 { $description "Converts the string into an integer, throwing a validation error if the string is not a valid integer." } ;
  29
  30 HELP: v-min-length
  31 { $values { "str" string } { "n" integer } }
  32 { $description "Throws a validation error if the string is shorter than " { $snippet "n" } " characters." } ;
  33
  34 HELP: v-max-length
  35 { $values { "str" string } { "n" integer } }
  36 { $description "Throws a validation error if the string is longer than " { $snippet "n" } " characters." } ;
  37
  38 HELP: v-max-value
  39 { $values { "x" integer } { "n" integer } }
  40 { $description "Throws an error if " { $snippet "x" } " is larger than " { $snippet "n" } "." } ;
  41
  42 HELP: v-min-value
  43 { $values { "x" integer } { "n" integer } }
  44 { $description "Throws an error if " { $snippet "x" } " is smaller than " { $snippet "n" } "." } ;
  45
  46 HELP: v-mode
  47 { $values { "str" string } }
  48 { $description "Throws an error if " { $snippet "str" } " is not a valid XMode mode name." } ;
  49
  50 HELP: v-number
  51 { $values { "str" string } { "n" real } }
  52 { $description "Converts the string into a real number, throwing a validation error if the string is not a valid real number." } ;
  53
  54 HELP: v-one-line
  55 { $values { "str" string } }
  56 { $description "Throws a validation error if the string contains line breaks." } ;
  57
  58 HELP: v-one-word
  59 { $values { "str" string } }
  60 { $description "Throws a validation error if the string contains word breaks." } ;
  61
  62 HELP: v-optional
  63 { $values { "str" string } { "quot" quotation } { "result" string } }
  64 { $description "If the string is non-empty, applies the quotation to the string, otherwise outputs the empty string." } ;
  65
  66 HELP: v-password
  67 { $values { "str" string } }
  68 { $description "A reasonable default validator for passwords." } ;
  69
  70 HELP: v-regexp
  71 { $values { "str" string } { "what" string } { "regexp" regexp } }
  72 { $description "Throws a validation error that " { $snippet "what" } " failed if the string does not match the regular expression." } ;
  73
  74 HELP: v-required
  75 { $values { "str" string } }
  76 { $description "Throws a validation error if the string is empty." } ;
  77
  78 HELP: v-url
  79 { $values { "str" string } }
  80 { $description "Throws an error if the string is not a valid URL, as determined by a regular expression." } ;
  81
  82 HELP: v-username
  83 { $values { "str" string } }
  84 { $description "A reasonable default validator for usernames." } ;
  85
  86 ARTICLE: "validators" "Form validators"
  87 "The " { $vocab-link "validators" } " vocabulary provides a set of words which are intended to be used with the form validation functionality offered by " { $vocab-link "furnace.actions" } ". They can also be used independently of the web framework."
  88 $nl
  89 "Note that validators which take numbers must be preceded by " { $link v-integer } " or " { $link v-number } " if the original input is a string."
  90 $nl
  91 "Higher-order validators which require additional parameters:"
  92 { $subsections
  93     v-default
  94     v-optional
  95     v-min-length
  96     v-max-length
  97     v-min-value
  98     v-max-value
  99     v-regexp
 100 }
 101 "Simple validators:"
 102 { $subsections
 103     v-required
 104     v-number
 105     v-integer
 106     v-one-line
 107     v-one-word
 108     v-captcha
 109     v-checkbox
 110 }
 111 "More complex validators:"
 112 { $subsections
 113     v-email
 114     v-url
 115     v-username
 116     v-password
 117     v-credit-card
 118     v-mode
 119 } ;
 120
 121 ABOUT: "validators"