Lichen

Change of docs/wiki/Representations

861:f745d151a441
docs/wiki/Representations
     1.1 --- a/docs/wiki/Representations	Sat Jul 21 23:19:26 2018 +0200
     1.2 +++ b/docs/wiki/Representations	Fri Aug 17 11:41:28 2018 +0200
     1.3 @@ -1,12 +1,16 @@
     1.4  = Representing Program Objects =
     1.5  
     1.6 -Certain representations have been chosen for program objects that attempt to support efficient access to those objects during the execution of a program.
     1.7 +Certain representations have been chosen for program objects that attempt to
     1.8 +support efficient access to those objects during the execution of a program.
     1.9  
    1.10  <<TableOfContents(2,2)>>
    1.11  
    1.12  == Attributes ==
    1.13  
    1.14 -The principal means of referring to an object in a program is by using an '''attribute''', having this name because it is the representation of an attribute in classes, instances and modules. Each attribute can hold a reference to an object, known as the '''value''', or other kinds of data:
    1.15 +The principal means of referring to an object in a program is by using an
    1.16 +'''attribute''', having this name because it is the representation of an
    1.17 +attribute in classes, instances and modules. Each attribute can hold a
    1.18 +reference to an object, known as the '''value''', or other kinds of data:
    1.19  
    1.20  {{{#!graphviz
    1.21  //format=svg
    1.22 @@ -25,19 +29,49 @@
    1.23  }
    1.24  }}}
    1.25  
    1.26 -Although a value indicates a specific object of interest for an attribute, if the object is callable then additional '''context''' information may be required to call the object. Such context information is not stored in an attribute record but is instead obtained from the object itself, if appropriate.
    1.27 +Although a value indicates a specific object of interest for an attribute, if
    1.28 +the object is callable then additional '''context''' information may be
    1.29 +required to call the object. Such context information is not stored in an
    1.30 +attribute record but is instead obtained from the object itself, if
    1.31 +appropriate.
    1.32  
    1.33  === Integer Representation ===
    1.34  
    1.35 -The `intvalue` member of the attribute structure is employed instead of the `value` member to store integer values. Since `value` normally holds a pointer, and since pointers are often aligned to certain address boundaries on many modern platforms (usually four-byte boundaries on 32-bit platforms, eight-byte boundaries on 64-bit platforms, two-byte boundaries on platforms with 16-bit addressing), the lowest significant bit (bit 0) will typically be zero for a valid pointer. Consequently, by setting bit 0 to 1, other data can be stored in the remaining bits and be distinguished from pointer information. Obviously, operations on attributes first need to test whether the `value` member or the `intvalue` member is in use by testing bit 0.
    1.36 +The `intvalue` member of the attribute structure is employed instead of the
    1.37 +`value` member to store integer values. Since `value` normally holds a
    1.38 +pointer, and since pointers are often aligned to certain address boundaries on
    1.39 +many modern platforms (usually four-byte boundaries on 32-bit platforms,
    1.40 +eight-byte boundaries on 64-bit platforms, two-byte boundaries on platforms
    1.41 +with 16-bit addressing), the lowest significant bit (bit 0) will typically be
    1.42 +zero for a valid pointer. Consequently, by setting bit 0 to 1, other data can
    1.43 +be stored in the remaining bits and be distinguished from pointer information.
    1.44 +Obviously, operations on attributes first need to test whether the `value`
    1.45 +member or the `intvalue` member is in use by testing bit 0.
    1.46  
    1.47 -Thus, integers are transformed and stored directly within attributes, and they are therefore passed around by value. When an attribute of an integer needs to be accessed, the operation usually providing the `value` member, thus obtaining an instance under normal circumstances, instead provides the address of a common integer instance. This instance may then provide instance attributes, whose values will be the same for all integers, or class attributes through a reference to the integer (`int`) class.
    1.48 +Thus, integers are transformed and stored directly within attributes, and they
    1.49 +are therefore passed around by value. When an attribute of an integer needs to
    1.50 +be accessed, the operation usually providing the `value` member, thus
    1.51 +obtaining an instance under normal circumstances, instead provides the address
    1.52 +of a common integer instance. This instance may then provide instance
    1.53 +attributes, whose values will be the same for all integers, or class
    1.54 +attributes through a reference to the integer (`int`) class.
    1.55  
    1.56 -Each method provided by `int`, when called, will be given the original attribute for which the method was obtained as its context. In such methods, operations on the context via `self` will either involve the propagation of the attribute to other functions or methods or attribute accesses on `self`, yielding common instance attributes or class attributes as already described. Only native functions will attempt to interpret the attribute in a different way, decoding the representation, performing arithmetic or logical operations, and encoding the result in a new attribute.
    1.57 +Each method provided by `int`, when called, will be given the original
    1.58 +attribute for which the method was obtained as its context. In such methods,
    1.59 +operations on the context via `self` will either involve the propagation of
    1.60 +the attribute to other functions or methods or attribute accesses on `self`,
    1.61 +yielding common instance attributes or class attributes as already described.
    1.62 +Only native functions will attempt to interpret the attribute in a different
    1.63 +way, decoding the representation, performing arithmetic or logical operations,
    1.64 +and encoding the result in a new attribute.
    1.65  
    1.66  == Contexts and Wrappers ==
    1.67  
    1.68 -The context of an object is of significance if that object is callable. For example, an instance may permit access to a method via an attribute. Since the method will be callable, and since the method is accessed via the instance, the context of that method will be the instance. In order to retain both context and value information, a '''wrapper''' may be created.
    1.69 +The context of an object is of significance if that object is callable. For
    1.70 +example, an instance may permit access to a method via an attribute. Since the
    1.71 +method will be callable, and since the method is accessed via the instance,
    1.72 +the context of that method will be the instance. In order to retain both
    1.73 +context and value information, a '''wrapper''' may be created.
    1.74  
    1.75  {{{#!graphviz
    1.76  //format=svg
    1.77 @@ -57,11 +91,14 @@
    1.78  }
    1.79  }}}
    1.80  
    1.81 -The context is not always the accessor of the object - in this case, the instance - because the object may already be a wrapper with its own context.
    1.82 +The context is not always the accessor of the object - in this case, the
    1.83 +instance - because the object may already be a wrapper with its own context.
    1.84  
    1.85  == Objects ==
    1.86  
    1.87 -Classes, instances and modules are objects, and all of these kinds of objects provide metadata describing the type of each object, together with a collection of attributes forming the contents of such objects.
    1.88 +Classes, instances and modules are objects, and all of these kinds of objects
    1.89 +provide metadata describing the type of each object, together with a
    1.90 +collection of attributes forming the contents of such objects.
    1.91  
    1.92  {{{#!graphviz
    1.93  //format=svg
    1.94 @@ -84,31 +121,52 @@
    1.95  }
    1.96  }}}
    1.97  
    1.98 -Classes are represented by structures whose members reference class attributes and class metadata (the class table), as well as incorporating invocation metadata (the `__args__` and `__fn__` special attributes).
    1.99 +Classes are represented by structures whose members reference class attributes
   1.100 +and class metadata (the class table), as well as incorporating invocation
   1.101 +metadata (the `__args__` and `__fn__` special attributes).
   1.102  
   1.103 -Instances are represented by structures whose members reference instance attributes (including `__class__` which indicates the class instantiated by a given instance) and instance metadata (the instance table), as well as incorporating invocation metadata (the `__args__` and `__fn__` special attributes).
   1.104 +Instances are represented by structures whose members reference instance
   1.105 +attributes (including `__class__` which indicates the class instantiated by a
   1.106 +given instance) and instance metadata (the instance table), as well as
   1.107 +incorporating invocation metadata (the `__args__` and `__fn__` special
   1.108 +attributes).
   1.109  
   1.110 -Functions are instances of a general function type that does not permit additional, general instance attributes. However, function instance structures may have extra members corresponding to default parameter values. Access to such extra members is performed using the minimum and maximum values provided via `__args__` and with knowledge of the number of declared instance attributes indicated by the instance table for the function type.
   1.111 +Functions are instances of a general function type that does not permit
   1.112 +additional, general instance attributes. However, function instance structures
   1.113 +may have extra members corresponding to default parameter values. Access to
   1.114 +such extra members is performed using the minimum and maximum values provided
   1.115 +via `__args__` and with knowledge of the number of declared instance
   1.116 +attributes indicated by the instance table for the function type.
   1.117  
   1.118 -Modules are represented by structures whose members reference module attributes and module metadata (the module table).
   1.119 +Modules are represented by structures whose members reference module
   1.120 +attributes and module metadata (the module table).
   1.121  
   1.122  == Special Members ==
   1.123  
   1.124 -All object representations support the following special members describing the invocation properties of each object:
   1.125 +All object representations support the following special members describing
   1.126 +the invocation properties of each object:
   1.127  
   1.128  {{{#!table
   1.129 -`__args__` || the minimum number of arguments supported in an invocation and a reference to the parameter table for the object
   1.130 +`__args__` || the minimum number of arguments supported in an invocation and a
   1.131 +           .. reference to the parameter table for the object
   1.132  ==
   1.133 -`__fn__` || a reference to a native function containing the actual code run when calling the object
   1.134 +`__fn__` || a reference to a native function containing the actual code run
   1.135 +         .. when calling the object
   1.136  }}}
   1.137  
   1.138 -Classes are invoked in order to create instances of each class ('''instantiation'''). Instances may support invocation by providing a `__call__` method. Functions are supported by instances of a general function class. Modules are generally not callable and will not actually provide these special members in practice.
   1.139 +Classes are invoked in order to create instances of each class
   1.140 +('''instantiation'''). Instances may support invocation by providing a
   1.141 +`__call__` method. Functions are supported by instances of a general function
   1.142 +class. Modules are generally not callable and will not actually provide these
   1.143 +special members in practice.
   1.144  
   1.145  All object representations support information about their type:
   1.146  
   1.147  {{{#!table
   1.148  `__class__`
   1.149 -|| the class of the object: instances refer to their classes, classes refer to the `type` class, functions are instances that refer to the `function` class, modules refer to the `module` class
   1.150 +|| the class of the object: instances refer to their classes, classes refer to
   1.151 +.. the `type` class, functions are instances that refer to the `function`
   1.152 +.. class, modules refer to the `module` class
   1.153  }}}
   1.154  
   1.155  Certain kinds of object support other descriptive attributes:
   1.156 @@ -119,31 +177,48 @@
   1.157  `__parent__` || the parent scope of a class or a function
   1.158  }}}
   1.159  
   1.160 -Objects supported by native, system-level functionality require a means of retaining information in special attributes:
   1.161 +Objects supported by native, system-level functionality require a means of
   1.162 +retaining information in special attributes:
   1.163  
   1.164  {{{#!table
   1.165  `__data__` || private data manipulated at the native level
   1.166  }}}
   1.167  
   1.168 -Strings support special annotation attributes that permit their use in dynamically resolving attributes:
   1.169 +Strings support special annotation attributes that permit their use in
   1.170 +dynamically resolving attributes:
   1.171  
   1.172  {{{#!table
   1.173 -`__key__` || the code and position of the attribute whose name is represented by the string
   1.174 +`__key__` || the code and position of the attribute whose name is represented
   1.175 +          .. by the string
   1.176  }}}
   1.177  
   1.178 -Such "key" attributes provide information that can be used to inspect an object table and to test for the presence of an attribute. With such information, the `getattr` and `hasattr` functions can be supported.
   1.179 +Such "key" attributes provide information that can be used to inspect an
   1.180 +object table and to test for the presence of an attribute. With such
   1.181 +information, the `getattr` and `hasattr` functions can be supported.
   1.182  
   1.183  == Attribute Tables ==
   1.184  
   1.185 -In order to provide information about the attributes supported by each object, the structure of each object will reference a table containing entries describing these supported attributes. The size of this table is declared within the table structure, and for each position in the table an entry corresponding to the same position within an actual object structure describes the nature of the attribute at that position.
   1.186 +In order to provide information about the attributes supported by each object,
   1.187 +the structure of each object will reference a table containing entries
   1.188 +describing these supported attributes. The size of this table is declared
   1.189 +within the table structure, and for each position in the table an entry
   1.190 +corresponding to the same position within an actual object structure describes
   1.191 +the nature of the attribute at that position.
   1.192  
   1.193  == Parameter Tables ==
   1.194  
   1.195 -In order to support argument validation and keyword arguments in invocations, a structure is referenced by `__args__` that indicates...
   1.196 +In order to support argument validation and keyword arguments in invocations,
   1.197 +a structure is referenced by `__args__` that indicates...
   1.198  
   1.199   * The minimum number of parameters supported by a callable
   1.200   * The maximum number of parameters supported by a callable
   1.201   * The size of the table describing the parameters
   1.202 - * A table of entries with each entry indicating the nature of a parameter (in effect, which name it uses, albeit as a generated code instead of a string) and the position of the parameter in any argument list prepared for an invocation
   1.203 + * A table of entries with each entry indicating the nature of a parameter (in
   1.204 +   effect, which name it uses, albeit as a generated code instead of a string)
   1.205 +   and the position of the parameter in any argument list prepared for an
   1.206 +   invocation
   1.207  
   1.208 -Parameter tables only need to be consulted at run-time if the nature of a callable is undetermined. By supporting a uniform interface, the arguments used in an invocation can be tested against the description provided by `__args__` and the table.
   1.209 +Parameter tables only need to be consulted at run-time if the nature of a
   1.210 +callable is undetermined. By supporting a uniform interface, the arguments
   1.211 +used in an invocation can be tested against the description provided by
   1.212 +`__args__` and the table.