bionic (5) aewan.5.gz

Provided by: aewan_1.0.01-4.1_amd64 bug

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

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)