man/form_field_validation.3x

   1 .\"***************************************************************************
   2 .\" Copyright 2018-2022,2023 Thomas E. Dickey                                *
   3 .\" Copyright 1998-2010,2017 Free Software Foundation, Inc.                  *
   4 .\"                                                                          *
   5 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
   6 .\" copy of this software and associated documentation files (the            *
   7 .\" "Software"), to deal in the Software without restriction, including      *
   8 .\" without limitation the rights to use, copy, modify, merge, publish,      *
   9 .\" distribute, distribute with modifications, sublicense, and/or sell       *
  10 .\" copies of the Software, and to permit persons to whom the Software is    *
  11 .\" furnished to do so, subject to the following conditions:                 *
  12 .\"                                                                          *
  13 .\" The above copyright notice and this permission notice shall be included  *
  14 .\" in all copies or substantial portions of the Software.                   *
  15 .\"                                                                          *
  16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  23 .\"                                                                          *
  24 .\" Except as contained in this notice, the name(s) of the above copyright   *
  25 .\" holders shall not be used in advertising or otherwise to promote the     *
  26 .\" sale, use or other dealings in this Software without prior written       *
  27 .\" authorization.                                                           *
  28 .\"***************************************************************************
  29 .\"
  30 .\" $Id: form_field_validation.3x,v 1.40 2023/07/01 15:46:10 tom Exp $
  31 .TH form_field_validation 3X 2023-07-01 "ncurses 6.4" "Library calls"
  32 .ie \n(.g .ds `` \(lq
  33 .el       .ds `` ``
  34 .ie \n(.g .ds '' \(rq
  35 .el       .ds '' ''
  36 .de bP
  37 .ie n  .IP \(bu 4
  38 .el    .IP \(bu 2
  39 ..
  40 .SH NAME
  41 \fBform_field_validation\fP \- data type validation for fields
  42 .SH SYNOPSIS
  43 \fB#include <form.h>\fP
  44 .sp
  45 \fBvoid *field_arg(const FIELD *\fIfield\fB);\fR
  46 .br
  47 \fBFIELDTYPE *field_type(const FIELD *\fIfield\fB);\fR
  48 .br
  49 \fBint set_field_type(FIELD *\fIfield\fB, FIELDTYPE *\fItype\fB, ...);\fR
  50 .sp
  51 /* predefined field types */
  52 .br
  53 \fBFIELDTYPE *TYPE_ALNUM;\fP
  54 .br
  55 \fBFIELDTYPE *TYPE_ALPHA;\fP
  56 .br
  57 \fBFIELDTYPE *TYPE_ENUM;\fP
  58 .br
  59 \fBFIELDTYPE *TYPE_INTEGER;\fP
  60 .br
  61 \fBFIELDTYPE *TYPE_NUMERIC;\fP
  62 .br
  63 \fBFIELDTYPE *TYPE_REGEXP;\fP
  64 .br
  65 \fBFIELDTYPE *TYPE_IPV4;\fP
  66 .SH DESCRIPTION
  67 By default, no validation is done on form fields.
  68 You can associate a form with with a \fIfield type\fP,
  69 making the form library validate input.
  70 .SS field_arg
  71 Returns a pointer to the field's argument block.
  72 The \fIargument block\fP is an opaque structure containing
  73 a copy of the arguments provided in a \fBset_field_type\fP call.
  74 .SS field_type
  75 Returns a pointer to the \fIfield type\fP associated with the form field,
  76 i.e., by calling \fBset_field_type\fP.
  77 .SS set_field_type
  78 The function \fBset_field_type\fP associates
  79 a field type with a given form field.
  80 This is the type checked by validation functions.
  81 Most field types are configurable,
  82 via arguments which the caller provides when calling \fBset_field_type\fP.
  83 .PP
  84 Several field types are predefined by the form library.
  85 .SS Predefined types
  86 It is possible to set up new programmer-defined field types.
  87 Field types are implemented via the \fBFIELDTYPE\fP data
  88 structure, which contains several pointers to functions.
  89 .PP
  90 See the \fBform_fieldtype\fP(3X) manual page,
  91 which describes functions which can be used to construct
  92 a field-type dynamically.
  93 .PP
  94 The predefined types are as follows:
  95 .TP 5
  96 TYPE_ALNUM
  97 Alphanumeric data.
  98 Required parameter:
  99 .RS
 100 .bP
 101 a third \fBint\fP argument, a minimum field width.
 102 .RE
 103 .TP 5
 104 TYPE_ALPHA
 105 Character data.
 106 Required parameter:
 107 .RS
 108 .bP
 109 a third \fBint\fP argument, a minimum field width.
 110 .RE
 111 .TP 5
 112 TYPE_ENUM
 113 Accept one of a specified set of strings.
 114 Required parameters:
 115 .RS
 116 .bP
 117 a third \fB(char **)\fP argument pointing to a string list;
 118 .bP
 119 a fourth \fBint\fP flag argument to enable case-sensitivity;
 120 .bP
 121 a fifth \fBint\fP flag argument specifying whether a partial
 122 match must be a unique one.
 123 If this flag is off, a prefix matches the first
 124 of any set of more than one list elements with that prefix.
 125 .RE
 126 .IP
 127 The library copies the string list,
 128 so you may use a list that lives in automatic variables on the stack.
 129 .TP 5
 130 TYPE_INTEGER
 131 Integer data, parsable to an integer by \fBatoi\fP(3).
 132 Required parameters:
 133 .RS
 134 .bP
 135 a third \fBint\fP argument controlling the precision,
 136 .bP
 137 a fourth \fBlong\fP argument constraining minimum value,
 138 .bP
 139 a fifth \fBlong\fP constraining maximum value.
 140 If the maximum value is less than or equal to the minimum value, the range is
 141 simply ignored.
 142 .RE
 143 .IP
 144 On return, the field buffer is formatted according to the
 145 \fBprintf\fP format specification \*(``.*ld\*('',
 146 where the \*(``*\*('' is replaced by the precision argument.
 147 .IP
 148 For details of the precision handling see \fBprintf\fP(3).
 149 .TP 5
 150 TYPE_NUMERIC
 151 Numeric data (may have a decimal-point part).
 152 Required parameters:
 153 .RS
 154 .bP
 155 a third \fBint\fP argument controlling the precision,
 156 .bP
 157 a fourth \fBdouble\fP argument constraining minimum value,
 158 .bP
 159 and a fifth \fBdouble\fP constraining maximum value.
 160 If your system supports locales,
 161 the decimal point character must be the one specified by your locale.
 162 If the maximum value is less than or equal to the minimum value,
 163 the range is simply ignored.
 164 .RE
 165 .IP
 166 On return, the field buffer is formatted according to the
 167 \fBprintf\fP format specification \*(``.*f\*('',
 168 where the \*(``*\*('' is replaced by the precision argument.
 169 .IP
 170 For details of the precision handling see \fBprintf\fP(3).
 171 .TP 5
 172 TYPE_REGEXP
 173 Regular expression data.
 174 Required parameter:
 175 .RS
 176 .bP
 177 a third argument, a regular expression \fB(char *)\fP string.
 178 The data is valid if the regular expression matches it.
 179 .RE
 180 .IP
 181 Regular expressions
 182 are in the format of \fBregcomp\fP and \fBregexec\fP.
 183 .IP
 184 The regular expression must match the whole field.
 185 If you have for example, an eight character wide field,
 186 a regular expression "^[0\-9]*$" always
 187 means that you have to fill all eight positions with digits.
 188 If you want to allow fewer digits,
 189 you may use for example "^[0\-9]* *$" which is good for
 190 trailing spaces (up to an empty field),
 191 or "^ *[0\-9]* *$" which is good for
 192 leading and trailing spaces around the digits.
 193 .TP 5
 194 TYPE_IPV4
 195 An Internet Protocol Version 4 address.
 196 Required parameter:
 197 .RS
 198 .bP
 199 none
 200 .RE
 201 .IP
 202 The form library checks whether or not the buffer has the form \fIa.b.c.d\fP,
 203 where \fIa\fP, \fIb\fP, \fIc\fP, and \fId\fP are numbers in the range 0 to 255.
 204 Trailing blanks in the buffer are ignored.
 205 The address itself is not validated.
 206 .IP
 207 This is an ncurses extension;
 208 this field type may not be available in other curses implementations.
 209 .SH RETURN VALUE
 210 The functions \fBfield_type\fP and \fBfield_arg\fP return \fBNULL\fP on error.
 211 The function \fBset_field_type\fP returns one of the following:
 212 .TP 5
 213 .B E_OK
 214 The routine succeeded.
 215 .TP 5
 216 .B E_SYSTEM_ERROR
 217 System error occurred (see \fBerrno\fP(3)).
 218 .SH SEE ALSO
 219 \fBcurses\fP(3X),
 220 \fBform\fP(3X),
 221 \fBform_fieldtype\fP(3X),
 222 \fBform_variables\fP(3X).
 223 .SH NOTES
 224 The header file \fB<form.h>\fP automatically includes the header file
 225 \fB<curses.h>\fP.
 226 .SH PORTABILITY
 227 These routines emulate the System V forms library.
 228 They were not supported on
 229 Version 7 or BSD versions.
 230 .SH AUTHORS
 231 Juergen Pfeifer.
 232 Manual pages and adaptation for new curses by Eric S. Raymond.