GraceTMPL::Save Class Reference

Container for a number of graphs to be saved in a xmgrace compatible file format. More...

#include <gracetmpl.h>

Inheritance diagram for GraceTMPL::Save:

List of all members.

Public Member Functions
	Save ()
	Default constructor. Does nothing special.
virtual	~Save ()
	Destructor. Cleans up things.
virtual Graph *	newGraph (int logplot=0)
	Create and store a new Graph within this object.
int	isCopydata (int g, int s)
	Used to query if a certain dataset should be copied from another.
Data *	copydata (int g, int s)
	Used to query the source set of a set copy operation.
void	regCopydata (int g, int s, Data *src)
	Used to set a reference to a dataset copy source.
void	clearCopydata ()
	Used to clear all references to dataset copy sources.
virtual Graph *	graph (int i)
	Returns the number of stored graphs.
virtual int	graphs ()
	Returns the number of stored graphs.
void	setOutputName (const std::string &name)
	Set the template for the output filename.
void	enablePipe (int i)
	Enables writing output data to a pipe.
int	pipeEnabled ()
	Query the state of pipe handling.
virtual int	loadTemplate (const char *filename, int useS0=0)
	Load an xmgrace file as template.
virtual String2Vec	templateDataRequestInfo ()
	Query information about datasets the template requests.
virtual void	save ()
	Save all graphs to at least one file, optionally using a template.
Protected Types
typedef std::map< int, CopySrc >	CopyMap
	convenience type definition
typedef std::map< int, CopyMap >	Copy2Map
	convenience type definition
Protected Attributes
Template	tmpl_
	Used to store template data.
std::vector< Graph * >	graphsVec_
StringStringMap	docEnvs_
StringMap	myEnv_
std::string	nameTmpl_
int	allowPipe_

---

Detailed Description

Container for a number of graphs to be saved in a xmgrace compatible file format.

For saving the data, an existing xmgrace file can be used as a template by calling loadTemplate(templatename)

So what happens in a typical livecycle of GraceTMPL usage?

• The application creates a new GraceTMPL::Save object.
• Using GraceTMPL::Save::loadTemplate it then loads a gracefile. Anything found in the template which cannot be associated with a certain graph or set is saved as a string and preserved for later, when the output files are produced. Anything regarding a graph or set is stored in special data structures. And by the way, all goes into GraceTMPL::Save::Template. Also, the doubly indexed vector request_ is built which can be queried using templateDataRequestInfo().
• At this time, GraceTMPL knows how many graphs fit on each page (or go to each file, resp.) and how many datasets each graph in the template contains. The latter information is of a certain 'diffuse' significance. On one hand side, a graph can take any number of graphs. Literal data will always be contained in the graph. Data stored by the application will be formatted like the associated dataset in the template. If more data is stored than datasets where contained in the template, the data will be formatted in some nonpredictable way (i.e. however grace should decide).
• Now the application creates a number of graphs and stores datasets therein. How this is done, in a way depends on the purpose of the template.
  • If the Template requests certain data via "$=DATA" or "$'DATA" the application will want to analyze whatever a call to templateDataRequestInfo() returns. Creating one graph after the other it will produce datasets as requested by the template and store them within the graphs.
  • Another approach is to just create one graph after the other, happily storing any kind and count of datasets within the graphs and trust that the template is properly formatted to handle the data. Upon creation, a graph is already assigned with a name, namely "gX", with X being the graph number.
• The application can set any amount of name/value pairs within the GraceTMPL::Save object, each of the graphs and any of the datasets, as need may call for.
• When all is done, the application may call GraceTMPL::Save::save() This will trigger the following actions:
  • By expanding the filename template the name for the first output file is generated. If the resulting filename starts with pipe symbol ("|") and enablePipe(true) was set, it will be interpreted as a process not a file and the output data will be sent to the process. Note this is a security risk, so by default pipe handling is disabled.
  • To each graph in the template a graph as created by the application is associated by a call to saveprep. At this point, all sets contained in a graph get a name "sX" with X being the set number.
  • Now the output data is created. The common stuff is written as taken from the template. Then, for each graph and set the formatting stiff is written. Any string possibly containing a variable (e.g. legend strings, axis labels, titles, strings, etc.) is expanded properly. After that part, all data is written to the output and the pipe or file is closed.
  • If any graphs are yet unhandled, the saver will increase the page number and repeat this procedure.

---

Member Function Documentation

void GraceTMPL::Save::clearCopydata (   )

Used to clear all references to dataset copy sources. Used internally only.

Data* GraceTMPL::Save::copydata (  int  g, int  s )  [inline]

Used to query the source set of a set copy operation. Used internally only by Graph::savedata()

void GraceTMPL::Save::enablePipe (  int  i  )  [inline]

Enables writing output data to a pipe. If output to a pipe is enables and the outputname set with setOutputName() starts with a '|' symbol, the rest of the outputname will be interpreted as a process to which a pipe is opened and the outputdata is written. This might not work as expected if only works if no template has been loaded. For this case, pipe support might be disabled in the future Todo: Decide upon pipe policy in case of missing template.

int GraceTMPL::Save::isCopydata (  int  g, int  s )

Used to query if a certain dataset should be copied from another. Used internally only by Graph::saveprep

virtual int GraceTMPL::Save::loadTemplate (  const char *  filename, int  useS0 = 0 )  [virtual]

Load an xmgrace file as template. In the template file, environment variables can be used in a way of writing '$NAME' of ${NAME} with NAME consisting of alphanumerical characters and the underscore ('_'). This will be replaced by the string related to NAME. An environment variable can be set by calling setenv(). Any environment variable belonging to a certain graph is exported to the sheet using a naming style of ${GRAPH::NAME} with GRAPH denoting the graph name (e.g. "g0", "g1", etc.). Note this naming style explicitly requires the brackets "{}". Additionally, the might be an arbitrary number of parameters related to a graph. To specify the positions of these parameters (if they should be printed at all) the template can contain string objects of the form "PARAMg0:1" where g0 stands for graph "g0" and 1 stands for set number 1 withing that graph. If any, at least two strings per graph should be present, namely "PARAMg0:0" and "PARAMg0:1" for graph 0, "PARAMg1:0" and "PARAMg1:1" for graph 1 and so on. The positions of the last two strings of this kind will be used to interpolate the positions of further strings, so there should be enough space to hold the expected number of strings. See also: setenv(), save()

void GraceTMPL::Save::regCopydata (  int  g, int  s, Data *  src )

Used to set a reference to a dataset copy source. Used internally only by Graph::saveprep()

virtual void GraceTMPL::Save::save (   )  [virtual]

Save all graphs to at least one file, optionally using a template. If no template was loaded with loadTemplate(), each graph will result in one datafile wich can be imported into an xmgrace-graph as ascii data. In case a template was successfully loaded, it will be used to store as many graphs in a file as specified in the template. The resulting files can be loaded by the same xmgrace version used to generate the template file. For notes on templates, see loadTemplate(). On saving, the environment variable '$p' will be expanded to the file number currently written, while '$pz' is this same number formatted with enough leading zeros to give a fixed-length string for all written files. To generate outputfilenames which can be sorted in ascending order, include "$pz" in your filename-template (see setOutputName()). '$P' will expand to the number of outputfiles necessary to save all graphs.

void GraceTMPL::Save::setOutputName (  const std::string &  name  )  [inline]

Set the template for the output filename. The accessible environment for the output template is the same as for the whole file plus the environment of the first graph in the file. See also: save()

virtual String2Vec GraceTMPL::Save::templateDataRequestInfo (   )  [virtual]

Query information about datasets the template requests. In each of the graphs defined within the template, the contained sets can request the program using GraceTMPL to supply certain kind of data for the according set. This is done by adding a file/data specifier to the legendstring. A specifier starts with $' for sets which should keep their name from the legend entry and with $= for sets which get their name from the application. This is followed by a string of arbitrary length which is actually passed to the application when it calls this function. The result will be a 2-dimensional string vec with the first index being the graph number and the second index the setnumber within that graph. The setnumber must not necessarily represent the S* number as known from XmGrace - literal data sets will be missing as they can not be changed anyway.

---

Member Data Documentation

int GraceTMPL::Save::allowPipe_ [protected]

Used to set flag if opening a pipe for output is allowed

StringStringMap GraceTMPL::Save::docEnvs_ [protected]

Used to store the output file's environment

std::vector<Graph*> GraceTMPL::Save::graphsVec_ [protected]

Used to store all graphs

StringMap GraceTMPL::Save::myEnv_ [protected]

Used to store the environment specific to the saver

std::string GraceTMPL::Save::nameTmpl_ [protected]

Used to store the filename template

Template GraceTMPL::Save::tmpl_ [protected]

Used to store template data. Todo: More than one template for more than one output file? Probably not!

---

The documentation for this class was generated from the following file:

• gracetmpl.h

---