Lorg in a nutshell

Lorg defines a syntax to organize hierarchical data. Hierarchical data are components containing other components. Here is a full example of a Lorg document used to prepare the gear for a trek. 

# Sleep
    ## Shelter
        Should I use a tent instead?
        ### Trekking poles
            $ Cost: 69
            $ Weight: 560
        ### Tarp
            $ Cost: 60
            $ Weight: 495
    ## Sleeping bag
        $ Cost: 51.99
        $ Weight: 1200.00
        ### Liner
            $ Cost: 50
            $ Weight: 340
# Clothes
    I should bring a jacket.
    And maybe a beanie.
    ## Poncho
        $ Cost: 49
        $ Weight: 400
    ## Tee-shirt
        $ Cost: 0
        $ Weight: 150
    ## Shoes
        $ Cost: 169
        $ Weight: 0
        I wear them so no weight in the backpack.

Your goal with this document is to have the total Cost and Weight of your gear.

By glancing at the example you can certainly already create your own Lorg documents, but let's explain how this document is structured.

Leading and trailing spaces

Leading spaces (spaces at the beginning of a line) and trailing spaces (spaces at the end of a line) are ignored. They can be used to make the visualization of the hierarchy easier.

Nodes

In Lorg, components are call nodes. Nodes have a title, children and units.

In this example, there is a node with the title Poncho. It is the child of the node with the title Clothes. It defines two units: Cost and Weight.

If you know Markdown, you already know how to structure your nodes. You use # to define the hierarchy and the number of # defines the node level.

Multiple nodes can have the same title.

In our example:

  • The node with the title Clothes has a level of 1.
  • The node with the title Sleep is a sibling of Clothes.
  • The node with the title Poncho is a child of Clothes.

Units

In Lorg, we define units. They have a name and a value. We associate nodes with units.

To define a unit, start a line with a $ followed by the unit name then by : then by the unit value.

A unit name can contain spaces and :. For example the names Weight (g) and expenses:groceries are valid.

A unit value can be an integer or a decimal. The number must be in the Base-10 number system like (example: 34.5, 15). Hexadecimal values like 0xFF are invalid.

If a node defines multiple times a value for the same unit, then the last defined value is considered.

If you do not know the value of a unit in a node: do not define it! The values will be calculated by Lorg according to the unit values in the node children. This is the whole point of Lorg!

For the moment, Lorg only sums the values. Maybe in the future other operations will be available (average, min, max...).

In our example:

  • Tee-shirt has a Cost of 0 and a Weight of 150.
  • Clothes does not have any units. Lorg will calculate its associated Cost and Weight units.

Comments

All lines that are not node definitions or unit definitions are comments. Comments are ignored by Lorg.

In our example, the line I should bring a jacket. is ignored.

Getting the result

Lorg (with the options prettify and total activated) returns this result for our example. 

TOTAL
│ $ Cost: 398.99 [Calculated]
│ $ Weight: 2805 [Calculated]
├── Sleep
│   │ $ Cost: 180.99 [Calculated]
│   │ $ Weight: 2255 [Calculated]
│   ├── Shelter
│   │   │ $ Cost: 129 [Calculated]
│   │   │ $ Weight: 1055 [Calculated]
│   │   ├── Trekking poles
│   │   │     $ Cost: 69
│   │   │     $ Weight: 560
│   │   └── Tarp
│   │         $ Cost: 60
│   │         $ Weight: 495
│   └── Sleeping bag
│       │ $ Cost: 51.99
│       │ $ Weight: 1200
│       └── Liner
│             $ Cost: 50 [Ignored]
│             $ Weight: 340 [Ignored]
└── Clothes
    │ $ Cost: 218 [Calculated]
    │ $ Weight: 550 [Calculated]
    ├── Poncho
    │     $ Cost: 49
    │     $ Weight: 400
    ├── Tee-shirt
    │     $ Cost: 0
    │     $ Weight: 150
    └── Shoes
          $ Cost: 169
          $ Weight: 0

When a unit was not defined in the document, it is calculated by Lorg. If the node does not have children, the value is 0. Else the value is calculated according to the children. In all cases, those created units are indicated by [Calculated]

A unit defined in the document can be ignored. This means that its value is not used for the total. It happens when a parent already set a value. Those ignored units are indicated by [Ignored]

In our example:

  • Clothes now has units. The units values are the sum of the unit values of its children.
  • The unit values of Liner are ignored because its parent Sleeping bag has already defined values for the same units.

Using Lorg

Lorg is open source. Lorg is available as a command line interface or as a web app.

When using the CLI version, write your document into a file and use the lorg command. If we put our example in a file named trek.lorg, we can use the following command. 

lorg trek.lorg

By convention, Lorg file extension is .lorg but you can use any other file extension.

You now know everything you need to know to use Lorg. We hope you will find Lorg useful for you!

Syntax definition in English

Here is the syntax definition written in English. This section is aimed for people who want to develop their own Lorg software. Lorg syntax was designed to be easy to pick up so you can certainly use Lorg without reading this section.

Various

The character carriage return (ASCII code 13 or 0x0D) is completely ignored. Why? Because Microsoft Windows users would certainly not want to put this character into their node titles or their unit values, and this character is not used except for defining the end of a line.

Any character is any character except the new line character (ASCII code 10 or 0x0A).

A white space can be the space character (ASCII code 32 or 0x20) or the tabulation character (ASCII code 9).

Optional white spaces is zero or multiple white spaces.

Leading spaces is optional white spaces at the beginning of a line.

Trailing spaces is optional white spaces at the end of a line.

A digit is 0 or 1 or 2 or 3 or 4 or 5 or 6 or 7 or 8 or 9.

An integral is at least one digit.

A decimal is at least one digit then . then at least one digit.

A number is a decimal or an integral. decimal definition has a precedence over integral definition.

Nodes

A node heading contains one or more #.

A node title contains a non white space then zero or more any character, and must end with a non white space.

A node definition is defined in a full line from the first character of the line to the last character.

A node definition ignores leading spaces and trailing spaces.

A node definition contains a node heading then optional white spaces then a node title.

The number of # in the node heading defines the node level.

In a Lorg document, there can be multiple node definitions with a node level of 1. For nodes with a superior node level, the node level must not be superior to 1 + the node level of the previous node definition. In other words, a node must be the sibling or the direct descendant of another node.

If a line starts a node definition but it is not a valid node definition (for example it does not contain the node title), then this is an error.

Units

A unit name contains a non white space then zero or more any character, and must end with a non white space.

A unit value is a number.

A unit definition is defined in a full line from the first character of the line to the last characters.

A node definition ignores leading spaces and trailing spaces.

A unit definition contains a $ then optional white spaces then a unit name then optional white spaces then a : then optional white spaces then a unit value. This means that unit names can contain one or more : and white spaces.

A unit definition must follow, but not necessarily directly, a node definition. In other words, a unit definition must be associated with a node definition.

If a line starts a unit definition but it is not a valid unit definition (for example it does not contain a unit value), then this is an error.

Comments

All lines that are not node definitions or unit definitions are comments; they are ignored.

Behaviour

When Lorg parses a Lorg document, it creates a tree of nodes. A node contains a title, units and other nodes (its children).

Multiple nodes can have the same title.

A unit value can be considered as real or calculated. A real unit value is a value explicitly defined in the Lorg document. A calculated unit value is a value calculated by Lorg.

When a unit is not defined in the Lorg document for a node but is defined for another node, Lorg creates this unit and set it as calculated. If the node does not have children then the unit value is set to the default unit value (which is0); if the node has children then the unit value is the sum of the children unit values.

A unit can be defined multiple times in a node. Only the last value is considered.

A unit can be considered as ignored. When a unit value is considered as real in a node, then all the unit values of the children of this node for this unit are considered ignored. This means that those ignored unit values are not used to get the unit value for the highest node parent (the node of node level 1).

Lorg can create a main node called the total node if the user activates the option. All nodes with a node level of 1 are the children of this total node. The total node calculates its unit values as it is done for any other nodes.

Lorg can also export the result in the JSON format.