parser: map input strings onto arbitrary expressions (not only symbols).
[ginac.git] / ginac / parser / parse_context.hpp
1 #ifndef _GINAC_PARSE_CONTEXT_HPP
2 #define _GINAC_PARSE_CONTEXT_HPP
3 #include <string>
4 #include <cstddef> // size_t
5 #include "ex.h"
6 #include "symbol.h"
7 #include <map>
8 #include <utility>
9
10 namespace GiNaC
11 {
12
13 /**
14  * Establishes correspondence between the strings and expressions.
15  * The parser will create missing symbols (if not instructed otherwise,
16  * in which case it fails if the expression contains unknown symbols).
17  */
18 typedef std::map<std::string, ex> symtab;
19
20 /**
21  * Find the symbol with the @a name in the symbol table @a syms.
22  *
23  * If symbol is missing and @a strict = false, insert it, otherwise
24  * throw an exception.
25  */
26 extern symbol
27 find_or_insert_symbol(const std::string& name, symtab& syms,
28                       const bool strict);
29
30 /**
31  * Function (or class ctor) prototype
32  * .first is  the name of function(or ctor),
33  * .second is the number of arguments (each of type ex)
34  */
35 typedef std::pair<std::string, std::size_t> prototype;
36
37 /**
38  * A (C++) function for reading functions and classes from the stream.
39  *
40  * The parser uses (an associative array of) such functions to construct
41  * (GiNaC) classes and functions from a sequence of characters.
42  */
43 typedef ex (*reader_func)(const exvector& args);
44
45 /**
46  * Prototype table.
47  *
48  * If parser sees an expression which looks like a function call (e.g.
49  * foo(x+y, z^2, t)), it looks up such a table to find out which
50  * function (or class) corresponds to the given name and has the given
51  * number of the arguments.
52  *
53  * N.B.
54  *
55  * 1. The function don't have to return a (GiNaC) function or class, it
56  *    can return any expression.
57  * 2. Overloaded functions/ctors are paritally supported, i.e. there might
58  *    be several functions with the same name, but they should take different
59  *    number of arguments.
60  * 3. User can extend the parser via custom prototype tables. It's possible
61  *    to read user defined classes, create abbreviations, etc.
62  */
63 typedef std::map<prototype, reader_func> prototype_table;
64
65 /**
66  * Default prototype table.
67  *
68  * It supports most of builtin GiNaC functions.
69  */
70 extern const prototype_table& get_default_reader();
71
72 }
73
74 #endif // _GINAC_PARSE_CONTEXT_HPP
75