1.1 --- a/README.txt Tue Sep 23 00:33:01 2008 +0200
1.2 +++ b/README.txt Fri Sep 26 23:48:05 2008 +0200
1.3 @@ -1,167 +1,3 @@
1.4 -Namespace Definition
1.5 -====================
1.6 -
1.7 -Module attributes are defined either at the module level or by global
1.8 -statements.
1.9 -
1.10 -Class attributes are defined only within class statements.
1.11 -
1.12 -Instance attributes are defined only by assignments to attributes of self
1.13 -within __init__ methods.
1.14 -
1.15 -(These restrictions apply because such attributes are thus explicitly
1.16 -declared. Module and class attributes can also be finalised in this way in
1.17 -order to permit certain optimisations.)
1.18 -
1.19 -Potential Restrictions
1.20 -----------------------
1.21 -
1.22 -Names of classes and functions could be restricted to only refer to those
1.23 -objects within the same namespace. If redefinition were to occur, or if
1.24 -multiple possibilities were present, these restrictions could be moderated as
1.25 -follows:
1.26 -
1.27 - * Classes assigned to the same name could provide the union of their
1.28 - attributes. This would, however, cause a potential collision of attribute
1.29 - definitions such as methods.
1.30 -
1.31 - * Functions, if they share compatible signatures, could share parameter list
1.32 - definitions.
1.33 -
1.34 -Instruction Evaluation Model
1.35 -============================
1.36 -
1.37 -Programs use a value stack where evaluated instructions may save their
1.38 -results. A value stack pointer indicates the top of this stack. In addition, a
1.39 -separate stack is used to record the invocation frames. All stack pointers
1.40 -refer to the next address to be used by the stack, not the address of the
1.41 -uppermost element.
1.42 -
1.43 - Frame Stack Value Stack
1.44 - ----------- ----------- Address of Callable
1.45 - -------------------
1.46 - previous ...
1.47 - current ------> callable -----> identifier
1.48 - arg1 reference to code
1.49 - arg2
1.50 - arg3
1.51 - local4
1.52 - local5
1.53 - ...
1.54 -
1.55 -Loading local names is a matter of performing frame-relative accesses to the
1.56 -value stack.
1.57 -
1.58 -Invocations and Argument Evaluation
1.59 ------------------------------------
1.60 -
1.61 -When preparing for an invocation, the caller first sets the invocation frame
1.62 -pointer. Then, positional arguments are added to the stack such that the first
1.63 -argument positions are filled. A number of stack locations for the remaining
1.64 -arguments specified in the program are then reserved. The names of keyword
1.65 -arguments are used (in the form of table index values) to consult the
1.66 -parameter table and to find the location in which such arguments are to be
1.67 -stored.
1.68 -
1.69 - fn(a, b, d=1, e=2, c=3) -> fn(a, b, c, d, e)
1.70 -
1.71 - Value Stack
1.72 - -----------
1.73 -
1.74 - ... ... ... ...
1.75 - fn fn fn fn
1.76 - a a a a
1.77 - b b b b
1.78 - ___ ___ ___ --> 3
1.79 - ___ --> 1 1 | 1
1.80 - ___ | ___ --> 2 | 2
1.81 - 1 ----------- 2 ----------- 3 -----------
1.82 -
1.83 -Conceptually, the frame can be considered as a collection of attributes, as
1.84 -seen in other kinds of structures:
1.85 -
1.86 -Frame for invocation of fn:
1.87 -
1.88 - 0 1 2 3 4 5
1.89 - code a b c d e
1.90 - reference
1.91 -
1.92 -However, where arguments are specified positionally, such "attributes" are not
1.93 -set using a comparable approach to that employed with other structures.
1.94 -Keyword arguments are set using an attribute-like mechanism, though, where the
1.95 -position of each argument discovered using the parameter table.
1.96 -
1.97 -Where the target of the invocation is known, the above procedure can be
1.98 -optimised slightly by attempting to add keyword argument values directly to
1.99 -the stack:
1.100 -
1.101 - Value Stack
1.102 - -----------
1.103 -
1.104 - ... ... ... ... ...
1.105 - fn fn fn fn fn
1.106 - a a a a a
1.107 - b b b b b
1.108 - ___ ___ ___ --> 3
1.109 - 1 1 1 | 1
1.110 - 2 1 | 2
1.111 - 3 -----------
1.112 -
1.113 - (reserve for (add in-place) (add in-place) (evaluate) (store by
1.114 - parameter c) index)
1.115 -
1.116 -Method Invocations
1.117 -------------------
1.118 -
1.119 -Method invocations incorporate an implicit first argument which is obtained
1.120 -from the context of the method:
1.121 -
1.122 - method(a, b, d=1, e=2, c=3) -> method(self, a, b, c, d, e)
1.123 -
1.124 - Value Stack
1.125 - -----------
1.126 -
1.127 - ...
1.128 - method
1.129 - context of method
1.130 - a
1.131 - b
1.132 - 3
1.133 - 1
1.134 - 2
1.135 -
1.136 -Although it could be possible to permit any object to be provided as the first
1.137 -argument, in order to optimise instance attribute access in methods, we should
1.138 -seek to restrict the object type.
1.139 -
1.140 -Verifying Supplied Arguments
1.141 -----------------------------
1.142 -
1.143 -In order to ensure a correct invocation, it is also necessary to check the
1.144 -number of supplied arguments. If the target of the invocation is known at
1.145 -compile-time, no additional instructions need to be emitted; otherwise, the
1.146 -generated code must test for the following situations:
1.147 -
1.148 - 1. That the number of supplied arguments is equal to the number of expected
1.149 - parameters.
1.150 -
1.151 - 2. That no keyword argument overwrites an existing positional parameter.
1.152 -
1.153 -Default Arguments
1.154 ------------------
1.155 -
1.156 -Some arguments may have default values which are used if no value is provided
1.157 -in an invocation. Such defaults are initialised when the function itself is
1.158 -initialised, and are used to fill in any invocation frames that are known at
1.159 -compile-time.
1.160 -
1.161 -Tuples, Frames and Allocation
1.162 ------------------------------
1.163 -
1.164 -Using the approach where arguments are treated like attributes in some kind of
1.165 -structure, we could choose to allocate frames in places other than a stack.
1.166 -This would produce something somewhat similar to a plain tuple object.
1.167 -
1.168 Optimisations
1.169 =============
1.170
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/evaluation.txt Fri Sep 26 23:48:05 2008 +0200
2.3 @@ -0,0 +1,113 @@
2.4 +Instruction Evaluation Model
2.5 +============================
2.6 +
2.7 +Programs use a value stack containing local and temporary storage. A value
2.8 +stack pointer indicates the top of this stack. In addition, a separate stack
2.9 +is used to record the invocation frames. All stack pointers refer to the next
2.10 +address to be used by the stack, not the address of the uppermost element.
2.11 +
2.12 + Frame Stack Value Stack
2.13 + ----------- ----------- Address of Callable
2.14 + -------------------
2.15 + previous ...
2.16 + current ------> callable -----> identifier
2.17 + arg1 reference to code
2.18 + arg2
2.19 + arg3
2.20 + local4
2.21 + local5
2.22 + ...
2.23 +
2.24 +Unlike the CPython virtual machine, programs do not use a value stack
2.25 +containing the results of expression evaluations. Instead, temporary storage
2.26 +is statically allocated and employed by instructions.
2.27 +
2.28 +Loading local names and temporary values is a matter of performing
2.29 +frame-relative accesses to the value stack.
2.30 +
2.31 +Invocations and Argument Evaluation
2.32 +-----------------------------------
2.33 +
2.34 +When preparing for an invocation, the caller first sets the invocation frame
2.35 +pointer. A number of locations for the arguments required by the invocation
2.36 +are then reserved. With a frame to prepare, positional arguments are added to
2.37 +the frame in order such that the first argument positions are filled. The
2.38 +names of keyword arguments are used (in the form of table index values) to
2.39 +consult the parameter table and to find the frame location in which such
2.40 +arguments are to be stored.
2.41 +
2.42 + fn(a, b, d=1, e=2, c=3) -> fn(a, b, c, d, e)
2.43 +
2.44 + Frame
2.45 + -----
2.46 +
2.47 + a a a a
2.48 + b b b b
2.49 + ___ ___ ___ --> 3
2.50 + ___ --> 1 1 | 1
2.51 + ___ | ___ --> 2 | 2
2.52 + 1 ----------- 2 ----------- 3 -----------
2.53 +
2.54 +Conceptually, the frame can be considered as a collection of attributes, as
2.55 +seen in other kinds of structures:
2.56 +
2.57 +Frame for invocation of fn:
2.58 +
2.59 + 0 1 2 3 4 5
2.60 + code a b c d e
2.61 + reference
2.62 +
2.63 +However, where arguments are specified positionally, such "attributes" are not
2.64 +set using a comparable approach to that employed with other structures.
2.65 +Keyword arguments are set using an attribute-like mechanism, though, where the
2.66 +position of each argument discovered using the parameter table.
2.67 +
2.68 +Method Invocations
2.69 +------------------
2.70 +
2.71 +Method invocations incorporate an implicit first argument which is obtained
2.72 +from the context of the method:
2.73 +
2.74 + method(a, b, d=1, e=2, c=3) -> method(self, a, b, c, d, e)
2.75 +
2.76 + Frame
2.77 + -----
2.78 +
2.79 + context of method
2.80 + a
2.81 + b
2.82 + 3
2.83 + 1
2.84 + 2
2.85 +
2.86 +Although it could be possible to permit any object to be provided as the first
2.87 +argument, in order to optimise instance attribute access in methods, we should
2.88 +seek to restrict the object type.
2.89 +
2.90 +Verifying Supplied Arguments
2.91 +----------------------------
2.92 +
2.93 +In order to ensure a correct invocation, it is also necessary to check the
2.94 +number of supplied arguments. If the target of the invocation is known at
2.95 +compile-time, no additional instructions need to be emitted; otherwise, the
2.96 +generated code must test for the following situations:
2.97 +
2.98 + 1. That the number of supplied arguments is equal to the number of expected
2.99 + parameters.
2.100 +
2.101 + 2. That no keyword argument overwrites an existing positional parameter.
2.102 +
2.103 +Default Arguments
2.104 +-----------------
2.105 +
2.106 +Some arguments may have default values which are used if no value is provided
2.107 +in an invocation. Such defaults are initialised when the function itself is
2.108 +initialised, and are used to fill in any invocation frames that are known at
2.109 +compile-time.
2.110 +
2.111 +Tuples, Frames and Allocation
2.112 +-----------------------------
2.113 +
2.114 +Using the approach where arguments are treated like attributes in some kind of
2.115 +structure, we could choose to allocate frames in places other than a stack.
2.116 +This would produce something somewhat similar to a plain tuple object.
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/docs/namespaces.txt Fri Sep 26 23:48:05 2008 +0200
3.3 @@ -0,0 +1,33 @@
3.4 +Namespace Definition
3.5 +====================
3.6 +
3.7 +Module attributes are defined either at the module level or by global
3.8 +statements.
3.9 +
3.10 +Class attributes are defined only within class statements.
3.11 +
3.12 +Instance attributes are defined only by assignments to attributes of self
3.13 +within __init__ methods.
3.14 +
3.15 +(These restrictions apply because such attributes are thus explicitly
3.16 +declared. Module and class attributes can also be finalised in this way in
3.17 +order to permit certain optimisations.)
3.18 +
3.19 +Potential Restrictions
3.20 +----------------------
3.21 +
3.22 +Names of classes and functions could be restricted to only refer to those
3.23 +objects within the same namespace. If redefinition were to occur, or if
3.24 +multiple possibilities were present, these restrictions could be moderated as
3.25 +follows:
3.26 +
3.27 + * Classes assigned to the same name could provide the union of their
3.28 + attributes. This would, however, cause a potential collision of attribute
3.29 + definitions such as methods.
3.30 +
3.31 + * Functions, if they share compatible signatures, could share parameter list
3.32 + definitions.
3.33 +
3.34 +It is easier, however, to regard multiply defined classes and functions as
3.35 +non-constant and to either disallow optimisations or to actually prevent the
3.36 +program describing them from compiling.
4.1 --- a/docs/rationale.txt Tue Sep 23 00:33:01 2008 +0200
4.2 +++ b/docs/rationale.txt Fri Sep 26 23:48:05 2008 +0200
4.3 @@ -1,8 +1,11 @@
4.4 Micropython: A minimal implementation of Python for constrained devices
4.5
4.6 - * Python provides a rich programming environment
4.7 - * CPython enforces the "official" language version
4.8 - * CPython, Jython, etc. expose the full strength language
4.9 + * "Full strength" Python:
4.10 + * Introspection, interactivity, PEP/reference-compliance
4.11 + * CPython, Jython, IronPython, PyPy, CLPython, etc.
4.12 + * "Reduced strength" Python:
4.13 + * Remove "luxury" semantics
4.14 + * Shed Skin, RPython, etc.
4.15
4.16 Motivations
4.17
4.18 @@ -22,6 +25,7 @@
4.19
4.20 * Locals, modules and classes are special in some way
4.21 * Locals don't tend to change unilaterally
4.22 + * Parameter lists don't tend to change if fully specified
4.23 * Modules usually retain their identity
4.24 * Classes differ from objects (despite metaclasses)
4.25