Arrow Notes Notation (ANN) Format Specification

Arrow Notes Notation (ANN) is a lightweight and human-readable serialization format designed to represent structured data intuitively. With its distinctive arrow-based syntax and increasing dashes for deeper nesting, ANN simplifies data representation for configuration files, documentation, and human-readable data exchange. ANN is inspired by my own analog note-taking methodology.

Basic Concepts

Arrows

Arrows (->) are the foundational elements of ANN. They mark the start of a new data element and visually convey its nesting depth. Arrows are accompanied by an increasing number of dashes (-) as you descend deeper into the data structure, providing a clear indication of hierarchy.

Indentation

Indentation in ANN visually depicts nested elements. It consists of a pipe (|) character followed by a dash (-), forming a consistent pattern (|->, |-->, |--->, and so on) that enhances readability. This is meant to signify a bent arrow ↳. Indentation is fundamental to recognizing the hierarchical relationships within the data. A pipe must always line up with the first character of the parent element. For example:

-> person
   |-> name = "Alice"
  

Key-Value Pairs

Key-value pairs form the core of ANN's data representation. They consist of a key and its associated value, separated by an equal sign (=). There are no spaces around the equal sign, preserving the format's clean and succinct nature.

Syntax Rules

1. Each line in the ANN format represents a distinct data element.
2. Arrows (->) signify the start of a new data element.
3. A pipe (|) indicates a nested element.
4. Indentation with an increasing number of dashes (-) indicates the nesting level of objects and values.
5. A child element's pipe must match up with the first character of the parent element.
6. Key-value pairs are denoted by the equal sign (=).
7. Strings are enclosed within double quotes (" ").
8. Boolean values are expressed as true or false.

Examples

Example 1: Simple Key-Value Pairs

-> name = "John"
-> age = 30
-> is_student = true
  

Example 2: Nested Objects

-> person
   |-> name = "Alice"
   |-> age = 25
   |-> address
       |--> street = "123 Main St"
       |--> city = "EONville"
  

Example 3: Arrays

-> numbers = 1 2 3 4 5
  

Example 4: Complex Nesting

-> data
   |-> category
       |--> type = "A"
       |--> items = item1 item2 item3
   |-> settings
   |-> enable_feature = true
   |-> threshold = 0.5
  

Usage and Considerations

1. ANN excels in human-readable data representation. Although it can be programmatically parsed, it may not match the efficiency of formats like JSON or XML for machine communication.
2. ANN thrives in scenarios with relatively simple data structures, prioritizing readability.
3. For intricate and complex data scenarios, JSON, XML, or established serialization formats are more suitable.
4. Consistent indentation is pivotal for accurately conveying nesting hierarchy, with dashes' increasing count providing an additional visual cue.

Conclusion

Arrow Notes Notation (ANN) introduces an intuitive approach to structured data representation. Through its arrow-based syntax with increasing dashes, ANN enhances human comprehension, making it a valuable choice for situations demanding readability and quick data understanding.