+ // ...
+ archive a2;
+ ifstream in("foobar.gar");
+ in >> a2;
+ // ...
+@end example
+
+And the stored expressions can be retrieved by their name:
+
+@example
+ // ...
+ lst syms(x, y);
+
+ ex ex1 = a2.unarchive_ex(syms, "foo");
+ ex ex2 = a2.unarchive_ex(syms, "the second one");
+
+ cout << ex1 << endl; // prints "41+sin(x+2*y)+3*z"
+ cout << ex2 << endl; // prints "42+sin(x+2*y)+3*z"
+ cout << ex1.subs(x == 2) << endl; // prints "41+sin(2+2*y)+3*z"
+@}
+@end example
+
+Note that you have to supply a list of the symbols which are to be inserted
+in the expressions. Symbols in archives are stored by their name only and
+if you don't specify which symbols you have, unarchiving the expression will
+create new symbols with that name. E.g. if you hadn't included @code{x} in
+the @code{syms} list above, the @code{ex1.subs(x == 2)} statement would
+have had no effect because the @code{x} in @code{ex1} would have been a
+different symbol than the @code{x} which was defined at the beginning of
+the program, although both would appear as @samp{x} when printed.
+
+You can also use the information stored in an @code{archive} object to
+output expressions in a format suitable for exact reconstruction. The
+@code{archive} and @code{archive_node} classes have a couple of member
+functions that let you access the stored properties:
+
+@example
+static void my_print2(const archive_node & n)
+@{
+ string class_name;
+ n.find_string("class", class_name);
+ cout << class_name << "(";
+
+ archive_node::propinfovector p;
+ n.get_properties(p);
+
+ size_t num = p.size();
+ for (size_t i=0; i<num; i++) @{
+ const string &name = p[i].name;
+ if (name == "class")
+ continue;
+ cout << name << "=";
+
+ unsigned count = p[i].count;
+ if (count > 1)
+ cout << "@{";
+
+ for (unsigned j=0; j<count; j++) @{
+ switch (p[i].type) @{
+ case archive_node::PTYPE_BOOL: @{
+ bool x;
+ n.find_bool(name, x, j);
+ cout << (x ? "true" : "false");
+ break;
+ @}
+ case archive_node::PTYPE_UNSIGNED: @{
+ unsigned x;
+ n.find_unsigned(name, x, j);
+ cout << x;
+ break;
+ @}
+ case archive_node::PTYPE_STRING: @{
+ string x;
+ n.find_string(name, x, j);
+ cout << '\"' << x << '\"';
+ break;
+ @}
+ case archive_node::PTYPE_NODE: @{
+ const archive_node &x = n.find_ex_node(name, j);
+ my_print2(x);
+ break;
+ @}
+ @}
+
+ if (j != count-1)
+ cout << ",";
+ @}
+
+ if (count > 1)
+ cout << "@}";
+
+ if (i != num-1)
+ cout << ",";
+ @}
+
+ cout << ")";
+@}
+
+int main()
+@{
+ ex e = pow(2, x) - y;
+ archive ar(e, "e");
+ my_print2(ar.get_top_node(0)); cout << endl;
+ return 0;
+@}
+@end example
+
+This will produce:
+
+@example
+add(rest=@{power(basis=numeric(number="2"),exponent=symbol(name="x")),
+symbol(name="y")@},coeff=@{numeric(number="1"),numeric(number="-1")@},
+overall_coeff=numeric(number="0"))
+@end example
+
+Be warned, however, that the set of properties and their meaning for each
+class may change between GiNaC versions.
+
+
+@node Extending GiNaC, What does not belong into GiNaC, Input/Output, Top
+@c node-name, next, previous, up
+@chapter Extending GiNaC
+
+By reading so far you should have gotten a fairly good understanding of
+GiNaC's design-patterns. From here on you should start reading the
+sources. All we can do now is issue some recommendations how to tackle
+GiNaC's many loose ends in order to fulfill everybody's dreams. If you
+develop some useful extension please don't hesitate to contact the GiNaC
+authors---they will happily incorporate them into future versions.
+
+@menu
+* What does not belong into GiNaC:: What to avoid.
+* Symbolic functions:: Implementing symbolic functions.
+* Structures:: Defining new algebraic classes (the easy way).
+* Adding classes:: Defining new algebraic classes (the hard way).
+@end menu
+
+
+@node What does not belong into GiNaC, Symbolic functions, Extending GiNaC, Extending GiNaC
+@c node-name, next, previous, up
+@section What doesn't belong into GiNaC
+
+@cindex @command{ginsh}
+First of all, GiNaC's name must be read literally. It is designed to be
+a library for use within C++. The tiny @command{ginsh} accompanying
+GiNaC makes this even more clear: it doesn't even attempt to provide a
+language. There are no loops or conditional expressions in
+@command{ginsh}, it is merely a window into the library for the
+programmer to test stuff (or to show off). Still, the design of a
+complete CAS with a language of its own, graphical capabilities and all
+this on top of GiNaC is possible and is without doubt a nice project for
+the future.
+
+There are many built-in functions in GiNaC that do not know how to
+evaluate themselves numerically to a precision declared at runtime
+(using @code{Digits}). Some may be evaluated at certain points, but not
+generally. This ought to be fixed. However, doing numerical
+computations with GiNaC's quite abstract classes is doomed to be
+inefficient. For this purpose, the underlying foundation classes
+provided by CLN are much better suited.
+
+
+@node Symbolic functions, Structures, What does not belong into GiNaC, Extending GiNaC
+@c node-name, next, previous, up
+@section Symbolic functions
+
+The easiest and most instructive way to start extending GiNaC is probably to
+create your own symbolic functions. These are implemented with the help of
+two preprocessor macros:
+
+@cindex @code{DECLARE_FUNCTION}
+@cindex @code{REGISTER_FUNCTION}
+@example
+DECLARE_FUNCTION_<n>P(<name>)
+REGISTER_FUNCTION(<name>, <options>)
+@end example
+
+The @code{DECLARE_FUNCTION} macro will usually appear in a header file. It
+declares a C++ function with the given @samp{name} that takes exactly @samp{n}
+parameters of type @code{ex} and returns a newly constructed GiNaC
+@code{function} object that represents your function.
+
+The @code{REGISTER_FUNCTION} macro implements the function. It must be passed
+the same @samp{name} as the respective @code{DECLARE_FUNCTION} macro, and a
+set of options that associate the symbolic function with C++ functions you
+provide to implement the various methods such as evaluation, derivative,
+series expansion etc. They also describe additional attributes the function
+might have, such as symmetry and commutation properties, and a name for
+LaTeX output. Multiple options are separated by the member access operator
+@samp{.} and can be given in an arbitrary order.
+
+(By the way: in case you are worrying about all the macros above we can
+assure you that functions are GiNaC's most macro-intense classes. We have
+done our best to avoid macros where we can.)
+
+@subsection A minimal example
+
+Here is an example for the implementation of a function with two arguments
+that is not further evaluated:
+
+@example
+DECLARE_FUNCTION_2P(myfcn)
+
+static ex myfcn_eval(const ex & x, const ex & y)
+@{
+ return myfcn(x, y).hold();
+@}
+
+REGISTER_FUNCTION(myfcn, eval_func(myfcn_eval))
+@end example
+
+Any code that has seen the @code{DECLARE_FUNCTION} line can use @code{myfcn()}
+in algebraic expressions:
+
+@example
+@{
+ ...
+ symbol x("x");
+ ex e = 2*myfcn(42, 3*x+1) - x;
+ // this calls myfcn_eval(42, 3*x+1), and inserts its return value into
+ // the actual expression
+ cout << e << endl;
+ // prints '2*myfcn(42,1+3*x)-x'
+ ...
+@}
+@end example
+
+@cindex @code{hold()}
+@cindex evaluation
+The @code{eval_func()} option specifies the C++ function that implements
+the @code{eval()} method, GiNaC's anonymous evaluator. This function takes
+the same number of arguments as the associated symbolic function (two in this
+case) and returns the (possibly transformed or in some way simplified)
+symbolically evaluated function (@xref{Automatic evaluation}, for a description
+of the automatic evaluation process). If no (further) evaluation is to take
+place, the @code{eval_func()} function must return the original function
+with @code{.hold()}, to avoid a potential infinite recursion. If your
+symbolic functions produce a segmentation fault or stack overflow when
+using them in expressions, you are probably missing a @code{.hold()}
+somewhere.
+
+There is not much you can do with the @code{myfcn} function. It merely acts
+as a kind of container for its arguments (which is, however, sometimes
+perfectly sufficient). Let's have a look at the implementation of GiNaC's
+cosine function.
+
+@subsection The cosine function
+
+The GiNaC header file @file{inifcns.h} contains the line
+
+@example
+DECLARE_FUNCTION_1P(cos)
+@end example
+
+which declares to all programs using GiNaC that there is a function @samp{cos}
+that takes one @code{ex} as an argument. This is all they need to know to use
+this function in expressions.
+
+The implementation of the cosine function is in @file{inifcns_trans.cpp}. The
+@code{eval_func()} function looks something like this (actually, it doesn't
+look like this at all, but it should give you an idea what is going on):
+
+@example
+static ex cos_eval(const ex & x)
+@{
+ if (<x is a multiple of 2*Pi>)
+ return 1;
+ else if (<x is a multiple of Pi>)
+ return -1;
+ else if (<x is a multiple of Pi/2>)
+ return 0;
+ // more rules...
+
+ else if (<x has the form 'acos(y)'>)
+ return y;
+ else if (<x has the form 'asin(y)'>)
+ return sqrt(1-y^2);
+ // more rules...
+
+ else
+ return cos(x).hold();
+@}
+@end example
+
+In this way, @code{cos(4*Pi)} automatically becomes @math{1},
+@code{cos(asin(a+b))} becomes @code{sqrt(1-(a+b)^2)}, etc. If no reasonable
+symbolic transformation can be done, the unmodified function is returned
+with @code{.hold()}.
+
+GiNaC doesn't automatically transform @code{cos(2)} to @samp{-0.416146...}.
+The user has to call @code{evalf()} for that. This is implemented in a
+different function:
+
+@example
+static ex cos_evalf(const ex & x)
+@{
+ if (is_a<numeric>(x))
+ return cos(ex_to<numeric>(x));
+ else
+ return cos(x).hold();
+@}
+@end example
+
+Since we are lazy we defer the problem of numeric evaluation to somebody else,
+in this case the @code{cos()} function for @code{numeric} objects, which in
+turn hands it over to the @code{cos()} function in CLN. The @code{.hold()}
+isn't really needed here, but reminds us that the corresponding @code{eval()}
+function would require it in this place.
+
+Differentiation will surely turn up and so we need to tell @code{cos}
+what its first derivative is (higher derivatives, @code{.diff(x,3)} for
+instance, are then handled automatically by @code{basic::diff} and
+@code{ex::diff}):
+
+@example
+static ex cos_deriv(const ex & x, unsigned diff_param)
+@{
+ return -sin(x);
+@}
+@end example
+
+@cindex product rule
+The second parameter is obligatory but uninteresting at this point. It
+specifies which parameter to differentiate in a partial derivative in
+case the function has more than one parameter, and its main application
+is for correct handling of the chain rule.
+
+An implementation of the series expansion is not needed for @code{cos()} as
+it doesn't have any poles and GiNaC can do Taylor expansion by itself (as
+long as it knows what the derivative of @code{cos()} is). @code{tan()}, on
+the other hand, does have poles and may need to do Laurent expansion:
+
+@example
+static ex tan_series(const ex & x, const relational & rel,
+ int order, unsigned options)
+@{
+ // Find the actual expansion point
+ const ex x_pt = x.subs(rel);
+
+ if (<x_pt is not an odd multiple of Pi/2>)
+ throw do_taylor(); // tell function::series() to do Taylor expansion
+
+ // On a pole, expand sin()/cos()
+ return (sin(x)/cos(x)).series(rel, order+2, options);
+@}
+@end example
+
+The @code{series()} implementation of a function @emph{must} return a
+@code{pseries} object, otherwise your code will crash.
+
+Now that all the ingredients have been set up, the @code{REGISTER_FUNCTION}
+macro is used to tell the system how the @code{cos()} function behaves:
+
+@example
+REGISTER_FUNCTION(cos, eval_func(cos_eval).
+ evalf_func(cos_evalf).
+ derivative_func(cos_deriv).
+ latex_name("\\cos"));
+@end example
+
+This registers the @code{cos_eval()}, @code{cos_evalf()} and
+@code{cos_deriv()} C++ functions with the @code{cos()} function, and also
+gives it a proper LaTeX name.
+
+@subsection Function options
+
+GiNaC functions understand several more options which are always
+specified as @code{.option(params)}. None of them are required, but you
+need to specify at least one option to @code{REGISTER_FUNCTION()} (usually
+the @code{eval()} method).
+
+@example
+eval_func(<C++ function>)
+evalf_func(<C++ function>)
+derivative_func(<C++ function>)
+series_func(<C++ function>)
+@end example
+
+These specify the C++ functions that implement symbolic evaluation,
+numeric evaluation, partial derivatives, and series expansion, respectively.
+They correspond to the GiNaC methods @code{eval()}, @code{evalf()},
+@code{diff()} and @code{series()}.
+
+The @code{eval_func()} function needs to use @code{.hold()} if no further
+automatic evaluation is desired or possible.
+
+If no @code{series_func()} is given, GiNaC defaults to simple Taylor
+expansion, which is correct if there are no poles involved. If the function
+has poles in the complex plane, the @code{series_func()} needs to check
+whether the expansion point is on a pole and fall back to Taylor expansion
+if it isn't. Otherwise, the pole usually needs to be regularized by some
+suitable transformation.
+
+@example
+latex_name(const string & n)
+@end example
+
+specifies the LaTeX code that represents the name of the function in LaTeX
+output. The default is to put the function name in an @code{\mbox@{@}}.
+
+@example
+do_not_evalf_params()
+@end example
+
+This tells @code{evalf()} to not recursively evaluate the parameters of the
+function before calling the @code{evalf_func()}.
+
+@example
+set_return_type(unsigned return_type, unsigned return_type_tinfo)
+@end example
+
+This allows you to explicitly specify the commutation properties of the
+function (@xref{Non-commutative objects}, for an explanation of
+(non)commutativity in GiNaC). For example, you can use
+@code{set_return_type(return_types::noncommutative, TINFO_matrix)} to make
+GiNaC treat your function like a matrix. By default, functions inherit the
+commutation properties of their first argument.
+
+@example
+set_symmetry(const symmetry & s)
+@end example
+
+specifies the symmetry properties of the function with respect to its
+arguments. @xref{Indexed objects}, for an explanation of symmetry
+specifications. GiNaC will automatically rearrange the arguments of
+symmetric functions into a canonical order.
+
+
+@node Structures, Adding classes, Symbolic functions, Extending GiNaC
+@c node-name, next, previous, up
+@section Structures
+
+If you are doing some very specialized things with GiNaC, or if you just
+need some more organized way to store data in your expressions instead of
+anonymous lists, you may want to implement your own algebraic classes.
+('algebraic class' means any class directly or indirectly derived from
+@code{basic} that can be used in GiNaC expressions).
+
+GiNaC offers two ways of accomplishing this: either by using the
+@code{structure<T>} template class, or by rolling your own class from
+scratch. This section will discuss the @code{structure<T>} template which
+is easier to use but more limited, while the implementation of custom
+GiNaC classes is the topic of the next section. However, you may want to
+read both sections because many common concepts and member functions are
+shared by both concepts, and it will also allow you to decide which approach
+is most suited to your needs.
+
+The @code{structure<T>} template, defined in the GiNaC header file
+@file{structure.h}, wraps a type that you supply (usually a C++ @code{struct}
+or @code{class}) into a GiNaC object that can be used in expressions.
+
+@subsection Example: scalar products
+
+Let's suppose that we need a way to handle some kind of abstract scalar
+product of the form @samp{<x|y>} in expressions. Objects of the scalar
+product class have to store their left and right operands, which can in turn
+be arbitrary expressions. Here is a possible way to represent such a
+product in a C++ @code{struct}:
+
+@example
+#include <iostream>
+using namespace std;
+
+#include <ginac/ginac.h>
+using namespace GiNaC;
+
+struct sprod_s @{
+ ex left, right;
+
+ sprod_s() @{@}
+ sprod_s(ex l, ex r) : left(l), right(r) @{@}
+@};
+@end example
+
+The default constructor is required. Now, to make a GiNaC class out of this
+data structure, we need only one line:
+
+@example
+typedef structure<sprod_s> sprod;
+@end example
+
+That's it. This line constructs an algebraic class @code{sprod} which
+contains objects of type @code{sprod_s}. We can now use @code{sprod} in
+expressions like any other GiNaC class:
+
+@example
+...
+ symbol a("a"), b("b");
+ ex e = sprod(sprod_s(a, b));
+...