Ansinerator 0.1 for PHP 4+
Updated 2006-09-02

1. Introduction
   • 1.1. What is ANSI Art?
   • 1.2. What is Ansinerator?
2. Installation
3. Quick Start
   • 3.1. Ansinerate some text
   • 3.2. Make an ANSI library
   • 3.3. Instantiating ansicons
   • 3.4. Using XML to instantiate ansicons
4. User's Guide
   • 4.1. Configuration
   • 4.2. Ansicon Libraries
     • 4.2.1. Ansicon Definitions
5. Fonts

Ansinerator is a retrospective into the minimal and resourceful activity of drawing graphics in a textmode display, a method which was highly active in the 80s primarily in conjuction with bulletin board systems (BBS). ANSI is an acronym for the American National Standards Institute, but in this context, it simply refers to the formatting standard used by early computer terminals (DOS is a common example). ANSI provided a standardized set of control sequences (specifically the x3.64 standard) that can be interpreted by terminals as instructions for how to display ASCII information. These sequences define quite a large number of instructions, ranging from cursor/carret movement to color settings. In addition, certain system fonts used in these terminals reserved a number of characters for drawing and shading blocks that could be arranged and configured in various ways to do things like drawing boxes or blending colors. Since its conception, the standard has been used as a platform to draw art by a community of people commonly referred to as artscene.

Ansinerator attemps to adhere to the original specification of ANSI formatted terminals as defined in 1979 to maintain compatibility with other ANSI art tools.

Ansinerator is a PHP library that processes ANSI graphics for the web.

Ansinerator's primary feature is the ability to generate PNG representations of art drawn in classic ANSI terminal emulation ('ANSI art'), but it also has a robust set of classes that can be used to further generate, manipulate and format ANSI art using an object-oriented workflow with an emphasis on fully integrating the output with web design.

The ANSI art that Ansinerator can interpret is usually stored in ASCII files generated by ANSI art drawing programs that format the file in the original ANSI x3.64 specification to include things like color coding or cursor positioning. The art stored in these ASCII files can be divided into meaninful blocks that Ansinerator can understand by writing some processing instructions into the files using a few syntax rules. Preparing an ANSI file in this manner results in a usable ANSI art graphics library containing 'prototype' art, graphics or widgets that can be instantiated, configured and combined with Ansinerator to be rendered into a larger ANSI art composition.

Ansinerator also provides various means for formatting ASCII or strings not derived from pre-existing ANSI art files, and other classes that can automatically generate ANSI control sequences for low-level manipulation and modification to the composition.

Ansinerator can accurately render the output as a bitmap using the classic 80x25 system font (or any custom-defined fixed-width bitmap font) in an 16 color pallette. When working in a web framework, hyperlinks are also supported and retained using HTML image maps. The script can also render the output back into ANSI x3.64 formatted ASCII for viewing in other ANSI art viewers or editors.

Ansinerator is designed to be as lightweight as possible. It makes use of the gd library, included in the standard PHP installation. Ansinerator is compatible with PHP 4 and newer.

Extract the contents of the Ansinerator package into your web path. By default, Ansinerator's resources are stored subdirectories, so make sure that they do not conflict with any existing paths. You can easily change the default paths used by Ansinerator.

Ansinerator renders the png files into the default relative-path 'output/', so you must make sure that PHP has sufficient privileges to write to the folder (This default location can also be changes). Set the permissions on the folder to read/write by everyone (world). If you have shell access use the following command:

chmod o+rw output/

If you are using an FTP client, the program also should have options to modify the permissions of files and folders. If you do not have access to modifying permissions on files and folders on your server, contact you server administrator.

This section provides a set of step-by-step tutorials to help you get started with using Ansinerator. For more indepth documentation of how to use all of Ansinerator's features, see the User's Guide section.

Once you have Ansinerator setup to your liking in your website's directory structure, create a new PHP script. You can start a new Ansinerator by instantiating the Ansinerator class:

<?php
    include_once 'ansi.php';
    $ansi = new Ansinerator();
?>

There are various ways to feed the Ansinerator content, but for now we'll just feed it some simple text. We can call the Ansinerator's append() method to do this:

$ansi->append( 'Hello world.' );

Internally, the Ansinerator works with ansicons, and the string 'Hello world' is converted to one. At this point, we have provided enough data for the Ansinerator to output something. We can retrieve the result by using the get_html() method:

<?php
    include_once 'ansi.php';
    $ansi = new Ansinerator();
    $ansi->append( 'Hello world.' );
    echo $ansi->get_html();
?>

Ansinerator will use a default html template, so no html needs to be predefined. get_html() will return a string containing complete html for a page, including the PNG image that is the rendition of our content:

Ansinerator has a built in interpreter that can we can use to modify the appearance of content, such as coloring, and it works in the exact same way as ANSI control sequences would. We do this by specifying tags in the string that modify the rendering state. For example, changing Hello world.' to '[#f10]Hello world.' will tell Ansinerator that the proceeding text Hello world. should be rendered bright green:

The syntax of tags interpreted by Ansinerator is a [, followed by a #, a single character modifier (such as f in the previous example), a value (in this case 10), and finally a closing bracket ]. f is the modifier for the foreground color currently being used, and 10 refers to color 10 of an index of 16 EGA colors used by Ansinerator. These color settings affect the string until another tag changes or removes the settings. For a complete list of tags interpreted by Ansinerator, see the User's Guide section for more information about ansicons. Here is another example:

$ansi->append( '[#f14]ansi[#f12][#b4]nera[#x]tor' );

This outputs:

[#b4] sets the background color to dark blue, where [#x] is used to clear the formatting. In effect, this manipulates the rendering of the text in the same way that ANSI x3.64 control sequences do. Tags set the rendering state of the string and do not affect anything beyond the string itself, and this is because the string actually gets converted to an encapsulated ansicon. Tags are also used to specify hyperlinks; this is covered in the User's Guide section.

This goes over some of the basics of how Ansinerator can output formatted text, but there is much more that ansicons can do. You can use an ANSI drawing program to draw art that can be imported as an ansicon. The next section goes over defining ansicon libraries through such tools and importing them for use in Ansinerator.

You can draw much more complicated ANSI in a drawing tool like PabloDraw or ITPDraw, and much faster, than simply using ansinerator's string tags. These are really only geared towards formatting colors and defining hyperlinks in the content.

An ansicon library simply refers to a file made by an ANSI drawing program that has some textual formatting instructions that define blocks of drawn ANSI as 'prototype' ansicons for ansinerator. If you haven't already, get a copy of PabloDraw or ITPDraw (you can use DosBox to emulate ITPDraw on any platform). Here is a list of textmode editors. The basic syntax used in the file is like this:

#ansicon name {
// ansi drawing here
// ansi drawing here
// ansi drawing here
}end

You can define as many ansicons as you want in a file, provided you use this syntax around each ANSI drawing. See the manual all the details of defining ansicon libraries. This is an example of how an ansicon definition would look like in an ANSI editing program:

The above example defines an ansicon called banner. You can load the file generated by the drawing program into ansinerator using add_library(), and instantiate the ansicon using append(), like this:

<?php
    include_once 'ansi.php';
    $ansi = new> ansinerator();
    $ansi->add_library( 'tutorial.ans' );
    $ansi->append( 'banner' );
    echo $ansi->get_html();
?>

append() is a versatile function. By adding a library, you can use append() not only for adding basic text to the output. You can also use it to call an ansicon in a loaded library by its name using a string (in this example, 'banner'), and add it to the output. You can also use append() to attach actual ansicon objects made on the fly in the script itself. This is covered in the manual.

ansicons can take on any number of roles. They can be static blocks of ANSI that define a banner image, or they can be templates that change based on parameters or character data that can be defined for the ansicon. A common use for the latter example is defining ANSI to serve as a frame for some textual information. In addition to the banner above, lets draw some ANSI that can be used as a frame for some text and save it in the file below the banner. It should look something like this:

We can add parameters after the name of the ansicon to change its behavior in ansinerator. The parameter -f sets the ansicon to be treated as a frame. We also need to tell ansinerator how to use the drawing as a frame. ansinerator defines frames as a rectanngle with 9 regions, and some of these regions are scalable based on the size of the contents of the frame. The 1 and 2 in the frame are the two points used to slice the drawing into 9 parts. The contents of the frame will lie the region between 1 and 2.

You can call the frame1 ansicon the same way as you did the banner ansicon, except this time you can provide some text to put in the frame:

<?php
    include_once 'ansi.php';
    $ansi = new ansinerator();
    $ansi->add_library( 'tutorial.ans' );
    $ansi->append( 'frame1', '[#f10]Hello world.' );
    echo $ansi->get_html();
?>

append() can take a second parameter that is a string, and this string is used as the contents of the frame. This will output:

The original frame is reconfigured to fit the content. Lets say, however, that we want the frame to be a set width, the width of the page for example, which is 80 columns. We can add -w 80 as a parameter for the ansicon in the ansicon library file, but this tell ansinerator to make all manifestations of the ansicon be 80 blocks wide. Instead, we can add it as a third parameter for append():

<?php
    include_once 'ansi.php';
    $ansi = new ansinerator();
    $ansi->add_library( 'tutorial.ans' );
    $ansi->append( 'frame1', '[#f10]Hello world.', '-w 80' );
    echo $ansi->get_html();
?>

The output:

This will set a static width for the frame only for this one instance of its usage. For more information on frames, refer to the User's Guide section about ansicons. In addition, there are various parameters that you can specify either in the library, script, or AML that modify the behavior of the ansicon. These parameters are listed in the manual.

<?php
    include_once 'ansi.php';
    $ansi = new ansinerator();
    $ansi->add_library( 'tutorial.ans' );
    $ansi->append( 'frame1', '[#@home.html]HOME[#@]' );
    $ansi->append( 'frame1', '[#@about.html]ABOUT[#@]' );
    $ansi->append( 'frame1', '[#@contact.html]CONTACT[#@]' );
    echo $ansi->get_html();
?>

<?php
    include_once 'ansi.php';
    $ansi = new ansinerator();
    $ansi->add_library( 'tutorial.ans' );
    $ansi->append( 'frame1', '[#@home.html]HOME[#@]', '-i -w 12' );
    $ansi->append( 'frame1', '[#@about.html]ABOUT[#@]', '-i -w 12' );
    $ansi->append( 'frame1', '[#@contact.html]CONTACT[#@]', '-i -w 12' );
    echo $ansi->get_html();
?>

<?php
    include_once 'ansi.php';
    $ansi = new ansinerator();
    $ansi->add_library( 'tutorial.ans' );
    $ansi->append( 'frame1', '[#@home.html]HOME[#@]', '-i -w 12 -lf 9 -lF 0' );
    $ansi->append( 'frame1', '[#@about.html]ABOUT[#@]', '-i -w 12 -lf 10 -lF 0' );
    $ansi->append( 'frame1', '[#@contact.html]CONTACT[#@]', '-i -w 12 -lf 12 -lF 0' );
    echo $ansi->get_html();
?>

<?php
    include_once 'ansi.php';
    $ansi = new ansinerator();
    $ansi->add_library( 'tutorial.ans' );
    $ansi->append( 'banner' );
    $ansi->append( 'frame1', '[#@home.html]HOME[#@]', '-i -w 12 -lf 9 -lF 0' );
    $ansi->append( 'frame1', '[#@about.html]ABOUT[#@]', '-i -w 12 -lf 10 -lF 0' );
    $ansi->append( 'frame1', '[#@contact.html]CONTACT[#@]', '-i -w 12 -lf 12 -lF 0' );
    echo $ansi->get_html();
?>

An alternative to using a PHP script to control the output of an ansineration is to use AML (aka ansiform). AML stands for ansinerator markup language, and it is an XML based document used to deploy ansicons in the same way you would using the append() function of the ansinerator class. Knowledge of the XML syntax is assumed.

AML provides the familiar environment and syntax of XML for combining ansicons into an ansipod, and with it you can skip over using a PHP script altogether. It's great for simple ansipods that do not have dynamic content retrieved/generated on the fly, but not so good for ansipods that do require such processing. In the latter case it is suggested that you use scripting to generate the ansipod. You can have ansi.php process ansiform files directly using GET data like this:

ansi.php?aml=tutorial.xml

NOTE: By default, absolute paths to aml files have been disabled to prevent the script being executed remotely with ansicon libraries and ansiforms residing on other servers by other people.

Let's recreate the the ansipod we made in the previous section of the tutorial in AML and save it to a file. We start by defining the root node ansiform. The ansiform node can take various parameters, which are documented in the manual. For the tutorial we will only use the one specifying the title of the browser window.

<ansiform title="tutorial">
</ansiform>

Now we need to add the library containing the ansicons we were using in the previous sections of the tutorial. We do this by adding an include node within the ansiform node. It must have the parameter library with a value specifying the path to the ansiform file, relative to the script reading the ansiform:

<ansiform title="tutorial">
    <include library="tutorial.ans" />
</ansiform>

The library should be included before any ansicon nodes that use it. Let's add the banner ansicon. We use the ansicon node for this, and because banner is just a simple block of ANSI art that does need additional character data like an ansicon frame would, the node can be singular like the include node, like this:

<ansiform title="tutorial">
    <include library="tutorial.ans" />
    <ansicon name="banner" />
</ansiform>

The name parameter specifies the prototype ansicon in any of the library files that may be loaded. Let's add the ansicons that acted as the menu items earlier in the tutorial. These ansicons had character data because they behaved like frames. We also gave them some parameters to fine-tune their appearance.

<ansiform title="tutorial">
    <include library="tutorial.ans" />
    <ansicon name="banner"/>
    <ansicon name="frame1" params="-i -w 12 -lf 9 -lF 0">[#@home.html]HOME[#@]</ansicon>
    <ansicon name="frame1" params="-i -w 12 -lf 10 -lF 0">[#@about.html]ABOUT[#@]</ansicon>
    <ansicon name="frame1" params="-i -w 12 -lf 12 -lF 0">[#@contact.html]CONTACT[#@]</ansicon>
</ansiform>

We can also use the ansicon node to add simple text the output that isn't associated with a prototype ansicon. Let's add the following line to the ansiform below the last ansicon node:

<ansicon>[#f11]The quick brown fox jumps over the lazy dog.</ansicon>

The output would look like:

The User's Guide provides a more indepth look at the features of Ansinerator. To get your feet wet using the script, refer to the previous section.

The Ansinerator configuration is stored in the file ansi.config in the same place as ansi.php. You can change Ansinerator's default configuration by editing this file. It is recommended to backup this file for later reference.

The config file stores the paths that Ansinerator used, as well as output settings pertaining to PNG output. You can also use the config file to specify custom colors that are different than the standard 16 EGA colors.

The following variables must be specified in the config file:

Ansicon Libraries are ASCII files which contain a collection of ANSI art readable by Ansinerator. These files are typically edited with 3rd party programs like ITPDraw or PabloDraw, which are editing programs that streamline ANSI formatting methods. These programs encode the file with machine readable control sequences that specify color settings, cursor positioning, and other parameters.

When drawing your ANSI graphics, you also need to specify proper definitions using a minimal synatx language so that Ansinerator knows how to construct individual ansicons, which are blocks of configurable ANSI graphics in Ansinerator, from a single ANSI file. You can have any number of ansicon definitions in an ANSI file.

Each ansicon definition comprises of any number of lines of ANSI graphics surrounded with the definition syntax which looks like:

#ansicon [name] [parameters] {
  // ANSI graphics here
}end

Every piece of art you want Ansinerator to convert into a usable ansicon has to be within with this syntax. The definition must start with #ansicon, followed by a unix friendly name for the ansicon (no spaces or special characters), followed by optional parameters you can specify. As you can see, the art is surrounded by curly braces as well, followed by the string end. Here is an example of what an ansicon definition would look like in an ANSI editing program:

This particular ansicon definition defines a frame, which is art that can be used as a frame around something else. You can learn more about frames in the Using Frames section.

IMPORTANT: You must make sure that the definition syntax has no color formatting. Ansinerator is not capable of identifying syntax that has control sequences embedded in it. To prevent any malformatting, Keep the background color and foreground colors at their defaults (black and dim white) when writing the definition syntax, as shown above.

This documentation is incomplete.

This documentation is incomplete.