NAME

Text::Convert::PETSCII - ASCII/PETSCII text converter

SYNOPSIS

  use Text::Convert::PETSCII qw/:all/;

  # Convert an ASCII string to a PETSCII string:
  my $petscii_string = ascii_to_petscii($ascii_string);

  # Convert a PETSCII string to an ASCII string:
  my $ascii_string = petscii_to_ascii($petscii_string);

  # Convert CBM screen codes to a PETSCII string:
  my $petscii_string = screen_codes_to_petscii($screen_codes);

  # Convert a PETSCII string to CBM screen codes:
  my $screen_codes = petscii_to_screen_codes($petscii_string);

  # Set mode for writing PETSCII character's representation to a file handle:
  set_petscii_write_mode($write_mode);

  # Write PETSCII single character's textual representation to a file handle:
  write_petscii_char($file_handle, $petscii_char);

  # Validate whether given PETSCII string text may normally be printed out:
  my $is_printable = is_printable_petscii_string($petscii_string);

  # Validate whether given text may be considered a valid PETSCII string:
  my $is_valid = is_valid_petscii_string($text_string);

DESCRIPTION

This package provides two basic methods for converting text format between ASCII and PETSCII character sets. PETSCII stands for the "PET Standard Code of Information Interchange" and is also known as CBM ASCII. PETSCII character set has been widely used in Commodore Business Machines (CBM)'s 8-bit home computers, starting with the PET from 1977 and including the VIC-20, C64, CBM-II, Plus/4, C16, C116 and C128.

METHODS

ascii_to_petscii

Convert an ASCII string to a PETSCII string:

  my $petscii_string = ascii_to_petscii($ascii_string);

Input data is handled as a stream of bytes. When original ASCII string contains any non-ASCII character, a relevant warning will be triggered, providing detailed information about invalid character's integer code and its position within the source string.

petscii_to_ascii

Convert a PETSCII string to an ASCII string:

  my $ascii_string = petscii_to_ascii($petscii_string);

Input data is handled as a stream of bytes. Note that integer codes between 0x80 and 0xff despite of being valid PETSCII codes are not convertible into any ASCII equivalents, therefore they trigger a relevant warning, providing detailed information about invalid character's integer code and its position within the source string.

screen_codes_to_petscii

Convert CBM screen codes to a PETSCII string:

  my $petscii_string = screen_codes_to_petscii($screen_codes);

Input screen codes are expected to be a scalar value that is handled as a stream of bytes. And so is a returned value.

petscii_to_screen_codes

Convert a PETSCII string to CBM screen codes:

  my $screen_codes = petscii_to_screen_codes($petscii_string);

Input PETSCII string is expected to be a scalar value that is handled as a stream of bytes. And so is a returned value.

set_petscii_write_mode

Set mode for writing PETSCII character's textual representation to a file handle:

  set_petscii_write_mode('shifted');
  set_petscii_write_mode('unshifted');

There are two modes available. A "shifted" mode, also known as a "text" mode, refers to mode, in which lowercase letters occupy the range 0x41 .. 0x5a, and uppercase letters occupy the range 0xc1 .. 0xda. In "unshifted" mode, codes 0x60 .. 0x7f and 0xa0 .. 0xff are allocated to CBM-specific block graphics characters.

If not set explicitly, writing PETSCII char defaults to "unshifted" mode.

write_petscii_char

Write PETSCII character's textual representation to a file handle:

  write_petscii_char($fh, $petscii_char);

$fh is expected to be an opened file handle that PETSCII character's textual representation may be written to, and $petscii_char is expected to either be an integer code (between 0x20 and 0x7f as well as between 0xa0 and 0xff, since control codes between 0x00 and 0x1f and between 0x80 and 0x9f are not printable by design) or a character byte (the actual single byte with PETSCII data to be processed, same rules for possible printable characters apply).

is_printable_petscii_string

Validate whether given PETSCII string text may normally be printed out:

  my $is_printable = is_printable_petscii_string($petscii_string);

Returns true value upon successful validation, and false otherwise. False value will also be immediately returned when text string that is given as an argument is not a PETSCII string at all.

is_valid_petscii_string

Validate whether given text may be considered a valid PETSCII string:

  my $is_valid = is_valid_petscii_string($text_string);

Returns true value upon successful validation, and false otherwise.

BUGS

There are no known bugs at the moment. Please report any bugs or feature requests.

EXPORT

No method is exported into the caller's namespace by default.

Selected methods may be exported into the caller's namespace explicitly by using the following tags in the import list:

• convert tag adds "ascii_to_petscii" and "petscii_to_ascii" subroutines to the list of symbols to be imported into the caller's namespace

• display tag adds "set_petscii_write_mode" and "write_petscii_char" subroutines to the list of symbols to be imported into the caller's namespace

• screen tag adds "screen_codes_to_petscii" and </petscii_to_screen_codes> subroutines to the list of symbols to be imported into the caller's namespace

• validate tag adds "is_printable_petscii_string" and </is_valid_petscii_string> subroutines to the list of symbols to be imported into the caller's namespace

• all tag adds all subroutines listed by convert, display, screen, and validate tags to the list of exported symbols

AUTHOR

Pawel Krol, <pawelkrol@cpan.org>.

VERSION

Version 0.05 (2013-03-08)

COPYRIGHT AND LICENSE

Copyright 2011, 2013 by Pawel Krol <pawelkrol@cpan.org>.

This library is free open source software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.

PLEASE NOTE THAT IT COMES WITHOUT A WARRANTY OF ANY KIND!

cpanm Text::Convert::PETSCII

perl -MCPAN -e shell
install Text::Convert::PETSCII