aewan - File format documentation
Starting with version 0.9.0, Aewan features an all-new, easier to parse file
format. Prior versions used a binary (largely undocumented) file format, and
relied on a program (ae2aes) to convert it to a readable format. With the new
format, the ae2aes utility became unnecessary and was deprecated.
An aewan document is a gzipped file. Therefore, you must first gunzip it in
order to be able to parse its contents. On the command line, you could use
zcat or something of the sort. On a program, you will probably want to
use the
zlib library.
In the future it might be better for Aewan to supply a shared library to enable
parsing of aewan files with minimal effort. Such a library would have to be
integrated with the editor in order not to have to duplicate code (i.e. the
editor itself would be just a client of the library). But for the time being,
you have to read and parse the format on your own.
In the description below, the items in between brackets are NOT literal, they
are placeholders. [S] is a placeholder for a string and [N] is a placeholder
for a decimal integer, and [B] is a placeholder for a boolean value ('true' or
'false'). A line with "..." is not literal either, it just means
that the lines above repeat a certain number of times.
<Aewan Document v1
layer-count: int: [N]
meta-info: str: [S]
<Layer
name: str: [S]
width: int: [N]
height: int: [N]
visible: bool: [B]
transparent: bool: [B]
layer-line: str: [S]
layer-line: str: [S]
layer-line: str: [S]
(...there are <height> such lines...)
>Layer
(...there are <layer-count> such blocks...)
>Aewan Document v1
Indentation is ignored, but all other whitespace is significant.
In particular, you can't omit the space that immediately follows
the ':' field delimiters, or supply more than one space there.
Notice that the file format does not use any quotation marks
for the values, not even strings.
Strings are represented almost literally in the file (where the [S] placeholders
are in the blueprint above), and are not put in between quotes or anything.
However, special characters (ASCII codes 1 to 31) are escaped: the escape code
is a backslash, followed by the character '0' + ch, where ch is the special
character. Thus, a newline character would be represented by "\:",
since ":" is '0' + 10.
Integers use just the plain old decimal representation. The booleans are
represented as strings: either "true" or "false" (without
quotes).
Each layer-line is a string, but it is specially formatted in order to convey
the characters and attributes in that line. In order to understand the format
of a layer-line string, it is first necessary to introduce the concept of
cells. A cell in an aewan layer is each of the spaces that can contain a
character. A cell has two pieces of data: the character that is in it, and a
color attribute. The character is just that: an 8-bit value represing the
character drawn there. The color attribute is an 8-bit unsigned value that
packs the foreground and background color of a given cell, as well as standout
and blink attributes.
The following color codes are used: 0=black, 1=red, 2=green, 3=yellow, 4=blue,
5=magenta, 6=cyan, 7=white.
The 8 bits of the attribute have the following meanings: SFFFLBBB. Where S is
the standout bit, FFF is the 3-bit color code for the foreground color, L is
the blink bit, and BBB is the 3-bit color code for the background color.
The layer-line string is composed of the hexadecimal representation of
layer_width*2 bytes. Each 2 bytes is the information for one cell of the line:
the first byte is the character, and the second is the attribute. For example,
the hex representation for 'A' is 0x41, so a line with five 'A's each of them
in a different foreground color (but all with black background) would be
represented as 41104120413041404150.
Copyright (c) 2004-2005 Bruno Takahashi C. de Oliveira. All rights reserved.
This program is licensed under the GNU General Public License, version 2 or, at
your option, any later version. For full license information, please refer to
the COPYING file that accompanies the program.
aecat(1),
aewan(1)