NAME

Term::CLI::Argument::Bool - class for "boolean" arguments in Term::CLI

VERSION

version 0.04002

SYNOPSIS

 use Term::CLI::Argument::Bool;

 # Case-insensitive booleans (default)
 my $arg = Term::CLI::Argument::Bool->new(
     name => 'arg1',
     ignore_case => 1, # default
 );

 $arg->validate( 'true' );  # -> returns 1
 $arg->validate( 'tRuE' );  # -> returns 1
 $arg->validate( '1' );     # -> returns 1

 $arg->validate( 'false' ); # -> returns 0
 $arg->validate( 'FaLsE' ); # -> returns 0
 $arg->validate( '0' );     # -> returns 0

 $arg->validate( 'never' ); # -> returns undef, sets error.

 # Case-sensitive booleans
 $arg = Term::CLI::Argument::Bool->new(
     name => 'arg1',
     ignore_case => 0,
 );

 $arg->validate( 'tRuE' );  # -> returns undef, sets error.
 $arg->validate( 'FaLsE' ); # -> returns undef, sets error.

 # Alternative booleans
 $arg = Term::CLI::Argument::Bool->new(
     name => 'arg1',
     true_values => ['on', 'yes'],
     false_values => ['off', 'no'],
 );

 $arg->validate( 'on' );    # -> returns 1
 $arg->validate( 'off' );   # -> returns 0

 # Abbreviation
 $arg->validate( 'y' );     # -> returns 1
 $arg->validate( 'n' );     # -> returns 0
 $arg->validate( 'o' );     # ambiguous -> returns undef, sets error.

DESCRIPTION

Class for "boolean" string arguments in Term::CLI(3p).

This class inherits from the Term::CLI::Argument(3p) class.

By default, the valid strings for a boolean are:

true, 1

A true value.

false, 0

A false value.

Case-Insensitive Matching

By default, the object's validate() and complete() methods ignore case, so FAlsE validates as "false", and TR will have a completion of TRue.

Set the ignore_case flag to 0 to do case-sensitive matching.

Abbreviations

The validate method accepts abbreviations as long as they are uniquely identifying either one or more "true" values or one or more "false" values.

For example, if you specify the following:

true_values => [ "on", "yes" ]

false_values => [ "off", "never", "no" ]

Then the string o will not validate since it matches both a "true" value (on) and a "false" value (off). On the other hand, the string n will validate, for although it matches both never and no, those values are both "false" values, so there is no ambiguity.

CLASS STRUCTURE

Inherits from:

Term::CLI::Argument(3p).

Consumes:

None.

CONSTRUCTORS

new ( name => STRING, ... )

See also Term::CLI::Argument(3p).

Additional attributes:

true_values => ArrayRef[Str]

List of values that are considered to be "true". Default is ['true', '1'].

false_values => ArrayRef[Str]

List of values that are considered to be "false". Default is ['false', '0'].

ignore_case => Bool

Whether or not matching should ignore case. Default is 1 (so True and FALSE are valid as well).

ACCESSORS

See also Term::CLI::Argument(3p).

ignore_case ( [ Bool ] )

Get or set the ignore_case flag.

true_values ( [ ArrayRef[Str] ] )

Get or set the list of strings that denote a "true" value.

false_values ( [ ArrayRef[Str] ] )

Get or set the list of strings that denote a "false" value.

METHODS

See also Term::CLI::Argument(3p).

The following methods are added or overloaded:

validate ( Str )

Validate Str to see if it is a uniquely "true" or "false" value. Return 1 if it is a "true" value, 0 if it is a "false" value.

If the true/false validity cannot be determined, the object's error attribute is set and undef is returned.

complete ( Str )

Return a list of possible completions for Str. If ignore_case is true, then values like FA will result in ('FAlse').

SEE ALSO

Term::CLI::Argument(3p), Term::CLI(3p).

AUTHOR

Steven Bakker <sbakker@cpan.org>, 2018.

COPYRIGHT AND LICENSE

Copyright (c) 2018 Steven Bakker

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See "perldoc perlartistic."

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

cpanm Term::CLI

perl -MCPAN -e shell
install Term::CLI