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)