initial import of the C runtime

src/runtime/c/pgf/parser.h

@@ -0,0 +1,127 @@
+#ifndef PGF_PARSER_H_
+#define PGF_PARSER_H_
+
+#include <gu/enum.h>
+#include <pgf/data.h>
+#include <pgf/expr.h>
+
+/// Parsing
+/** @file
+ *
+ *  @todo Querying the parser for expected continuations
+ *
+ *  @todo Literals and custom categories
+ *  
+ *  @todo HOAS, dependent types...
+ */
+
+typedef struct PgfParse PgfParse;
+
+/** @name Creating a new parser
+ *
+ * A #PgfParser object can parse sentences of a single concrete category into
+ * abstract syntax trees (#PgfExpr). The parser is created with
+ * #pgf_new_parser.
+ *
+ * @{ 
+ */
+
+/// A parser for a single concrete category
+typedef struct PgfParser PgfParser;
+    
+
+/// Create a new parser
+PgfParser*
+pgf_new_parser(PgfConcr* concr, GuPool* pool);
+/**<
+ * @param concr The concrete category whose sentences are to be parsed
+ *
+ * @pool
+ *
+ * @return A newly created parser for the concrete category \p concr
+ */ 
+
+/** @}
+ * 
+ * @name Parsing a sentence
+ *
+ * The progress of parsing is controlled by the client code. Firstly, the
+ * parsing of a sentence is initiated with #pgf_parser_parse. This returns an
+ * initial #PgfParse object, which represents the state of the parsing. A new
+ * parse state is obtained by feeding a token with #pgf_parse_token. The old
+ * parse state is unaffected by this, so backtracking - and even branching -
+ * can be accomplished by retaining the earlier #PgfParse objects.
+ *
+ * @{
+ */
+
+/// Begin parsing
+PgfParse*
+pgf_parser_parse(PgfParser* parser, PgfCId cat, size_t lin_idx, GuPool* pool);
+/**<
+ * @param parser The parser to use
+ *
+ * @param cat The identifier of the abstract category to parse
+ *
+ * @param lin_idx The index of the field of the concrete category to parse
+ *
+ * @pool
+ *
+ * @return An initial parsing state.
+*/
+
+
+/// Feed a token to the parser
+PgfParse*
+pgf_parse_token(PgfParse* parse, PgfToken tok, GuPool* pool);
+/**<
+ * @param parse The current parse state
+ *
+ * @param tok The token to feed
+ *
+ * @pool
+ *
+ * @return A new parse state obtained by feeding \p tok as an input to \p
+ * parse, or \c NULL if the token was unexpected.
+ *
+ * @note The new parse state partially depends on the old one, so it doesn't
+ * make sense to use a \p pool argument with a longer lifetime than that of
+ * the pool used to create \parse.
+ */
+
+
+/** @}
+ * @name Retrieving abstract syntax trees
+ *
+ * After the desired tokens have been fed to the parser, the resulting parse
+ * state can be queried for completed results. The #pgf_parse_result function
+ * returns an enumeration (#GuEnum) of possible abstract syntax trees whose
+ * linearization is the sequence of tokens fed so far.
+ *
+ * @{
+ */
+
+
+/// An enumeration of #PgfExpr elements.
+typedef GuEnum PgfExprEnum;
+
+
+/// Retrieve the current parses from the parse state.
+PgfExprEnum*
+pgf_parse_result(PgfParse* parse, GuPool* pool);
+/**<
+ * @param parse A parse state
+ *
+ * @pool
+ * 
+ * @return An enumeration of #PgfExpr elements representing the abstract
+ * syntax trees that would linearize to the sequence of tokens fed to produce
+ * \p parse. The enumeration may yield zero, one or more abstract syntax
+ * trees, depending on whether the parse was unsuccesful, unambiguously
+ * succesful, or ambiguously successful.
+ */
+
+
+/** @} */
+
+#endif // PGF_PARSER_H_