path - Path - Base class, common API
Welcome to the Path project, written by Andreas Kupries.
For availability please read Path - How To Get The Sources.
While this package, from its name, looks like the public entrypoint of the system, it is not. This package is internal, providing the base class for all the others implementing actual storage backends.
The following sections are of interest only to developers intending to extend or modify the system, then. Everybody else can skip this document.
This sections lists and describes all the methods a derived class has to override to be a proper and functional path storage:
This method's implementation has to add the path specified by the path id of its parent and the atom id of its segment name to the instance, and return its unique numeric identifier as the result of the method.
Multiple calls of this method for the same combination of parent and segment have to return the same identifier.
This method's implementation has to map the specified numeric path id back to its combination of parent and segment (see Encode above), and return that pair as the result of the method.
An error must be thrown if the id is not known to the instance.
This method's implementation has to return a list of all paths which have been interned into the instance. No specific order is guaranteed.
Beware, this is an expensive operation as it has to decode the internal representation for all interned paths back to their representation as lists of strings.
This method's implementation has to test if the path specified by its combination of parent and segment ids has been interned into the instance and return a boolean flag as the result of the method.
The result has to be true if the path is known, and false otherwise.
Furthermore, if the path does exist then its numeric id is stored into the variable named by idvar.
This method's implementation has to test if the specified numeric path id is known to the instance and return a boolean flag as the result of the method.
The result has to be true if the id is known, and false otherwise.
This method's implementation has to return the number of interned paths known to the instance.
This method's implementation has to add the specified path to the instance and force an association with the specified numeric path id. The path argument is only used for error messages. The actual representation is that of a combination of parent and segment id, is done for Encode, of which this method is a variant of.
The result of the method has to be the empty string.
An error has to be thrown if the id is already used for a different path.
This method's implementation has to drop all path/id mappings from the instance. After this method has run the instance must be empty.
The result of this method must be the empty string.
This sections lists the base class methods a derived class may override. While they have implementations in the base these are generic and may not be as efficient as possible for the derived class and its full access to its own datastructures.
These methods have to intern a path and return its unique numeric id. The methods with names ending * take the segments of the path as separate arguments, while the other methods take them as a list. The methods with -from in the name take the path id of a known base path, and intern the actual path relative to the base, i.e. as a child of the base.
If the id of the base path is not known an error has to be thrown.
The standard implementations use Encode (see previous section) to incrementally intern the path.
These methods have to test if a path is interned and return a boolean flag indicating the result of the test. true if the path exists, and false otherwise. The methods with names ending * take the segments of the path to check as separate arguments, while the other methods take them as a list. The methods with -from in the name take the path id of a known base path, and check the actual path relative to the base, i.e. as a child of the base.
If the id of the base path is not known an error has to be thrown.
The standard implementations use Has (see previous section) to incrementally check the path.
This method's implementation has to map the specified path id back to the path it was generated from during interning, and return that path as its result.
The standard implementation uses Decode (see previous section) to incrementally regain the path.
This method's implementation has to intern the specified path and force it to map to the given id.
The standard implementation recodes the path into the internal combination of parent and segment ids and then uses Map (see previous section) to save the forced mapping.
The result of the method has to be id.
This method's implementation has to serialize the content of the instance, i.e. the path-to-id map and return it as the result of the method.
The result has to be an ordered Tcl dictionary with the paths as keys and the associated identifiers as the values. The paths are however not represented by their full list of strings, but as a pair of parent path id and segment name. This form retains the internal compression done by the store. The ordering comes in because the command has to list parent paths before their children. This is necessary for deserialize and merge to work correctly.
This method's implementation has to take a serialization as generated by method serialize and add it to the instance. It has to use the semantics of method map for this, to preserve the exact path/id mapping found in the input. On the flip-side this means that existing mappings may interfere, in that case an error has to be thrown.
The result of the method has to be the empty string.
This method's implementation has to take a serialization as generated by method serialize and have it replace the previous content of the instance.
The result of the method has to be the empty string.
This method's implementation has to take a serialization as generated by method serialize and add the strings it contains to the instance, per the semantics of method id.
The ids found in the serialization do not matter and have to be ignored.
The result of the method has to be the empty string.
Both the package(s) and this documentation will undoubtedly contain bugs and other problems. Please report such at Path Tickets.
Please also report any ideas you may have for enhancements of either package(s) and/or documentation.
deduplication, hierarchical, interning, list(string) deduplication, list(string) interning, list(string) storage, path deduplication, path interning, path storage, storage, tree
Copyright © 2017 Andreas Kupries
Copyright © 2017 Documentation, Andreas Kupries