Support for properties

[dragonwasrobot]

Hi, and thx for providing an elixir package for org-mode parsing :)

I was wondering if you are planning on supporting org :PROPERTIES: blocks, usually located right under headlines, see https://orgmode.org/manual/Property-syntax.html ? as I'm looking to do statistics over some org-mode files that heavily utilise these :PROPERTIES: blocks.

I would also be happy to supply a further information, if need be, or a PR if that is preferable.

[aviav]

Since I need properties myself, and like how this parser works, I added some basic property support. In case you do not need some advanced features, maybe this already resolves your issue. See #3

[dragonwasrobot]

Cool, looks like it will solve my needs.

[aviav]

Great! Could you maybe test it on some files to see whether the changes do not break anything for you? In case you should notice any such flaws, you can comment on the PR and it is quite likely I would find the time to fix them.

This kind of testing would be valuable to me, since the files that I currently work with are really simple and small and thus maybe kind of atypical

[dragonwasrobot]

Did a quick test with:

* 2019
** 2019-01 January
*** 2019-01-01 Tuesday
:PROPERTIES:
:FOO: Bar
:END:
Some paragraph.
*** 2019-01-02 Wednesday
:PROPERTIES:
:FOO: Buzz
:QUX: Test
:END:
Another paragraph.

and got

%Org.Document{
  comments: [],
  contents: [],
  sections: [
    %Org.Section{
      children: [
        %Org.Section{
          children: [
            %Org.Section{
              children: [],
              contents: [%Org.Paragraph{lines: ["Some paragraph."]}],
              properties: [FOO: "Bar"],
              title: "2019-01-01 Tuesday"
            },
            %Org.Section{
              children: [],
              contents: [%Org.Paragraph{lines: ["Another paragraph."]}],
              properties: [FOO: "Buzz", QUX: "Test"],
              title: "2019-01-02 Wednesday"
            }
          ],
          contents: [],
          properties: [],
          title: "2019-01 January"
        }
      ],
      contents: [],
      properties: [],
      title: "2019"
    }
  ]
}

So looks to be working as expected :)

While testing I noticed that if I add a property with a key and no value:

:PROPERTIES:
:SOME_FLAG:
:END:

I get an error from the parser. But looking at the org-mode documentation I'm not sure if a property without a value is actually valid org-mode syntax.

[dragonwasrobot]

One more thought: might also be cool to try and parse the property value type, e.g.

:FOO: t -> [FOO: true]
:FOO: nil -> [FOO: nil]
:FOO: 42 -> [FOO: 42]
:FOO: helicopter -> [FOO: "helicopter"]

but wasn't able to find anything specific in the org-mode docs about how property value types.

[aviav]

Thanks for testing! With types, I have something similar in mind. Maybe I'll also use it for dates and times (and then parse time-tracking as well?), because then I could really make do without a full-fledged database system for a while. However, my next step would be to look whether I can just re-use something for this. Parsing types sounds universal enough that somebody could have already done that in Elixir as well.

Your point about getting an error from the parser is a good one. I usually do not write parsers, so maybe I should read up on whether it is better to just ignore lines that do not parse, or whether it is better to work with exceptions or crash or something

[dragonwasrobot]

Parsing date+time would be really useful indeed.

Implementing good parser errors is a non-trivial task (can recommend reading https://elm-lang.org/blog/compiler-errors-for-humans on good error reporting).

Given that org-mode does not report if your org-mode markup isn't as expected, one could argue that the parser should take a similar 'optimistic' approach to parsing, i.e. parse what you can and perhaps add some good errors/warnings for stuff that looks wrong.