doc/html/man/form_field_validation.3x.html

   1 <!--
   2   ****************************************************************************
   3   * Copyright 2018-2019,2020 Thomas E. Dickey                                *
   4   * Copyright 1998-2010,2017 Free Software Foundation, Inc.                  *
   5   *                                                                          *
   6   * Permission is hereby granted, free of charge, to any person obtaining a  *
   7   * copy of this software and associated documentation files (the            *
   8   * "Software"), to deal in the Software without restriction, including      *
   9   * without limitation the rights to use, copy, modify, merge, publish,      *
  10   * distribute, distribute with modifications, sublicense, and/or sell       *
  11   * copies of the Software, and to permit persons to whom the Software is    *
  12   * furnished to do so, subject to the following conditions:                 *
  13   *                                                                          *
  14   * The above copyright notice and this permission notice shall be included  *
  15   * in all copies or substantial portions of the Software.                   *
  16   *                                                                          *
  17   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  18   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  19   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  20   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  21   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  22   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  23   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  24   *                                                                          *
  25   * Except as contained in this notice, the name(s) of the above copyright   *
  26   * holders shall not be used in advertising or otherwise to promote the     *
  27   * sale, use or other dealings in this Software without prior written       *
  28   * authorization.                                                           *
  29   ****************************************************************************
  30   * @Id: form_field_validation.3x,v 1.33 2020/12/12 19:57:55 tom Exp @
  31 -->
  32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  33 <HTML>
  34 <HEAD>
  35 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  36 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
  37 <TITLE>form_field_validation 3x</TITLE>
  38 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  39 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  40 </HEAD>
  41 <BODY>
  42 <H1 class="no-header">form_field_validation 3x</H1>
  43 <PRE>
  44 <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3x)</A></STRONG>                            <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3x)</A></STRONG>
  45
  46
  47
  48
  49 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  50        <STRONG>form_field_validation</STRONG> - data type validation for fields
  51
  52
  53 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  54        <STRONG>#include</STRONG> <STRONG>&lt;form.h&gt;</STRONG>
  55
  56        <STRONG>void</STRONG> <STRONG>*field_arg(const</STRONG> <STRONG>FIELD</STRONG> <STRONG>*</STRONG><EM>field</EM><STRONG>);</STRONG>
  57        <STRONG>FIELDTYPE</STRONG> <STRONG>*field_type(const</STRONG> <STRONG>FIELD</STRONG> <STRONG>*</STRONG><EM>field</EM><STRONG>);</STRONG>
  58        <STRONG>int</STRONG> <STRONG>set_field_type(FIELD</STRONG> <STRONG>*</STRONG><EM>field</EM><STRONG>,</STRONG> <STRONG>FIELDTYPE</STRONG> <STRONG>*</STRONG><EM>type</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
  59
  60        /* predefined field types */
  61        <STRONG>FIELDTYPE</STRONG> <STRONG>*TYPE_ALNUM;</STRONG>
  62        <STRONG>FIELDTYPE</STRONG> <STRONG>*TYPE_ALPHA;</STRONG>
  63        <STRONG>FIELDTYPE</STRONG> <STRONG>*TYPE_ENUM;</STRONG>
  64        <STRONG>FIELDTYPE</STRONG> <STRONG>*TYPE_INTEGER;</STRONG>
  65        <STRONG>FIELDTYPE</STRONG> <STRONG>*TYPE_NUMERIC;</STRONG>
  66        <STRONG>FIELDTYPE</STRONG> <STRONG>*TYPE_REGEXP;</STRONG>
  67        <STRONG>FIELDTYPE</STRONG> <STRONG>*TYPE_IPV4;</STRONG>
  68
  69
  70 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  71        By  default, no validation is done on form fields.  You can associate a
  72        form with with a <EM>field</EM> <EM>type</EM>, making the form library validate input.
  73
  74
  75 </PRE><H3><a name="h3-field_arg">field_arg</a></H3><PRE>
  76        Returns a pointer to the field's argument block.  The <EM>argument</EM> <EM>block</EM> is
  77        an  opaque  structure  containing a copy of the arguments provided in a
  78        <STRONG>set_field_type</STRONG> call.
  79
  80
  81 </PRE><H3><a name="h3-field_type">field_type</a></H3><PRE>
  82        Returns a pointer to the <EM>field</EM> <EM>type</EM> associated  with  the  form  field,
  83        i.e., by calling <STRONG>set_field_type</STRONG>.
  84
  85
  86 </PRE><H3><a name="h3-set_field_type">set_field_type</a></H3><PRE>
  87        The  function  <STRONG>set_field_type</STRONG> associates a field type with a given form
  88        field.  This is the type checked by validation functions.   Most  field
  89        types  are  configurable,  via arguments which the caller provides when
  90        calling <STRONG>set_field_type</STRONG>.
  91
  92        Several field types are predefined by the form library.
  93
  94
  95 </PRE><H3><a name="h3-Predefined-types">Predefined types</a></H3><PRE>
  96        It is possible to set up new  programmer-defined  field  types.   Field
  97        types  are implemented via the <STRONG>FIELDTYPE</STRONG> data structure, which contains
  98        several pointers to functions.
  99
 100        See the <STRONG><A HREF="form_fieldtype.3x.html">form_fieldtype(3x)</A></STRONG> manual page, which describes functions which
 101        can be used to construct a field-type dynamically.
 102
 103        The predefined types are as follows:
 104
 105        TYPE_ALNUM
 106             Alphanumeric data.  Required parameter:
 107
 108             <STRONG>o</STRONG>   a third <STRONG>int</STRONG> argument, a minimum field width.
 109
 110        TYPE_ALPHA
 111             Character data.  Required parameter:
 112
 113             <STRONG>o</STRONG>   a third <STRONG>int</STRONG> argument, a minimum field width.
 114
 115        TYPE_ENUM
 116             Accept one of a specified set of strings.  Required parameters:
 117
 118             <STRONG>o</STRONG>   a third <STRONG>(char</STRONG> <STRONG>**)</STRONG> argument pointing to a string list;
 119
 120             <STRONG>o</STRONG>   a fourth <STRONG>int</STRONG> flag argument to enable case-sensitivity;
 121
 122             <STRONG>o</STRONG>   a  fifth  <STRONG>int</STRONG> flag argument specifying whether a partial match
 123                 must be a unique one.  If this flag is off, a  prefix  matches
 124                 the  first of any set of more than one list elements with that
 125                 prefix.
 126
 127             The library copies the string list, so you may  use  a  list  that
 128             lives in automatic variables on the stack.
 129
 130        TYPE_INTEGER
 131             Integer data, parsable to an integer by <STRONG>atoi(3)</STRONG>.  Required parame-
 132             ters:
 133
 134             <STRONG>o</STRONG>   a third <STRONG>int</STRONG> argument controlling the precision,
 135
 136             <STRONG>o</STRONG>   a fourth <STRONG>long</STRONG> argument constraining minimum value,
 137
 138             <STRONG>o</STRONG>   a fifth <STRONG>long</STRONG> constraining maximum value.  If the maximum value
 139                 is  less than or equal to the minimum value, the range is sim-
 140                 ply ignored.
 141
 142             On return, the field buffer is formatted according to  the  <STRONG>printf</STRONG>
 143             format specification ".*ld", where the "*" is replaced by the pre-
 144             cision argument.
 145
 146             For details of the precision handling see <STRONG>printf(3)</STRONG>.
 147
 148        TYPE_NUMERIC
 149             Numeric data (may have a decimal-point  part).   Required  parame-
 150             ters:
 151
 152             <STRONG>o</STRONG>   a third <STRONG>int</STRONG> argument controlling the precision,
 153
 154             <STRONG>o</STRONG>   a fourth <STRONG>double</STRONG> argument constraining minimum value,
 155
 156             <STRONG>o</STRONG>   and a fifth <STRONG>double</STRONG> constraining maximum value.  If your system
 157                 supports locales, the decimal point character must be the  one
 158                 specified  by  your locale.  If the maximum value is less than
 159                 or equal to the minimum value, the range is simply ignored.
 160
 161             On return, the field buffer is formatted according to  the  <STRONG>printf</STRONG>
 162             format  specification ".*f", where the "*" is replaced by the pre-
 163             cision argument.
 164
 165             For details of the precision handling see <STRONG>printf(3)</STRONG>.
 166
 167        TYPE_REGEXP
 168             Regular expression data.  Required parameter:
 169
 170             <STRONG>o</STRONG>   a third argument, a regular expression <STRONG>(char</STRONG> <STRONG>*)</STRONG>  string.   The
 171                 data is valid if the regular expression matches it.
 172
 173             Regular expressions are in the format of <STRONG>regcomp</STRONG> and <STRONG>regexec</STRONG>.
 174
 175             The  regular  expression  must match the whole field.  If you have
 176             for example, an eight character wide field, a  regular  expression
 177             "^[0-9]*$"  always means that you have to fill all eight positions
 178             with digits.  If you want to allow fewer digits, you may  use  for
 179             example  "^[0-9]*  *$" which is good for trailing spaces (up to an
 180             empty field), or "^ *[0-9]* *$" which  is  good  for  leading  and
 181             trailing spaces around the digits.
 182
 183        TYPE_IPV4
 184             An Internet Protocol Version 4 address.  Required parameter:
 185
 186             <STRONG>o</STRONG>   none
 187
 188             The  form  library  checks  whether or not the buffer has the form
 189             <EM>a.b.c.d</EM>, where <EM>a</EM>, <EM>b</EM>, <EM>c</EM>, and <EM>d</EM> are numbers in the range 0  to  255.
 190             Trailing  blanks in the buffer are ignored.  The address itself is
 191             not validated.
 192
 193             This is an ncurses extension; this field type may not be available
 194             in other curses implementations.
 195
 196
 197 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 198        The functions <STRONG>field_type</STRONG> and <STRONG>field_arg</STRONG> return <STRONG>NULL</STRONG> on error.  The func-
 199        tion <STRONG>set_field_type</STRONG> returns one of the following:
 200
 201        <STRONG>E_OK</STRONG> The routine succeeded.
 202
 203        <STRONG>E_SYSTEM_ERROR</STRONG>
 204             System error occurred (see <STRONG>errno(3)</STRONG>).
 205
 206
 207 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 208        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG>, <STRONG><A HREF="form_fieldtype.3x.html">form_fieldtype(3x)</A></STRONG>, <STRONG><A HREF="form_variables.3x.html">form_variables(3x)</A></STRONG>.
 209
 210
 211 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 212        The  header  file  <STRONG>&lt;form.h&gt;</STRONG>  automatically  includes  the  header  file
 213        <STRONG>&lt;curses.h&gt;</STRONG>.
 214
 215
 216 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 217        These  routines emulate the System V forms library.  They were not sup-
 218        ported on Version 7 or BSD versions.
 219
 220
 221 </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
 222        Juergen Pfeifer.  Manual pages and adaptation for new curses by Eric S.
 223        Raymond.
 224
 225
 226
 227                                                      <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3x)</A></STRONG>
 228 </PRE>
 229 <div class="nav">
 230 <ul>
 231 <li><a href="#h2-NAME">NAME</a></li>
 232 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 233 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 234 <ul>
 235 <li><a href="#h3-field_arg">field_arg</a></li>
 236 <li><a href="#h3-field_type">field_type</a></li>
 237 <li><a href="#h3-set_field_type">set_field_type</a></li>
 238 <li><a href="#h3-Predefined-types">Predefined types</a></li>
 239 </ul>
 240 </li>
 241 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 242 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 243 <li><a href="#h2-NOTES">NOTES</a></li>
 244 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 245 <li><a href="#h2-AUTHORS">AUTHORS</a></li>
 246 </ul>
 247 </div>
 248 </BODY>
 249 </HTML>