Class std.object

Prototype-based objects.

This module creates 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.

Objects are cloned by simply calling an existing object, which then serves as a prototype from which the new object is copied.

All valid objects contain a field _init, which determines the syntax required to execute the cloning process:

  1. _init can be a list of keys; then the unnamed init_1 through init_m values from the argument table are assigned to the corresponding keys in new_object;

     new_object = proto_object {
       init_1, ..., init_m;
       field_1 = value_1,
       ...
       field_n = value_n,
     }
    
  2. Or it can be a function, in which the arguments passed to the prototype during cloning are simply handed to the _init function:

    new_object = proto_object (arg, ...)
    

Objects, then, are essentially tables of field_n = value_n pairs:

  > o = Object {
  >>  field_1 = "value_1",
  >>  method_1 = function (self) return self.field_1 end,
  >> }
  > = o.field_1
  value_1
  > o.field_2 = 2
  > function o:method_2 (n) return self.field_2 + n end
  > = o:method_2 (2)
  4

Normally new_object automatically shares a metatable with proto_object. However, field names beginning with "_" are private, and moved into the object metatable during cloning. So, adding new private fields to an object during cloning will result in a new metatable for new_object that also contains a copy of all the entries in the proto_object metatable.

Note that Object methods are stored in the __index field of their metatable, and so cannot also use __index to lookup references with square brackets. See std.container objects if you want to do that.

Tables

std.object Root object.

Metamethods

std.object:__call (...) Return a clone of this object, and its metatable.
std.object:__tostring () Return a string representation of this object.
std.object:__totable () Return a shallow copy of non-private object fields.

Methods

std.object:clone (o, ...) Clone this Object.
std.object:prototype (x) Type of an object, or primitive.


Tables

std.object
Root object.

Changing the values of these fields in a new object will change the corresponding behaviour.

Fields:

  • _init table or function a table of field names, or initialisation function, used by clone
  • _functions nil or table a table of module functions not copied by std.object.__call
  • _type string type of Object, returned by prototype (default "Object")

Metamethods

std.object:__call (...)
Return a clone of this object, and its metatable.

Private fields are stored in the metatable.

Parameters:

  • ... arguments for _init

Returns:

    std.object a clone of the this object.

See also:

std.object:__tostring ()
Return a string representation of this object.

First the object type, and then between { and } a list of the array part of the object table (without numeric keys) followed by the remaining key-value pairs.

This function doesn't recurse explicity, but relies upon suitable __tostring metamethods in field values.

Returns:

    string stringified container representation

See also:

std.object:__totable ()
Return a shallow copy of non-private object fields.

Used by clone to get the base contents of the new object. Can be overridden in other objects for greater control of which fields are considered non-private.

Returns:

    table a shallow copy of non-private object fields

See also:

Methods

std.object:clone (o, ...)
Clone this Object.

Parameters:

  • o std.object an object
  • ... a list of arguments if o._init is a function, or a single table if o._init is a table.

Returns:

    std.object a clone of o

See also:

std.object:prototype (x)

Type of an object, or primitive.

It's conventional to organise similar objects according to a string valued _type field, which can then be queried using this function.

 Stack = Object {
   _type = "Stack",

   __tostring = function (self) ... end,

   __index = {
     push = function (self) ... end,
     pop  = function (self) ... end,
   },
 }
 stack = Stack {}

 stack:prototype () --> "Stack"

Parameters:

  • x anything

Returns:

    string type of x
generated by LDoc 1.4.0