view release on metacpan or  search on metacpan

lib/Convert/ASCIInames.pm  view on Meta::CPAN

                 0x95 => [ 'MW', 'Message Waiting' ],
                 0x96 => [ 'SPA', 'Start of Protected Area' ],
                 0x97 => [ 'EPA', 'End of Protected Area' ],
                 0x98 => [ 'RES5', 'Reserved for future standardization' ],
                 0x99 => [ 'RES6', 'Reserved for future standardization' ],
                 0x9a => [ 'RES7', 'Reserved for future standardization' ],
                 0x9b => [ 'CSI', 'Control Sequence Introducer' ],
                 0x9c => [ 'ST', 'String Terminator' ],
                 0x9d => [ 'OSC', 'Operating System Command' ],
                 0x9e => [ 'PM', 'Privacy Message' ],
                 0x9f => [ 'APC', 'Application Program Command' ],
                );
    %alt2ord = ();
    %name2ord = ();

    #
    # Now for the backward conversions
    #
    while (my ($ord, $name) = each(%ord2name)) {
        $name2ord{$name->[0]} = $ord;
    }
    while (my ($ord, $name) = each(%ord2alt)) {
        $alt2ord{$name->[0]} = $ord;
    }
}

=pod

=head1 NAME

Convert::ASCIInames - ASCII names for control characters

=head1 SYNOPSIS

 use Convert::ASCIInames;

 Convert::ASCIInames::Configure(fallthrough => 1);
 $name = ASCIIname($character_ordinal);
 $name = ASCIIaltname($character_ordinal);
 $name = ASCIIdescription($character_ordinal);
 $name = ASCIIaltdescription($character_ordinal);
 $character_ordinal = ASCIIordinal($name);

=head1 DESCRIPTION

Most if not all of the non-printing characters of the ASCII character set
had special significance in the days of teletypes and paper tapes.
For example, the character code 0x00 would be sent repeatedly in order
to give the receiving end a chance to catch up; it signified "no action"
and so was named C<NUL>.  The sending end might follow each line of text
with a number of C<NUL> bytes in order to give the receiving end
a chance to return its print carriage to the left margin.  The control
characters (so-called because they were used to control aspects of
communication or receiving devices) were given short 2-to-4 letter
names, like C<CR>, C<EOT>, C<ACK>, and C<NAK>.

Some of these special purposes have become obsolete, but some of them
are still in use.  For example, character 0x07 (C<BEL>) is used to
ring the feeper; 0x05 (C<ENQ>) is recognised by many terminals as
a trigger to report their status; and 0x08 (C<BS>) still means
"move the cursor back one space".

This module will return the ASCII name for specified characters,
or the character code if given an ASCII name.  In addition, the
full descriptive name ("Start of Heading" instead of C<SOH>) is
available, although reverse translation of the descriptions isn't
provided.

Some control characters have altername names.  Character 0x13
is named C<DC3> ("Device Control 3"), but is probably better
known by its alternate name of C<XOFF>.  These alternate names
are also available through this module's functions.

=head1 USAGE

Each of the functions in this module is described below.  They
are listed in lexical order, rather than functional.

If you request the name (or alternate name) of a character that
doesn't have one, you'll either get the actual character itself,
or the name (if it has one) from the other list.  For instance,
if you request the alternate name for 0x00, which doesn't have
one, the return value will either be C<NUL> (the primary name)
or the value of C<chr(0x00)>.  The former is called "falling
through," and is controlled by the setting of the C<fallthrough>
configuration option.  If the option is set to a true value,
the module will attempt to give you the best name it can; if
it's set to a false value, you'll either get exactly what you
requested (such as the alternate name) or the character itself.

If you provide an invalid character ordinal (such as a non-integer,
or one outside the range of 0-255), Convert::ASCIInames will
throw a message using C<carp()> and use a standard substitute
value instead:

=over 4

=item o B<Ordinal is omitted or is a zero-length string>

The value 0x00 will be used.

=item o B<Ordinal E<lt> 0 or E<gt> 255>

The value 255 (0xff) will be used instead.

=item o B<Ordinal is a non-integer>

The ordinal of the first character of the argument will be used.
If option C<strict_ordinals> is set, a warning message will be
issued.

=back

=cut

=pod

=head2 ASCIIaltdescription

 $text = ASCIIaltdescription($ordinal);