Added method Document.getCounter. Interaction with using counters in …

[robertpanzer]

…the Document not possible yet

Fixes #488.

Added methods Document.getCounter(counterName) and Document.getCounter(counterName, initialValue) to the API.

The interaction with using the {counter:mycounter} macro is not possible though.

If I've understood it correctly the counters are finally stored in an attribute having the name of the counter on the Document.
All Document attributes are restored after for example BlockMacros are called in Document#parse.
The counter macro however is invoked in the conversion phase by the Substitutor after the attributes have been reset. Therefore the counter restarts at 1 again.

The first test reflects this behavior.

With a TreeProcessor it works a bit better in so far as the document can continue using the counters as the reset happens before the invocation of the Treeprocessors.
But I'd guess that when having a counter in the document, then reusing the same counter in a TreeProcessor will result in the counter sequence 2, 1.

When using counters both in a processor and the document, I think it would be better to make the processor insert the text {counter:foocounter} instead of invoking the method on the Document.

To wrap it up I wonder if it makes sense at all to invoke this API from an extension and if it has already been used by Ruby extensions.
(Maybe I completely missed a point, that's also perfectly possible)

[mojavelinux]

It seems like the rest of this sentence is missing.

[robertpanzer]

Renamed getCounter() to getAndIncrementCounter() and fixed javadoc.

[mojavelinux]

I think it's understood that these counters won't affect parsing/conversion since they are being used in a different phase. The API can leverage the counter mechanism for its own purposes. In some cases, extensions may be able to influence the attribute in the document, but as you have pointed out, it's highly dependent on when it is invoked. I'm okay with that as the API current stands. That's how it works in Ruby too. In the future, we may evolve this.