Lorg is a hierarchical data manager in plain text.

Define the relation between the elements, the units for each element, and let Lorg manage the sum of the units. Lorg can be used as a CLI software or as a web app.

Showcase

Let say you want to go for a trek, and you are preparing your trekking gear. You want to know how much it will cost and how heavy it will be. Let's write a Lorg document for that!

Define your hierarchy

If you are familiar with Markdown, you already know how to define your data hierarchy. Start a line with one or more # to define your hierarchy and to give a title for your component. In Lorg, the components are named nodes. You can put spaces to make your hierarchy visually clearer.

# Sleep
    ## Shelter
        ### Trekking poles
        ### Tarp
    ## Sleeping bag
# Clothes
    ## Poncho
    ## Tee-shirt
    ## Shoes

Define your units

For each node, you can add units. Units are defined using $ followed by the unit name followed by : followed by the unit value. If you do not put a unit in a node, Lorg will automatically create the unit, and set its a value as the sum of the units of the node children. A unit value can be an integer or a floating-point number.

# Sleep
    ## Shelter
        ### Trekking poles
            $ Cost: 69
            $ Weight: 560
        ### Tarp
            $ Cost: 60
            $ Weight: 495
    ## Sleeping bag
        $ Cost: 51.99
        $ Weight: 1200.00
# Clothes
    ## Poncho
        $ Cost: 49
        $ Weight: 400
    ## Tee-shirt
        $ Cost: 0
        $ Weight: 150
    ## Shoes
        $ Cost: 169
        $ Weight: 0

Add comments

In Lorg, a comment is a line that is not a node definition or a unit definition. Comments are ignored by Lorg.

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

Let Lorg handle the calculation

Now that you have everything, let Lorg do the rest. Here is the result that Lorg could return with the correct options activated.

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
└── Clothes
    │ $ Cost: 218 [Calculated]
    │ $ Weight: 550 [Calculated]
    ├── Poncho
    │     $ Cost: 49
    │     $ Weight: 400
    ├── Tee-shirt
    │     $ Cost: 0
    │     $ Weight: 150
    └── Shoes
          $ Cost: 169
          $ Weight: 0

Why using Lorg?

Spreadsheets are incredible software, but they are not the best tools for working on hierarchical data. Lorg solves many issues.

A human friendly format

Spreadsheets are saved in a format designed only for the software. You must use the software to work on the data.

Lorg uses plain text with a simple format. You can open a Lorg file with any text editor you want. You can easily use a source control system (git, Fossil, SVN...) to manage the history of your Lorg files. Plus, the format is so simple that you can quickly hack your own version of Lorg if you do not have access to Lorg. (The first version of Lorg was written in VimScript in about three hours.)

A clear view on the data structure

Spreadsheets are tables: you have columns and rows. This disposition is great when you are working on flat data: each element has unit values but no sub-element.

When you want to work on elements having other elements, the table disposition is confusing. You end up using functionalities like group and subtotal, or you create tables on the side with manual references to other cells. In all cases, you end up with something that is messy.

On the other hand Lorg gives you a clear view on the data structure. At a glance you immediately see what element are parent elements or child elements.

Less risk of messing up data manipulation

In a spreadsheet, you have to select the cells that a formula is referring. When inserting new data, there is the risk that the new data is not referred by the formula. This is often the case when you fill a row after a table, you may forget that this row was not selected by the formula. At the end, you end up with incorrect results.

In Lorg all the data is considered. The biggest mistakes you can do is misspelling a unit name, or messing up the data hierarchy because you add too much or too little # when you defined a node. Those mistakes are really easy to catch.

Respecting your inputs

Spreadsheets do not respect your data. They modify your data to be more pleasant for the users (localizing the decimal point, adding non-breakable spaces between digits...). When you copy your data and paste them somewhere else, you have to sanitize them.

Lorg reads a plain text where you write the data into a specific format; so it does not change your data.

Fun fact, this advantage was found while writing the example above. The data were copied from a spreadsheet and pasted into a Lorg file. The author could not figure out why the result was wrong when using Lorg on these data. The reason was simple, the numbers contained non-breakable spaces and , instead of . because the spreadsheet was localized in French.

Comments

Lorg includes the possibility to add comments, and they are considered as first-class citizen. Comments are not hidden when you open a Lorg file.

UNIX philosophy

Lorg was designed to be easily integrated into scripts. If you are a UNIX or Linux user, you can easily pipe the result to filter it.

Using the previous examples, if you do not want to see the Cost unit then you can use the command grep to filter that out.

Drawbacks

As for everything, Lorg has some drawbacks.

Only sums the values

For the moment, Lorg can only do sums on numbers (integers or floating-point numbers). Maybe in future versions there will be a way to create formulas.

For power users

Lorg is designed for people who are comfortable with text editors. Lorg is not a GUI software but merely a parser for data specified in a markup language.

Vertical space

Because the categories and units are defined line by line, the data tend to take a lot of vertical space on a screen. Maybe in future versions there will be an option to print the result in a more tabular format.