commocore/petscii

Converts text to PETSCII compatible format (used on Commodore 8-bit computers)

v1.0.1 2018-09-23 23:10 UTC

README

Petscii is a tiny PHP library which converts text to PETSCII (PET Standard Code of Information Interchange) format, a character set based on ASCII. It has been used in Commodore Business Machines - the 8-bit home computers like VIC-20, C64, C128, CBM-II, Commodore Plus/4, C16 and C116.

With this package, you can prepare your website to be fully compatible with web browsers available for Commodore 64 or Commodore 128 connected to internet via one of existing ethernet cartridges: 64NIC+, The Final Ethernet, RR-Net or other. You can even surf the web using an emulator.

This package is used on www.commocore.com website.

Supported browsers

Petscii package has been tested on a few Commodore 64 browsers. Please let me know if you're using other ones, or you've encountered any issues. Also, please let me know if some of the links below are no longer available.

Contiki web browser

Online HTML web browser available with a web server and other tools. Set up disk configurator for version 2.5 available here. Contiki 3 is available here.

Singular browser

Online HTML web browser. About the browser here. Set up disk available here.

HyperLink

Online HTML web browser. Not tested yet, but detected by PETSCII. More info here.

FairlightML

Offline HTML viewer also known as 64'er htmlreader. Version 0.99 is available here. You can download files using WGET (available i.a. on Contiki floppy disk).

Entering World Wide Web with emulator

If you don't have physical ethernet card, you can try Vice64 emulator for Windows (with WinPcap installed). You will find details in this Commodore Server blog entry.

Features

  • All non-ASCII characters are converted to basic ASCII-96
  • Can detect if browser is running in PETSCII mode (HTTP user agent check)
  • Pound Sterling character will be converted to the responding PETSCII character CHR$(92) for Contiki browser
  • All variations of break line tag (e.g. <br />) will be converted to <br> ( FairlightML browser cannot detect other variations)

Installation

To install via Composer, just:

composer require commocore/petscii

This package uses Composer autoloader, regular boot looks this way (for more details, see Composer documentation):

require_once '../vendor/autoload.php';

And can be imported this way:

use Commocore\Petscii\Petscii;

Usage

$content = 'Commodore 64<br />The Commodore 64 is an 8-bit home computer introduced in January 1982.<br />';

$petscii = new Petscii();
$content = $petscii->render($content);

echo $content;

As you see, you don't have to check if browser supports PETSCII. HTTP user agent is recognized automatically, and if a browser doesn't support PETSCII, text content will be displayed without any changes.

To trim break lines (or other characters), just provide them in string as the second parameter (uses PHP's trim() mask):

$content = $petscii->render($content, '<br>');

Note: you don't have to define other variations of <br> in trim mask (e.g. <br />) as all variations of break line will be converted to <br> by default.

To check if browser is supporting PETSCII:

if ($petscii->isPetsciiBrowser()) {
    // I'm PETSCII!
}

To return browser class detected by HTTP user agent:

$browserClass = $petscii->getDetectedBrowser();

Or, to get only the class name (without namespace):

$className = substr(strrchr(get_class($petscii->getDetectedBrowser()), "\\"), 1);

Testing the package

Docker (with Docker Compose) has been used for testing purposes.

Setup

  1. First, you need to build images by executing make build.
  2. Then, you can execute make all in the main directory for the first time to install PHP dependencies and run containers, or use make composer then make start.

Executing tests

You will find all available make commands in Makefile. To test the whole project just make test. For the test coverage, if make phpunit-code-coverage-html is used, results will be saved to coverage/ folder in the HTML format.

Testing available characters

To see characters available in a particular browser, you can create test page where you can generate list of all 256 characters this way:

echo $petscii->getTestPage();

Notes

Underscore character compatibility

As Contiki browser is not using underscore character (instead left arrow CHR$(95) is displayed), and there is no equivalent available for this browser, you can ignore it, or remove underscores from text beforehand. This character is fully supported e.g. in FairlightML HTML viewer and Singular browser.