This module supplies the root prototype object from which every other
+ object is descended. There are no classes as such, rather new objects
+ are created by cloning an existing object, and then changing or adding
+ to the clone. Further objects can then be made by cloning the changed
+ object, and so on.
+
+
The functionality of a container based object is entirely defined by its
+ metamethods. However, since we can store any object in a container,
+ we cannot rely on the __index metamethod, because it is only a
+ fallback for when that key is not already in the container itself. Of
+ course that does not entirely preclude the use of __index with
+ containers, so long as this limitation is observed.
+
+
When making your own prototypes, derive from prototype.container.prototype
+ if you want to access the contents of your containers with the []
+ operator, otherwise from prototype.object.prototype if you want to access
+ the functionality of your objects with named object methods.
Return new with references to the fields of src merged in.
+
+
+
+
+
+
+
+
Objects
+
+
+
+
+ prototype
+
+
+ Container prototype.
+
+
+
Fields:
+
+
_init
+ table or function
+ object initialisation
+ (optional)
+
+
_type
+ string
+ object name
+ (default "Container")
+
+
+
+
+
+
+
Usage:
+
+
+ local Container = require"prototype.container".prototype
+ local Graph = Container { _type = "Graph" }
+ localfunction nodes (graph)
+ local n = 0
+ for _ in std.pairs (graph) do n = n + 1end
+ return n
+ end
+ local g = Graph { "node1", "node2" }
+ assert (nodes (g) == 2)
+
+
+
+
+
Metamethods
+
+
+
+
+ prototype:__call (...)
+
+
+ Return a clone of this container and its metatable.
+
+
Like any Lua table, a container is essentially a collection of
+ field_n = value_n pairs, except that field names beginning with
+ an underscore _ are usually kept in that container's metatable
+ where they define the behaviour of a container object rather than
+ being part of its actual contents. In general, cloned objects
+ also clone the behaviour of the object they cloned, unless...
+
+
When calling prototype.container.prototype, you pass a single table
+ argument with additional fields (and values) to be merged into the
+ clone. Any field names beginning with an underscore _ are copied
+ to the clone's metatable, and all other fields to the cloned
+ container itself. For instance, you can change the name of the
+ cloned object by setting the _type field in the argument table.
+
+
The _init private field is also special: When set to a sequence of
+ field names, unnamed fields in the call argument table are assigned
+ to those field names in subsequent clones, like the example below.
+
+
Alternatively, you can set the _init private field of a cloned
+ container object to a function instead of a sequence, in which case
+ all the arguments passed when it is called/cloned (including named
+ and unnamed fields in the initial table argument, if there is one)
+ are passed through to the _init function, following the nascent
+ cloned object. See the mapfields usage example below.
+
+
+
Parameters:
+
+
...
+ arguments to prototype's _init, often a single table
+
+
+
+
Returns:
+
+
+ prototype
+ clone of this container, with shared or
+ merged metatable as appropriate
+
+
+
+
+
Usage:
+
+
+ local Cons = Container {_type="Cons", _init={"car", "cdr"}}
+ local list = Cons {"head", Cons {"tail", nil}}
+
+
+
+
+
+ prototype:__tostring ()
+
+
+ Return a compact string representation of this object.
+
+
First the container name, and then between { and } an ordered list
+ of the array elements of the contained values with numeric keys,
+ followed by asciibetically sorted remaining public key-value pairs.
+
+
This metamethod doesn't recurse explicitly, but relies upon
+ suitable __tostring metamethods for non-primitive content objects.
+
+
+
+
+ Return new with references to the fields of src merged in.
+
+
This is the function used to instantiate the contents of a newly
+ cloned container, as called by __call above, to split the
+ fields of a __call argument table into private "_" prefixed
+ field namess, -- which are merged into the new metatable, and
+ public (everything else) names, which are merged into new itself.
+
+
You might want to use this function from _init functions of your
+ own derived containers.
+
+
+
Parameters:
+
+
new
+ table
+ partially instantiated clone container
+
In addition to the functionality described here, List objects also
+ have all the methods and metamethods of the prototype.object.prototype
+ (except where overridden here),
This module provides a specialization of the prototype.container.prototype
+ with the addition of object methods. In addition to the functionality
+ described here, object prototypes also have all the methods and
+ metamethods of the prototype.container.prototype.
+
+
Note that object methods are stored in the __index field of their
+ metatable, and so cannot also use the __index metamethod to lookup
+ references with square brackets. Use a prototype.container.prototype based
+ object if you want to do that.
+ Return an in-order iterator over public object fields.
+
+
+
+
Returns:
+
+
+ function
+ iterator function
+
+ Object
+ self
+
+
+
+
+
Usage:
+
+
for k, v in prototype.pairs (anobject) do process (k, v) end
+
+
+
+
+
Methods
+
+
+
+
+ prototype:clone (...)
+
+
+ Return a clone of this object and its metatable.
+
+
This function is useful if you need to override the normal use of
+ the __call metamethod for object cloning, without losing the
+ ability to clone an object.
+
+
+
Parameters:
+
+
...
+ arguments to prototype's _init, often a single table
+
+
+
+
Returns:
+
+
+ prototype
+ a clone of this object, with shared or merged
+ metatable as appropriate
+
+
+
+
+ local Node = Object { _type = "Node" }
+ -- A trivial FSA to recognize powers of 10, either "0" or a "1"
+-- followed by zero or more "0"s can transition to state 'finish'
+local states; states = {
+ start = Node { ["1"] = states[1], ["0"] = states.finish },
+ [1] = Node { ["0"] = states[1], [""] = states.finish },
+ finish = Node {},
+ }
+
+
+
+
+
Object Functions
+
+
+
+
+ prototype.mapfields (new, src[, map={}])
+
+
+ Return new with references to the fields of src merged in.
+
+
You can change the value of this function in an object, and that
+ new function will be called during cloning instead of the
+ standard prototype.container.mapfields implementation.
+
+
+
Parameters:
+
+
new
+ table
+ partially instantiated clone container
+
This module returns a table of set operators, as well as the prototype
+ for a Set container object.
+
+
Every possible object or primitive value is always present in any Set
+ container exactly zero or one times.
+
+
In addition to the functionality described here, Set containers also
+ have all the methods and metamethods of the prototype.container.prototype
+ (except where overridden here).
Buffers are mutable by default, but being based on objects, they can
+ also be used in a functional style:
+
+
+
+local StrBuf = require"prototype.strbuf".prototype
+local a = StrBuf {"a"}
+local b = a:concat "b"-- mutate *a*
+print (a, b) --> ab ab
+local c = a {} .. "c"-- copy and append
+print (a, c) --> ab abc
+
+
+
+
In addition to the functionality described here, StrBuf objects also
+ have all the methods and metamethods of the prototype.object.prototype
+ (except where overridden here),
+ Add a object to a buffer.
+ Elements are stringified lazily, so if you add a table and then
+ change its contents, the contents of the buffer will be affected
+ too.
+
+
+
+ local StrBuf = require"prototype.strbuf".prototype
+ local a = StrBuf {1, 2, 3}
+ local b = StrBuf {a, "five", "six"}
+ a = a .. 4
+ b = b:concat "seven"
+ print (a, b) --> 1234 1234fivesixseven
+os.exit (0)
+
+
+
+
+
+
+
+
+
+generated by LDoc 1.4.3
+Last updated 2016-02-06 00:10:05
+
This module returns a table of tree operators, as well as the prototype
+ for a Tree container object.
+
+
This is not a search tree, but rather a way to efficiently store and
+ retrieve values stored with a path as a key, such as a multi-key
+ keytable. Although it does have iterators for walking the tree with
+ various algorithms.
+
+
In addition to the functionality described here, Tree containers also
+ have all the methods and metamethods of the prototype.container.prototype
+ (except where overridden here),
The returned iterator function performs a depth-first traversal of
+ tr, and at each node it returns {node-type, tree-path, tree-node}
+ where node-type is branch, join or leaf; tree-path is a
+ list of keys used to reach this node, and tree-node is the current
+ node.
+
+
Note that the tree-path reuses the same table on each iteration, so
+ you must table.clone a copy if you want to take a snap-shot of the
+ current state of the tree-path list before the next iteration
+ changes it.
+
+
+
Parameters:
+
+
tr
+ prototype or table
+ tree or tree-like table to iterate over
+
A straight forward prototype-based object system, and a selection of
-useful objects built on it.
+useful objects built on it.
This is a collection of light-weight libraries for Lua 5.1 (including
-LuaJIT), 5.2 and 5.3 written in pure Lua, comprising:
+LuaJIT), 5.2 and 5.3 written in pure Lua.
+
+
Each of the modules in this package returns a table with an empty
+prototype object in the prototype field, and often a selection of
+module functions not related to a specific instance. That is, when
+you require one of these modules, you get a conventional table of
+functions plus an empty object of some sort:
+
+
+
local object = require "std.prototype.object"
+for k, v in pairs (object) do print (k, type (v)) end
+--> prototype table
+--> type function
+
+
+
In this case, a module function called type which looks up the
+_type field in any prototype's metatable, and an empty Object:
+
+
print (object.prototype)
+--> Object {}
+
+
+
You can instantiate additional copies of a prototype by calling it with
+a table of specialised attributes:
As a convenience, calling the module itself passes the argument table
+through to that module's prototype, although its faster to save an
+empty instance of the prototype in a local and use that: