acon

Documentation

ACON is a minimalistic data serialization language. It stands for Awk-Compatible Object Notation and is geared towards command-line usage using acon tools.

See acon for command-line utilities and the awk script.

To include acon in your project.

# Cargo.toml
[dependencies]
acon = "0.5.0"

License

Licensed under GNU GPLv3, see the LICENSE.md file.

lib.rs:

An ACON-parsing library

This crate contains an ACON-to-tree parser that deserializes text. It can also serialize an ACON tree into text.

ACON stands for Awk-Compatible Object Notation. It is used because of its simplicity and versatility.

Examples of Acon

key value
other-key value
and_yet_another_key and some values

The key is always the first word on the line. The value consists of all remaining words on that line, trimmed by whitespace. Any superfluous whitespace between words is made into a single space. This format makes it very easy to process with awk.

Tables

{ table
  key value
}
{ other-table
  key value
}
key value

A table is denoted by the first word being a curly opening brace on a line. The name of the table is the second word. If there is no name, the table's name will be empty.

Arrays

[ array-name
  here is a single value, every line is its own value
  this is the second entry
]

Arrays start when the first word on a line is an opening square bracket. An array has no keys, only values. Arrays are ordered. Empty lines Will become empty elements. In tables empty lines are simply ignored.

Super Delimiter

If you have some deeply nesting structure, or a program that may not finish writing all closing delimiters, you can use '$' as a delimiter. This will close all open tables and arrays.

{ deeply
   { nested
      [ arrays
$ <- we've had enough, anything after the $ on this line is skipped.

key value

Dot-Pathing

All values can be retrieved using a dot-separated key-path.

use acon::Acon;
let input = r#"
{ table
   key value
  [ my-array
    { subtable
      anything goes
    }
  ]
}"#;
let result = input.parse::<Acon>().unwrap();
assert_eq!(result.path("table.my-array.0.subtable.anything").unwrap().string(), "goes");

Escaping

If you want a new-line or explicit whitespace in your value, you need to use escape codes. Dots and whitespaces in keys also require escape codes. Escaping is done by inserting (number), where number is the numeric code point value. This library handles escaping transparently. To escape or unescape is only necessary for other utilities or viewing the data in another way. When using dot-pathing, you still need to explicitly write the parenthesized elements.

use acon::Acon;
let input = r#"
  key(32)with_space(46)and_dot value(10)with(10)new(10)lines, which is interesting
"#;
let result = input.parse::<Acon>().unwrap();
assert_eq!(result.path("key(32)with_space(46)and_dot").unwrap().string(), "value(10)with(10)new(10)lines, which is interesting");

Comments

A line is ignored if the first word is a '#'. If you need this to be the first word on a line, you can use the escape code '(35)'.