/ 
TUI-Vision-2.000_004
/ TPXPictureValidator

NAME

TPXPictureValidator - Picture-based validator for structured input

HIERARCHY

TObject
  TValidator
    TPXPictureValidator

SYNOPSIS

use TUI::Validate::PXPictureValidator;

my $validator = new_TPXPictureValidator( '##-??', true );

my $value = '12ab';
my $ok_partial = $validator->isValidInput( $value, false );
my $ok_final   = $validator->isValid($value);

$validator->error() if !$ok_final;

DESCRIPTION

TPXPictureValidator checks text against a picture pattern.

The picture string defines allowed character classes and grouping rules. During validation, the parser returns status codes from TPicResult to describe whether the current input is complete, incomplete, syntactically invalid, or incompatible with the pattern.

If auto-fill is enabled, literal characters from the picture can be inserted while parsing incremental input.

Commonly Used Features

Typical usage combines isValidInput for live, per-keystroke checks and isValid for final acceptance checks.

When autoFill is enabled, picture literals are inserted during parsing so input can be normalized to the target format while the user types.

For integration points that need direct parser state, picture returns the underlying TPicResult status codes.

VARIABLES

$errorMsg

Message template used by error.

ATTRIBUTES

pic

Read-only picture string used as the validation mask.

CONSTRUCTOR

new

my $obj = TPXPictureValidator->new(
  pic      => $picture,
  autoFill => $bool,
);

Creates a validator instance.

  • pic (required): picture mask (Str).

  • autoFill (required): enables fill behavior via voFill.

new_TPXPictureValidator

my $obj = new_TPXPictureValidator( $picture, $autoFill );

Positional factory equivalent to ->new(pic => ..., autoFill => ...).

METHODS

error

Displays an error message box for invalid picture definitions.

isValid

my $ok = $obj->isValid($s);

Returns true only if $s is a complete match for the picture.

isValidInput

my $ok = $obj->isValidInput( $s, $suppressFill );

Checks whether $s is acceptable as in-progress input. Depending on fill settings, $s may be normalized in place.

picture

my $result = $obj->picture( $input, $autoFill );

Evaluates $input and returns a TPicResult status.

The parser recognizes the following control tokens in pic:

  • # digit

  • ? letter

  • & letter, force uppercase

  • ! any character, force uppercase

  • @ any character

  • ; escape next character as literal

  • * repetition of next token or group

  • [] optional group

  • {} group

  • , alternatives inside a group

PRACTICAL VALIDATION EXAMPLES

  • US Phone Number: (###)###-####

    Enforces exactly 10 digits wrapped in standard telephone punctuation.

  • US Zip Code: #####[-####]

    Requires 5 digits, but allows an optional hyphen and 4-digit extension.

  • State Abbreviation: &&

    Requires exactly two letters and forces them into capital letters.

  • Boolean Choice: {Yes,No,Maybe}

    Restricts data entry strictly to one of the three words in the comma-separated list.

SEE ALSO

TValidator, TUI::Validate::Const

AUTHORS

  • Borland International (original Turbo Vision design)

  • J. Schneider <brickpool@cpan.org> (Perl implementation and maintenance)

COPYRIGHT AND LICENSE

Copyright (c) 1990-1994, 1997 by Borland International

Copyright (c) 2026 the "AUTHORS" as listed above.

This software is licensed under the MIT license (see the LICENSE file, which is part of the distribution).