---
name: "aewan"
section: "5"
platform: "linux"
package: "aewan"
version: "1.0.01-6"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/aewan/5"
---

# aewan(5)

File format documentation

## 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)](/aecat/1.md), [**aewan**(1)](/aewan/1.md)