README and docs update

Author: tklip

README.md

@@ -89,8 +89,8 @@ Click on the type name in the following list to see more detailed documentation
 - [`forest::tree`](docs/forest_tree.md) - a tree extracted from a graph
 - [`tgf`](docs/tgf.md) - Tau Grammar Form parser - reads a grammar in TGF format from a string or a file. An alternative way to describe a grammar instead of creating it programatically.
 - [`traverser`](docs/traverser.md) - struct for traversing and accessing rewriter trees
-- rewriting - API for rewriting a resulting parse tree
-- measure - simple struct for measuring time
+- [`rewriting`](docs/rewriting.md) - API for rewriting a resulting parse tree
+- [`measure`](docs/measure.md) - simple struct for measuring time
 
 ### Classes and structs usable for building command line interfaces
 
@@ -108,21 +108,18 @@ There are several areas covered by functions provided by this library
 - [devhelpers](docs/devhelpers.md) - helper forest transformations to various formats (TML facts, TML rules, DOT) useful when developing a parser
 
 
-<a name="tau-grammar-form"></a>
-
 ## TGF - Tau Grammar Form
 
 TGF is an EBNF-based form to describe grammars. Specification of the form can be found on page [`Tau Grammar Form`](docs/tau_grammar_form.md)
 
 
-<a name="tgf-tool"></a>
-
 ## TGF tool
 
 This library comes with a CLI executable `tgf` which features viewing, testing and debugging grammars written in TGF and it can also generate a C++ code from TGF grammar which is then usable in a C++ project.
 
 More detailed information about this CLI can be found on page [`TGF tool`](docs/tgf_tool.md)
 
+
 ## Tutorials
 
 ### CSV parser

docs/forest.md

@@ -1,4 +1,4 @@
-[back to index](../README.md#overview-of-types)
+[back to index](../README.md#classes-and-structs)
 
 # forest
 
@@ -8,18 +8,23 @@ template <typename NodeT> struct forest;
 
 `forest` is a structure which can contain multiple trees. Nodes can have multiple sets of children where more than one set represents splitting of trees meaning the part from root to the node is shared among all trees splitted.
 
-It offers methods for traversal or tree or graph extractions.
+It offers methods counting trees, traversal or tree or graph extractions.
 
-`forest` is a generic structure since the type of nodes is templated.
+`forest` is a generic structure since the type of nodes `NodeT` is templated.
 
 ### parse forest
 
-This library uses `forest` to represent all parse trees parsed from a given input. Each `parser<C, T>::parse(...)` call produces a `forest` with a type `std::pair<lit<C, T>, std::array<size_t, 2>>` where `lit<C, T>` is a parsed literal and the array contains starting and ending position of a literal in an input string.
+This library uses `forest` to represent all parse trees parsed from a given input. Each `parser<C, T>::parse(...)` call produces a `parser<C, T>::result` which contins a parsed forest (accessible with `get_forest()`). Parse nodes uses type (`NodeT`) `std::pair<lit<C, T>, std::array<size_t, 2>>` where `lit<C, T>` is a parsed literal and the array contains position span of a literal in an input string.
+
+`parser` provides type [`pnode`](parser_pnode.md) for used as `NodeT` templated type and type `pforest` for a parse forest:
 
-`parser` declares types `pnode` for a parse node and `pforest` for a parse forest:
 ```
-typedef typename std::pair<lit<C, T>, std::array<size_t, 2>> pnode;
-typedef forest<pnode> pforest;
+class parser {
+	// ...
+public:
+	using pforest forest<pnode>;
+	// ...
+}
 ```
 
 ## constructor
@@ -64,11 +69,6 @@ For a given node `p` sets the new set of subforests with children nodes and retu
 For a given node `p` returns set of subforests with children nodes.
 
 
-### bool is_binarized() const;
-
-Returns true if the forest is binarized, ie. each node has up to 2 children.
-
-
 ### size_t count_trees(const NodeT& p) const;
 
 Counts and returns a number of trees under a `p` node.
@@ -79,6 +79,22 @@ Counts and returns a number of trees under a `p` node.
 Counts and returns a number of trees in a whole forest.
 
 
+### bool is_binarized() const;
+
+Returns true if the forest is binarized, ie. each node has up to 2 children.
+
+
+### template<typename TraversableT> bool detect_cycle(TraversableT& g) const;
+
+Returns true if there exist a cycle in a `g`.
+
+```
+// having a forest f and a graph fg
+if (f->detect_cycle(fg)) cout << "cycle detected\n";
+else cout << "no cycles\n";
+```
+
+
 ### std::vector<graph> extract_graphs(const NodeT& root, cb_next_graph_t cb_next_graph, bool unique_edge = true) const;
 
 Extracts graphs from the forest starting at a `root` node. For every extracted graph `cb_next_graph` callback is called.
@@ -93,15 +109,6 @@ auto next_g = [](parser<C, T>::pforest::graph& fg) {
 f->extract_graphs(f->root(), next_g);
 ```
 
-### template<typename TraversableT> bool detect_cycle(TraversableT& g) const;
-
-Returns true if there exist a cycle in a `g`.
-
-```
-// having a forest f and a graph fg
-if (f->detect_cycle(fg)) cout << "cycle detected\n";
-else cout << "no cycles\n";
-```
 
 ### bool traverse(...)
 
@@ -146,21 +153,21 @@ Traverses the whole forest.
 
 `cb_ambig` is called after entering a node which splits into more than one tree. The node is passed as a first argument, a set of vectors of nodes is passed as a second argument representing sets of children nodes where each set member represents a different tree.
 
+Example of a traversal printing nodes and ambiguities of a parsed forest
 ```
-
 function print_node(ostream& os, parser<>::pnode& n) {
 	return os << n.first << " [" << n.second[0] << ", " << n.second[1] << "]";
 };
 
 void main() {
 	grammar g(tgf<>::from_file("arithmetic.tgf"));
 	parser p(g);
-	auto f = p.parse("1+2*3");
-	if (!p.found()) {
-		cerr << p.get_error().to_str() << endl;
+	auto r = p.parse("1+2*3");
+	if (r.found) {
+		cerr << r.parse_error.to_str() << endl;
 		return;
 	}
-	f->traverse(
+	r.get_forest()->traverse(
 		[](const parser<>::pnode& n) {
 			print_node(cout << "entering node: ", n) << "\n";
 		},
@@ -183,3 +190,13 @@ void main() {
 	);
 }
 ```
+
+
+### bool replace_nodes(graph& g, nodes& s);
+
+Replace each node with its immediate children, assuming its only one pack (unambigous) the caller to ensure the right order to avoid cyclic dependency if any. deletes from graph g as well. return true if any one of the nodes' replacement succeeds
+
+
+### bool replace_node(graph& g, const node& torep,const nodes& replacement);
+
+Replaces node 'torep' in one pass with the given nodes 'replacement' everywhere in the forest and returns true if changed. Does not care if its recursive or cyclic, its caller's responsibility to ensure

docs/measure.md

@@ -0,0 +1,38 @@
+[back to index](../README.md#classes-and-structs)
+
+# measure
+
+`measure` is a structure capable of measuring elapsed time. Values printed and returned are in milliseconds (ms).
+
+## constructor
+
+```
+measure(const std::string& label, bool start_measure = false, bool silent = false);
+```
+
+Creates a measuring object labeled with a `label`.
+
+If `start_measure` is true it starts measuring when instantiated (constructor calls `start()`).
+
+If `silent` is true it prints no measurement info but `stop()` and `pause()` still returns elapsed time in ms.
+
+
+## methods
+
+### void start();
+
+Starts measuring.
+
+### double pause();
+
+Pauses measuring and returns elapsed time from start in ms.
+
+### double unpause();
+
+Unpause measuring.
+
+### double stop();
+
+Stops measuring, if `silent` is not `true` it prints measured info and returns elapsed time in ms.
+
+`stop()` is called when measur struct is destructed.

docs/parser_pnode.md

@@ -1,7 +1,7 @@
-[back to index](../README.md#overview-of-types)
+[back to index](../README.md#classes-and-structs)
 
 # parser::pnode
 
-`pnode` is a structure used as a forest node. It maps nodes into pointers to make sure the forest does not contain duplicities.
+`pnode` is a structure used as a forest node. It maps nodes to pointers to make sure the forest does not contain duplicities.
 
 It has the same api as `std::pair<lit<C, T>, std::array<size_t, 2>>` containing the literal and it's position span in the input.