1.1 --- a/docs/wiki/Restarted Sat Jul 21 23:19:26 2018 +0200
1.2 +++ b/docs/wiki/Restarted Fri Aug 17 11:41:28 2018 +0200
1.3 @@ -1,8 +1,16 @@
1.4 = Lichen Restarted =
1.5
1.6 -Originally, lots of work was being put in to support various Python features that are arguably superfluous. The realisation was had that a lot of effort was being made for little practical benefit by trying to support things that are, [[../Design|in the larger picture]], not that important. Consequently, Lichen was refocused on a smaller set of more useful Python features.
1.7 +Originally, lots of work was being put in to support various Python features
1.8 +that are arguably superfluous. The realisation was had that a lot of effort
1.9 +was being made for little practical benefit by trying to support things that
1.10 +are, [[../Design|in the larger picture]], not that important. Consequently,
1.11 +Lichen was refocused on a smaller set of more useful Python features.
1.12
1.13 -This document is of historical interest only, with the [[../Design|design]] and other documents attempting to communicate the results of this restarting effort. Some obsolete information is therefore preserved below. For example, attributes hold context information in the diagrams, but context information is now held in wrappers or is maintained separately within programs.
1.14 +This document is of historical interest only, with the [[../Design|design]]
1.15 +and other documents attempting to communicate the results of this restarting
1.16 +effort. Some obsolete information is therefore preserved below. For example,
1.17 +attributes hold context information in the diagrams, but context information
1.18 +is now held in wrappers or is maintained separately within programs.
1.19
1.20 Objectives:
1.21
1.22 @@ -10,7 +18,8 @@
1.23 * No importing triggered during module inspection
1.24 * All unresolved external references are set to `<depends>`
1.25 * Hierarchical module namespaces are not exposed in programs
1.26 - * Modules are independent: package hierarchies are not traversed when importing
1.27 + * Modules are independent: package hierarchies are not traversed when
1.28 + importing
1.29 * Nested scopes will be dropped
1.30 * If expressions and comprehensions will be dropped
1.31 * `self` is a reserved name and is optional in method parameter lists
1.32 @@ -19,40 +28,51 @@
1.33
1.34 == Names ==
1.35
1.36 -Names are locals, globals or built-ins. (Special names exist internally to support certain operations.)
1.37 +Names are locals, globals or built-ins. (Special names exist internally to
1.38 +support certain operations.)
1.39
1.40 -Locals inside functions are dynamic; locals outside functions are static, as are module globals. Built-ins are defined statically in the `__builtins__` package.
1.41 +Locals inside functions are dynamic; locals outside functions are static, as
1.42 +are module globals. Built-ins are defined statically in the `__builtins__`
1.43 +package.
1.44
1.45 == Imports ==
1.46
1.47 -Imports provide access to external references. The "leaf" module in a module path is the module returned by the statement.
1.48 +Imports provide access to external references. The "leaf" module in a module
1.49 +path is the module returned by the statement.
1.50
1.51 Indicate that module "compiler" is accessed via compiler...
1.52 +
1.53 {{{#!python numbers=disable
1.54 import compiler
1.55 }}}
1.56
1.57 Indicate that module "compiler" is accessed via comp...
1.58 +
1.59 {{{#!python numbers=disable
1.60 import compiler as comp
1.61 }}}
1.62
1.63 -Indicate that module "compiler.ast" is accessed via ast; module "compiler.transformer" is accessed via tr...
1.64 +Indicate that module "compiler.ast" is accessed via ast; module
1.65 +"compiler.transformer" is accessed via tr...
1.66 +
1.67 {{{#!python numbers=disable
1.68 import compiler.ast as ast, compiler.transformer as tr
1.69 }}}
1.70
1.71 Import compiler.ast, access Function...
1.72 +
1.73 {{{#!python numbers=disable
1.74 from compiler.ast import Function
1.75 }}}
1.76
1.77 Import compiler.ast, access Function as F...
1.78 +
1.79 {{{#!python numbers=disable
1.80 from compiler.ast import Function as F
1.81 }}}
1.82
1.83 -This causes some semantic differences with Python, with the most significant one being the following:
1.84 +This causes some semantic differences with Python, with the most significant
1.85 +one being the following:
1.86
1.87 {{{{#!table
1.88 '''Python''' || '''Lichen'''
1.89 @@ -108,10 +128,12 @@
1.90
1.91 Some notes:
1.92
1.93 - * Names not defined in a module and not declared in import statements are unresolved
1.94 + * Names not defined in a module and not declared in import statements are
1.95 + unresolved
1.96 * Modules are identified during inspection but are not loaded
1.97 * Instead, modules are added to a list and are imported later
1.98 - * Names imported from modules are set to `<depends>` (since the contents of modules will not generally be known)
1.99 + * Names imported from modules are set to `<depends>` (since the contents of
1.100 + modules will not generally be known)
1.101 * Names are resolved in a later activity
1.102
1.103 == Self ==
1.104 @@ -119,22 +141,37 @@
1.105 In Python:
1.106
1.107 * The `self` name provides access to the instance associated with a method
1.108 - * The instance is supplied by a "context", initialised when a method is obtained from an instance (or through other attribute accesses)
1.109 - * Upon invocation, any instance context must be assigned to the `self` parameter, provided the callable is a method
1.110 - * Meanwhile, any non-instance context is not assigned to the `self` parameter, which should be provided explicitly for class-accessed methods
1.111 - * Plain functions never expose `self` or have `self` initialised, even if they have been assigned to an instance
1.112 + * The instance is supplied by a "context", initialised when a method is
1.113 + obtained from an instance (or through other attribute accesses)
1.114 + * Upon invocation, any instance context must be assigned to the `self`
1.115 + parameter, provided the callable is a method
1.116 + * Meanwhile, any non-instance context is not assigned to the `self`
1.117 + parameter, which should be provided explicitly for class-accessed methods
1.118 + * Plain functions never expose `self` or have `self` initialised, even if
1.119 + they have been assigned to an instance
1.120
1.121 -Apart from tests for the nature of the context and the callable, the argument list is effectively variable.
1.122 +Apart from tests for the nature of the context and the callable, the argument
1.123 +list is effectively variable.
1.124
1.125 With `self` as a ubiquitous, hidden parameter:
1.126
1.127 - * The `self` name still provides access to the instance associated with a method
1.128 - * The instance is still supplied by a "context", initialised when a method is obtained from an instance (or through other attribute accesses)
1.129 - * Upon invocation, `self` is included in the argument list regardless of the nature of the callable
1.130 - * Class-accessed methods would have their class as context, following from the above, but `self` may not refer to a class: it must be an instance
1.131 - * To combine class-accessed methods with instance contexts, a special function is employed
1.132 + * The `self` name still provides access to the instance associated with a
1.133 + method
1.134 + * The instance is still supplied by a "context", initialised when a method is
1.135 + obtained from an instance (or through other attribute accesses)
1.136 + * Upon invocation, `self` is included in the argument list regardless of the
1.137 + nature of the callable
1.138 + * Class-accessed methods would have their class as context, following from
1.139 + the above, but `self` may not refer to a class: it must be an instance
1.140 + * To combine class-accessed methods with instance contexts, a special
1.141 + function is employed
1.142
1.143 -The argument list for each callable thus remains static, at a cost of allocating an extra argument that may not be used. (Various calling conventions for certain processor architectures employ potentially unused registers, anyway.) Note that a callable may support defaults, however, and thus any argument list may need extending to include default values for parameters without corresponding arguments.
1.144 +The argument list for each callable thus remains static, at a cost of
1.145 +allocating an extra argument that may not be used. (Various calling
1.146 +conventions for certain processor architectures employ potentially unused
1.147 +registers, anyway.) Note that a callable may support defaults, however, and
1.148 +thus any argument list may need extending to include default values for
1.149 +parameters without corresponding arguments.
1.150
1.151 {{{{#!table
1.152 '''Python''' || '''Without self'''
1.153 @@ -185,7 +222,13 @@
1.154
1.155 }}}}
1.156
1.157 -To avoid usage of `self` in undefined ways, only methods are able to use `self` and are not allowed to redefine it. Consequently, when invoking a callable, the context is set (where the callable is unknown until run-time; it is not set if compile-time knowledge indicates that it is not needed), and in situations where `self` is not permitted, the context is therefore safely ignored. Meanwhile, methods are always supplied with a context compatible with `self`.
1.158 +To avoid usage of `self` in undefined ways, only methods are able to use
1.159 +`self` and are not allowed to redefine it. Consequently, when invoking a
1.160 +callable, the context is set (where the callable is unknown until run-time; it
1.161 +is not set if compile-time knowledge indicates that it is not needed), and in
1.162 +situations where `self` is not permitted, the context is therefore safely
1.163 +ignored. Meanwhile, methods are always supplied with a context compatible with
1.164 +`self`.
1.165
1.166 || '''Callable''' || '''self''' || '''Remarks''' ||
1.167 || Class || context || context discarded and replaced by allocated instance ||
1.168 @@ -196,13 +239,24 @@
1.169 || Method (via class) || class as context || method not called (see "unbound methods") ||
1.170 || Method (via instance) || instance as context || `self` set to instance ||
1.171
1.172 -Note that the treatment of functions stored on classes differs from Python. In Python, such functions would become unbound methods (see below) and would employ their first parameter as an effective `self` parameter (regardless of name).
1.173 +Note that the treatment of functions stored on classes differs from Python. In
1.174 +Python, such functions would become unbound methods (see below) and would
1.175 +employ their first parameter as an effective `self` parameter (regardless of
1.176 +name).
1.177
1.178 == Unbound Methods ==
1.179
1.180 -Since methods acquired directly from classes ("unbound methods" in Python) are meant to be combined with an instance as context (using the `get_using` function), they must be uncallable until combined with the appropriate context, yet the same methods when acquired via instances ("bound methods" in Python) must be immediately callable.
1.181 +Since methods acquired directly from classes ("unbound methods" in Python) are
1.182 +meant to be combined with an instance as context (using the `get_using`
1.183 +function), they must be uncallable until combined with the appropriate
1.184 +context, yet the same methods when acquired via instances ("bound methods" in
1.185 +Python) must be immediately callable.
1.186
1.187 -To support the two different states of methods, the principal structure of a class has attributes referencing uncallable versions of its methods. Meanwhile, such uncallable methods reference callable versions and when instances are employed to access the class attributes, it is these callable versions that are retrieved. For example:
1.188 +To support the two different states of methods, the principal structure of a
1.189 +class has attributes referencing uncallable versions of its methods.
1.190 +Meanwhile, such uncallable methods reference callable versions and when
1.191 +instances are employed to access the class attributes, it is these callable
1.192 +versions that are retrieved. For example:
1.193
1.194 {{{#!graphviz
1.195 //format=svg
1.196 @@ -253,7 +307,12 @@
1.197 }
1.198 }}}
1.199
1.200 -Callable methods provide a reference to a callable routine in its special callable member, just as functions and classes do. Uncallable methods populate the callable member with a reference to an error routine. Thus, any attempt to call an uncallable method would cause the error routine to be invoked. In addition, uncallable methods reference the corresponding callable methods so that the callable methods can be found and referenced.
1.201 +Callable methods provide a reference to a callable routine in its special
1.202 +callable member, just as functions and classes do. Uncallable methods populate
1.203 +the callable member with a reference to an error routine. Thus, any attempt to
1.204 +call an uncallable method would cause the error routine to be invoked. In
1.205 +addition, uncallable methods reference the corresponding callable methods so
1.206 +that the callable methods can be found and referenced.
1.207
1.208 || '''Accessor''' || '''Provider''' || '''Attribute''' || '''Context''' || '''Summary''' ||
1.209 ||<|4> Instance ||<|4> Instance || Function || ''not used'' ||<|6> Preserve context ||
1.210 @@ -269,14 +328,30 @@
1.211 || Unbound method || Providing class ||
1.212 || Other || Same as value ||
1.213
1.214 -When obtaining an unbound method from an instance attribute, the context of the method attribute is provided. Indeed, the context is always preserved when accessing instance attributes.
1.215 +When obtaining an unbound method from an instance attribute, the context of
1.216 +the method attribute is provided. Indeed, the context is always preserved when
1.217 +accessing instance attributes.
1.218
1.219 -When obtaining an unbound method from a class attribute via an instance, the context of the method attribute is tested against the accessing instance. If compatible, an attribute is copied containing the instance as context and a callable method reference as value.
1.220 +When obtaining an unbound method from a class attribute via an instance, the
1.221 +context of the method attribute is tested against the accessing instance. If
1.222 +compatible, an attribute is copied containing the instance as context and a
1.223 +callable method reference as value.
1.224
1.225 -When obtaining an unbound method from a class attribute, the context of the method attribute is provided. Indeed, the context is always preserved when accessing class attributes directly.
1.226 +When obtaining an unbound method from a class attribute, the context of the
1.227 +method attribute is provided. Indeed, the context is always preserved when
1.228 +accessing class attributes directly.
1.229
1.230 -When combining an unbound method obtained from a class with an instance using `get_using`, the context of the method attribute is tested against the supplied instance. If compatible, an attribute is copied containing the instance as context and a callable method reference as value.
1.231 +When combining an unbound method obtained from a class with an instance using
1.232 +`get_using`, the context of the method attribute is tested against the
1.233 +supplied instance. If compatible, an attribute is copied containing the
1.234 +instance as context and a callable method reference as value.
1.235
1.236 === Functions as Unbound Methods ===
1.237
1.238 -Functions not defined within classes could be treated as unbound methods if they were to employ `self` (thus indicating that they are intended as methods). Such functions would then be recorded as uncallable in the module namespace, needing to be explicitly bound to a class using a special function. However, there appears to be limited utility in defining functions in this way, instead of defining them directly as methods, or instead of merely using such generic functions from existing methods.
1.239 +Functions not defined within classes could be treated as unbound methods if
1.240 +they were to employ `self` (thus indicating that they are intended as
1.241 +methods). Such functions would then be recorded as uncallable in the module
1.242 +namespace, needing to be explicitly bound to a class using a special function.
1.243 +However, there appears to be limited utility in defining functions in this
1.244 +way, instead of defining them directly as methods, or instead of merely using
1.245 +such generic functions from existing methods.