aewan

aewan(5)                       File Formats Manual                      aewan(5)



NAME
       aewan - File format documentation


INTRODUCTION
       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.


FILE FORMAT
       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.


REPRESENTATION OF 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.


REPRESENTATION OF INTEGERS AND BOOLEANS
       Integers use just the plain old decimal representation. The booleans are
       represented as strings: either "true" or "false" (without quotes).


REPRESENTATION OF LAYER LINES
       Each layer-line is a string, but it is specially formatted in order to
       convey the characters and attibutes 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.


LICENSE INFORMATION
       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.


SEE ALSO
       aecat(1), aewan(1)




aewan (Aewan Ascii Art Editor)     August 2005                          aewan(5)