1.1 --- a/docs/wiki/Structure Sat Jul 21 23:19:26 2018 +0200
1.2 +++ b/docs/wiki/Structure Fri Aug 17 11:41:28 2018 +0200
1.3 @@ -1,12 +1,28 @@
1.4 = Program Structure =
1.5
1.6 -A program consists of a number of '''modules''' with each module providing its own namespace. Modules can be organised within '''packages''' which define a hierarchical relationship between them. However, the relationship between modules is not automatically exposed within the program: it is more appropriate to consider modules as independent entities that have a particular naming scheme.
1.7 +A program consists of a number of '''modules''' with each module providing its
1.8 +own namespace. Modules can be organised within '''packages''' which define a
1.9 +hierarchical relationship between them. However, the relationship between
1.10 +modules is not automatically exposed within the program: it is more
1.11 +appropriate to consider modules as independent entities that have a particular
1.12 +naming scheme.
1.13
1.14 -Within each module a hierarchy of namespaces is provided by '''classes''', with each class potentially containing other classes, and so on. Also appearing within modules and classes are '''functions''', with those appearing within classes being regarded as '''methods'''.
1.15 +Within each module a hierarchy of namespaces is provided by '''classes''',
1.16 +with each class potentially containing other classes, and so on. Also
1.17 +appearing within modules and classes are '''functions''', with those appearing
1.18 +within classes being regarded as '''methods'''.
1.19
1.20 -Function namespaces are considered separately from module and class namespaces and are not considered part of the general namespace hierarchy, instead merely appearing as objects at the edges of that hierarchy. Functions may also be defined within functions, and such inner functions will be referenced within their parent functions, but no hierarchical relationship will exist between their namespaces.
1.21 +Function namespaces are considered separately from module and class namespaces
1.22 +and are not considered part of the general namespace hierarchy, instead merely
1.23 +appearing as objects at the edges of that hierarchy. Functions may also be
1.24 +defined within functions, and such inner functions will be referenced within
1.25 +their parent functions, but no hierarchical relationship will exist between
1.26 +their namespaces.
1.27
1.28 -Thus, a program provides a static namespace hierarchy consisting of modules containing classes (containing other classes, and so on) plus functions. Objects residing within namespaces are accessed via '''attributes''' of those namespaces.
1.29 +Thus, a program provides a static namespace hierarchy consisting of modules
1.30 +containing classes (containing other classes, and so on) plus functions.
1.31 +Objects residing within namespaces are accessed via '''attributes''' of those
1.32 +namespaces.
1.33
1.34 {{{{#!table
1.35 {{{#!graphviz
1.36 @@ -88,7 +104,9 @@
1.37
1.38 == Referencing the Structure ==
1.39
1.40 -Each part of the structure is catalogued using an '''object path''', indicating its location in the structure hierarchy, and a reference indicating its nature and origin. For example:
1.41 +Each part of the structure is catalogued using an '''object path''',
1.42 +indicating its location in the structure hierarchy, and a reference indicating
1.43 +its nature and origin. For example:
1.44
1.45 || '''Object Path''' || '''Reference''' || '''Explanation''' ||
1.46 || `M.A` || `<class>:M.A` || The definition of class `A` in module `M` ||
1.47 @@ -99,17 +117,36 @@
1.48 || `__main__.M` || `<module>:M` || A reference to module `M` ||
1.49 || `__main__.counter` || `<var>` || An undetermined object called `counter` in the `__main__` module ||
1.50
1.51 -The reference therefore expresses the '''kind''' of object (class, function, instance, module or undetermined variable), possibly accompanied by an object type, and also possibly accompanied by an alias indicating where the reference was obtained.
1.52 +The reference therefore expresses the '''kind''' of object (class, function,
1.53 +instance, module or undetermined variable), possibly accompanied by an object
1.54 +type, and also possibly accompanied by an alias indicating where the reference
1.55 +was obtained.
1.56
1.57 == Classes ==
1.58
1.59 -Classes are regarded as statically-defined objects, meaning that they are only evaluated once and must not be defined within conditional sections or within functions. Base classes must be expressed using readily-identifiable class names, since any potential ambiguity or uncertainty with the identity of base classes could result in a class inheritance hierarchy that is effectively dynamic.
1.60 +Classes are regarded as statically-defined objects, meaning that they are only
1.61 +evaluated once and must not be defined within conditional sections or within
1.62 +functions. Base classes must be expressed using readily-identifiable class
1.63 +names, since any potential ambiguity or uncertainty with the identity of base
1.64 +classes could result in a class inheritance hierarchy that is effectively
1.65 +dynamic.
1.66
1.67 -When '''instantiated''', classes provide '''instances''' that provide the attributes of each class's namespace plus any '''inherited''' attributes from base classes that would not be provided by the class itself. In addition, instances provide their own instance attributes.
1.68 +When '''instantiated''', classes provide '''instances''' that provide the
1.69 +attributes of each class's namespace plus any '''inherited''' attributes from
1.70 +base classes that would not be provided by the class itself. In addition,
1.71 +instances provide their own instance attributes.
1.72
1.73 == Functions ==
1.74
1.75 -Functions are regarded as statically-defined objects, but they may be defined either with names within other named functions or as '''lambdas''' (functions without names) within named functions or other lambdas. Thus, unlike classes, functions may be defined once but replicated many times, each time with different accompanying state information. Such state information needs to be provided via default parameters: it is not detected and propagated automatically. Closures are not supported: any state from enclosing scopes must be supplied at the point of definition of a function; it is not acquired from outer functions by name.
1.76 +Functions are regarded as statically-defined objects, but they may be defined
1.77 +either with names within other named functions or as '''lambdas''' (functions
1.78 +without names) within named functions or other lambdas. Thus, unlike classes,
1.79 +functions may be defined once but replicated many times, each time with
1.80 +different accompanying state information. Such state information needs to be
1.81 +provided via default parameters: it is not detected and propagated
1.82 +automatically. Closures are not supported: any state from enclosing scopes
1.83 +must be supplied at the point of definition of a function; it is not acquired
1.84 +from outer functions by name.
1.85
1.86 {{{#!python numbers=disable
1.87 def outer(a):
1.88 @@ -125,11 +162,17 @@
1.89
1.90 === Lambdas ===
1.91
1.92 -Lambdas are given special names for the purposes of identification within the program structure, being named relative to the scope in which they are defined. For example, the first lambda appearing within module `N` would have an object path of `N.$l0`, and a subsequent lambda within the same scope would have an object path of `N.$l1`. Lambdas may appear within classes and functions, including lambdas themselves. For example:
1.93 +Lambdas are given special names for the purposes of identification within the
1.94 +program structure, being named relative to the scope in which they are
1.95 +defined. For example, the first lambda appearing within module `N` would have
1.96 +an object path of `N.$l0`, and a subsequent lambda within the same scope would
1.97 +have an object path of `N.$l1`. Lambdas may appear within classes and
1.98 +functions, including lambdas themselves. For example:
1.99
1.100 {{{#!python numbers=disable
1.101 def f(x):
1.102 return lambda y, x=x: lambda z, x=x, y=y: (x, y, z)
1.103 }}}
1.104
1.105 -Here, within a module `M`, the outer lambda would have the object path `M.f.$l0` whereas the inner lambda would have the object path `M.f.$l0.$l0`.
1.106 +Here, within a module `M`, the outer lambda would have the object path
1.107 +`M.f.$l0` whereas the inner lambda would have the object path `M.f.$l0.$l0`.