Document the new parser, provide an example.

diff --git a/doc/examples/Makefile.am b/doc/examples/Makefile.am
index ef8d4d1421ad57b38b27b84691df47ccf4f3eee0..2a5a10888d18e5cc97374c409f34fe16c60d8674 100644 (file)
--- a/doc/examples/Makefile.am
+++ b/doc/examples/Makefile.am
@@ -1,7 +1,7 @@
 ## Process this file with automake to produce Makefile.in
 
 EXFILES = archive1.cpp compile1.cpp compile2.cpp compile3.cpp lanczos.cpp \
 ## Process this file with automake to produce Makefile.in
 
 EXFILES = archive1.cpp compile1.cpp compile2.cpp compile3.cpp lanczos.cpp \

- mystring.cpp
+ mystring.cpp derivative.cpp

 
 TEXI = ginac-examples.texi
 
 
 TEXI = ginac-examples.texi
 

diff --git a/doc/examples/derivative.cpp b/doc/examples/derivative.cpp
new file mode 100644 (file)
index 0000000..c1a09b9
--- /dev/null
+++ b/doc/examples/derivative.cpp
@@ -0,0 +1,30 @@
+// Input expression containing variable 'x' and compute its derivative
+// with respect to 'x'.
+// Example from the tutorial (chapter Input/Output, section `Expression
+// input').
+#include <iostream>
+#include <string>
+#include <stdexcept>
+#include <ginac/ginac.h>
+using namespace std;
+using namespace GiNaC;
+
+int main()
+{
+       cout << "Enter an expression containing 'x': " << flush;
+       parser reader;
+
+       try {
+               ex e = reader(cin);
+               symtab table = reader.get_syms();
+
+               symbol x = table.find("x") != table.end() ? 
+                          ex_to<symbol>(table["x"]) : symbol("x");
+
+               cout << "The derivative of " << e << " with respect to x is ";
+               cout << e.diff(x) << "." << endl;
+       } catch (exception &p) {
+               cerr << p.what() << endl;
+       }
+}
+

diff --git a/doc/examples/ginac-examples.texi b/doc/examples/ginac-examples.texi
index 8870dafb84a8fde391a5937067176b602774f84a..2a109daa4c25496d559fb4d61913de88e1462b9f 100644 (file)
--- a/doc/examples/ginac-examples.texi
+++ b/doc/examples/ginac-examples.texi
@@ -30,6 +30,13 @@ This is a collection of code examples using GiNaC.
 
 Two expression are stored in an archive on the disk and are restored again.
 
 
 Two expression are stored in an archive on the disk and are restored again.
 

+@section Input and output of expressions
+
+@subsection Expression input @uref{derivative.cpp, (source)}
+
+Interactively input expression and compute its derivative with respect
+to the ``x'' variable.
+

 @chapter Monte Carlo Integration
 
 @section Example showing compile_ex @uref{compile1.cpp, (source)}
 @chapter Monte Carlo Integration
 
 @section Example showing compile_ex @uref{compile1.cpp, (source)}

diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi
index 7254406289eca0b84d70307c1c5d49df8fc8a289..e17d4dfa8f4f59e974bcb0645bfff81f19e00b94 100644 (file)
--- a/doc/tutorial/ginac.texi
+++ b/doc/tutorial/ginac.texi
@@ -6380,22 +6380,72 @@ and have the @samp{x} and @samp{y} correspond to the symbols @code{x} and
 @code{y} you defined in your program and there is no way to specify the
 desired symbols to the @code{>>} stream input operator.
 
 @code{y} you defined in your program and there is no way to specify the
 desired symbols to the @code{>>} stream input operator.
 

-Instead, GiNaC lets you construct an expression from a string, specifying the
-list of symbols to be used:
+Instead, GiNaC lets you read an expression from a stream or a string,
+specifying the mapping between the input strings and symbols to be used:

 
 @example
 @{
 
 @example
 @{

-    symbol x("x"), y("y");
-    ex e("2*x+sin(y)", lst(x, y));
+    symbol x, y;
+    symtab table;
+    table["x"] = x;
+    table["y"] = y;
+    parser reader(table);
+    ex e = reader("2*x+sin(y)");

 @}
 @end example
 
 The input syntax is the same as that used by @command{ginsh} and the stream
 @}
 @end example
 
 The input syntax is the same as that used by @command{ginsh} and the stream

-output operator @code{<<}. The symbols in the string are matched by name to
-the symbols in the list and if GiNaC encounters a symbol not specified in
-the list it will throw an exception.
+output operator @code{<<}. Matching between the input strings and expressions
+is given by @samp{table}. The @samp{table} in this example instructs GiNaC
+to substitute any input substring ``x'' with symbol @code{x}. Likewise,
+the substring ``y'' will be replaced with symbol @code{y}. It's also possible
+to map input (sub)strings to arbitrary expressions:

 
 

-With this constructor, it's also easy to implement interactive GiNaC programs:
+@example
+@{
+    symbol x, y;
+    symtab table;
+    table["x"] = x+log(y)+1;
+    parser reader(table);
+    ex e = reader("5*x^3 - x^2");
+    // e = 5*(x+log(y)+1)^3 + (x+log(y)+1)^2
+@}
+@end example
+
+If no mapping is specified for a particular string GiNaC will create a symbol
+with corresponding name. Later on you can obtain all parser generated symbols
+with @code{get_syms()} method:
+
+@example
+@{
+    parser reader;
+    ex e = reader("2*x+sin(y)");
+    symtab table = reader.get_syms();
+    symbol x = reader["x"];
+    symbol y = reader["y"];
+@}
+@end example
+
+Sometimes you might want to prevent GiNaC from inserting these extra symbols
+(for example, you want treat an unexpected string in the input as an error).
+
+@example
+@{
+       symtab table;
+       table["x"] = symbol();
+       parser reader(table);
+       parser.strict = true;
+       ex e;
+       try @{
+               e = reader("2*x+sin(y)");
+       @} catch (parse_error& err) @{
+               cerr << err.what() << endl;
+               // prints "unknown symbol "y" in the input"
+       @}
+@}
+@end example
+
+With this parser, it's also easy to implement interactive GiNaC programs:

 
 @example
 #include <iostream>
 
 @example
 #include <iostream>


@@ -6407,19 +6457,19 @@ using namespace GiNaC;
 
 int main()
 @{
 
 int main()
 @{

-    symbol x("x");
-    string s;
-
-    cout << "Enter an expression containing 'x': ";
-    getline(cin, s);
-
-    try @{
-        ex e(s, lst(x));
-        cout << "The derivative of " << e << " with respect to x is ";
-        cout << e.diff(x) << ".\n";
-    @} catch (exception &p) @{
-        cerr << p.what() << endl;
-    @}
+       cout << "Enter an expression containing 'x': " << flush;
+       parser reader;
+
+       try @{
+               ex e = reader(cin);
+               symtab table = reader.get_syms();
+               symbol x = table.find("x") != table.end() ? 
+                          ex_to<symbol>(table["x"]) : symbol("x");
+               cout << "The derivative of " << e << " with respect to x is ";
+               cout << e.diff(x) << "." << endl;
+       @} catch (exception &p) @{
+               cerr << p.what() << endl;
+       @}

 @}
 @end example
 
 @}
 @end example