ginac/parser/parse_context.h

   1 /** @file parse_context.h
   2  *
   3  *  Interface to parser context. */
   4
   5 /*
   6  *  GiNaC Copyright (C) 1999-2024 Johannes Gutenberg University Mainz, Germany
   7  *
   8  *  This program is free software; you can redistribute it and/or modify
   9  *  it under the terms of the GNU General Public License as published by
  10  *  the Free Software Foundation; either version 2 of the License, or
  11  *  (at your option) any later version.
  12  *
  13  *  This program is distributed in the hope that it will be useful,
  14  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  *  GNU General Public License for more details.
  17  *
  18  *  You should have received a copy of the GNU General Public License
  19  *  along with this program; if not, write to the Free Software
  20  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  21  */
  22
  23 #ifndef GINAC_PARSE_CONTEXT_H
  24 #define GINAC_PARSE_CONTEXT_H
  25
  26 #include "ex.h"
  27 #include "symbol.h"
  28
  29 #include <cstddef> // for size_t
  30 #include <map>
  31 #include <string>
  32 #include <utility>
  33
  34 namespace GiNaC {
  35
  36 /**
  37  * Establishes correspondence between the strings and expressions.
  38  * The parser will create missing symbols (if not instructed otherwise,
  39  * in which case it fails if the expression contains unknown symbols).
  40  */
  41 typedef std::map<std::string, ex> symtab;
  42
  43 /**
  44  * Find the symbol (or abbreviation) with the @a name in the symbol table @a syms.
  45  *
  46  * If symbol is missing and @a strict = false, insert it, otherwise
  47  * throw an exception.
  48  */
  49 extern ex
  50 find_or_insert_symbol(const std::string& name, symtab& syms,
  51                       const bool strict);
  52
  53 /**
  54  * Function (or class ctor) prototype
  55  * .first is  the name of function(or ctor),
  56  * .second is the number of arguments (each of type ex)
  57  */
  58 typedef std::pair<std::string, std::size_t> prototype;
  59
  60 /**
  61  * A (C++) function for reading functions and classes from the stream.
  62  *
  63  * The parser uses (an associative array of) such functions to construct
  64  * (GiNaC) classes and functions from a sequence of characters.
  65  */
  66 class reader_func {
  67         enum { FUNCTION_PTR, GINAC_FUNCTION };
  68 public:
  69         reader_func(ex (*func_)(const exvector& args))
  70                 : type(FUNCTION_PTR), serial(0), func(func_) {}
  71         reader_func(unsigned serial_)
  72                 : type(GINAC_FUNCTION), serial(serial_), func(nullptr) {}
  73         ex operator()(const exvector& args) const;
  74 private:
  75         unsigned type;
  76         unsigned serial;
  77         ex (*func)(const exvector& args);
  78 };
  79
  80
  81
  82 /**
  83  * Prototype table.
  84  *
  85  * If parser sees an expression which looks like a function call (e.g.
  86  * foo(x+y, z^2, t)), it looks up such a table to find out which
  87  * function (or class) corresponds to the given name and has the given
  88  * number of the arguments.
  89  *
  90  * N.B.
  91  *
  92  * 1. The function don't have to return a (GiNaC) function or class, it
  93  *    can return any expression.
  94  * 2. Overloaded functions/ctors are paritally supported, i.e. there might
  95  *    be several functions with the same name, but they should take different
  96  *    number of arguments.
  97  * 3. User can extend the parser via custom prototype tables. It's possible
  98  *    to read user defined classes, create abbreviations, etc.
  99  *
 100  * NOTE: due to a hack that allows user defined functions to be parsed, the map
 101  *       value of type reader_func is internally treated as an unsigned and not as a
 102  *       function pointer!! The unsigned has to correspond to the serial number of
 103  *       the defined GiNaC function.
 104  */
 105 class PrototypeLess
 106 {
 107 public:
 108         bool operator()(const prototype& p1, const prototype& p2) const
 109         {
 110                 int s = p1.first.compare(p2.first);
 111                 if (s == 0) {
 112                         if ((p1.second == 0) || (p2.second == 0)) return false;
 113                         return p1.second < p2.second;
 114                 }
 115                 return s < 0;
 116         }
 117 };
 118 typedef std::map<prototype, reader_func, PrototypeLess> prototype_table;
 119
 120 /**
 121  * Default prototype table.
 122  *
 123  * It supports all defined GiNaC functions and "pow", "sqrt", and "power".
 124  */
 125 extern const prototype_table& get_default_reader();
 126 /**
 127  * Builtin prototype table.
 128  *
 129  * It supports only the builtin GiNaC functions and "pow", "sqrt", and "power".
 130  */
 131 extern const prototype_table& get_builtin_reader();
 132
 133 } // namespace GiNaC
 134
 135 #endif // GINAC_PARSE_CONTEXT_H