Hledger.Utils.Parse

Trace to stderr or log to debug log the provided label (if non-null) and current parser state (position and next input), if the global debug level is at or above the specified level. See also: Hledger.Utils.Debug, megaparsec's dbg. Uses unsafePerformIO. XXX Can be hard to make this evaluate.

Custom error data for hledger parsers. Specialised for a Text parse stream. ReparseableTextParseErrorData ?

A specialised version of ParseErrorBundle: a non-empty collection of hledger parse errors, equipped with PosState to help pretty-print them. Specialised for a Text parse stream.

Fail at a specific source position, given by the raw offset from the start of the input stream (the number of tokens processed at that point).

Fail at a specific source interval, given by the raw offsets of its endpoints from the start of the input stream (the numbers of tokens processed at those points).

Note that care must be taken to ensure that the specified interval does not span multiple lines of the input source. This will not be checked.

A fragment of source suitable for "re-parsing". The purpose of this data type is to preserve the content and source position of the excerpt so that parse errors raised during "re-parsing" may properly reference the original source.

Get the raw text of a source excerpt.

'excerpt_ p' applies the given parser p and extracts the portion of the source consumed by p, along with the source position of this portion. This is the only way to create a source excerpt suitable for "re-parsing" by reparseExcerpt.

'reparseExcerpt s p' "re-parses" the source excerpt s using the parser p. Parse errors raised by p will be re-thrown at the source position of the source excerpt.

In order for the correct source file to be displayed when re-throwing parse errors, we must ensure that the source file during the use of 'reparseExcerpt s p' is the same as that during the use of excerpt_ that generated the source excerpt s. However, we can usually expect this condition to be satisfied because, at the time of writing, the only changes of source file in the codebase take place through include files, and the parser for include files neither accepts nor returns SourceExcerpts.

Pretty-print our custom parse errors. It is necessary to use this instead of errorBundlePretty when custom parse errors are thrown.

This function intercepts our custom parse errors and applies final adjustments (finalizeCustomError) before passing them to errorBundlePretty. These adjustments are part of the implementation of the behaviour of our custom parse errors.

Note: We must ensure that the offset of the PosState of the provided ParseErrorBundle is no larger than the offset specified by a ErrorFailAt constructor. This is guaranteed if this offset is set to 0 (that is, the beginning of the source file), which is the case for ParseErrorBundles returned from runParserT.

A type representing "final" parse errors that cannot be backtracked from and are guaranteed to halt parsing. The anti-backtracking behaviour is implemented by an ExceptT layer in the parser's monad stack, using this type as the ExceptT error type.

We have three goals for this type: (1) it should be possible to convert any parse error into a "final" parse error, (2) it should be possible to take a parse error thrown from an include file and re-throw it in the context of the parent file, and (3) the pretty-printing of "final" parse errors should be consistent with that of ordinary parse errors, but should also report the stack of parent files when errors are thrown from included files.

In order to pretty-print a "final" parse error (goal 3), it must be bundled with include filepaths and its full source text. When a "final" parse error is thrown from within a parser, we do not have access to the full source, so we must hold the parse error (FinalParseError) until it can be combined with the full source (and any parent file paths) by the parser's caller (FinalParseErrorBundle).

A type bundling a ParseError with its full source text, filepath, and stack of include files. Suitable for pretty-printing.

Megaparsec's ParseErrorBundle type already bundles a parse error with its full source text and filepath, so we just add a stack of include files.

Convert a "regular" parse error into a "final" parse error.

Like megaparsec's fancyFailure, but as a "final" parse error.

Like fail, but as a "final" parse error.

Like megaparsec's customFailure, but as a "final" parse error.

Pretty-print a "final" parse error: print the stack of include files, then apply the pretty-printer for parse error bundles. Note that attachSource must be used on a "final" parse error before it can be pretty-printed.

Attach a filepath and source text to a "final" parse error so that it can be pretty-printed. You must ensure that you provide the appropriate source text and filepath.

Parse an include file with the given parser and initial state, discarding the resulting state, and re-throwing any parse errors as final parse errors with the file's info attached.