Noob question: How to read the API?

[rowlesmr]

I'm trying to figure out how to read the documentation. I'm new to interpreting C++ docs, but have experience with Java and some Python.

I can see from the example code in the documentation that I can call in.string() to get the current token as a string from the Input. What other methods are available? I can see that errors have a position. Do Inputs have positions? How can I find out how to get the position?

Along the same lines, I read that I can alter the tracking behaviour of read_input. I understand that the default behaviour is eager tracking and lr or crlf line endings. If I explicitly instantiate that by pegtl::file_input<pegtl::tracking_mode::eager, pegtl::eol::lf_crlf> in("C:\\data\\filename.ext"); it works. If I try pegtl::file_input<pegtl::tracking_mode::lazy, pegtl::eol::lf_crlf> in("C:\\data\\filename.ext");, I get a bunch of compiler errors, the first of which is 1>C:\Users\184277j\Documents\GitHub\PEGTL\include\tao\pegtl\internal\bol.hpp(22,20): error C2039: 'column': is not a member of 'tao::pegtl::file_input<tao::pegtl::tracking_mode::lazy,tao::pegtl::ascii::eol::lf_crlf>'

Am I just reading the docs wrong?

Sorry for the low level of question. I can make up a MWE of the above error if needed.

[ColinH]

You are generally reading the docs correctly, however what might not be clear enough are the implications of this part of the documentation of the bol rule: "Does not work with inputs that don't have a column() member function."

The bol rule uses the column number from the current position in order to determine whether the input is at the beginning of a line. Now there are two ways how it could get at the column number, either query the input for the position and extract the column number, or directly query the input for the column number.

Now there are two design decisions that prevent the bol rule to work with lazy position tracking. The first is that the bol rule directly asks the input for the column number. The second is that this function is only available on inputs with eager position tracking.

This is because asking a lazy input for any position information is an expensive operation, it has to scan the entire input from beginning up to the current position in order to count lines and then columns. This is a good fit when the position information is only ever used for (parse) errors, which usually means zero or one time during a parsing run.

If however you use the position information frequently, which can be for tracing, when accessing it frequently in actions, or, like in this case, when a parsing rule depends on it, then eager tracking is the way to go since always updating the position information will (most probably) be cheaper than frequently having to re-scan the entire input.

[rowlesmr]

Ta for that.

when a parsing rule depends on it

is what I didn't realise for pegtl::bol.