Lichen

Annotated docs/wiki/Cache

884:c34258c62630
861:f745d151a441
2019-02-01 Paul Boddie file changeset files shortlog Fixed instance definitions to use the correct size identifiers, not those for classes. This fixes instance size calculations and instance allocation.
paul@810 1 
= Inspection Cache Files =
paul@810 2 
 
 paul@861      3 
The results of inspection for each module are written out to cache files, and
 
 paul@861      4 
these files should be able to provide all the information that is gathered
 
 paul@861      5 
during inspection without having to inspect the source code again. One minor
 
 paul@861      6 
benefit of using cached data, instead of having to parse and inspect the
 
 paul@861      7 
source code for a given module, is that of a slightly reduced processing time
 
 paul@861      8 
for the inspection activity. However, an arguably greater benefit is that of
 
 paul@861      9 
being able to see the outcome of the activity as a summary of accumulated
 
 paul@861     10 
data.
 
 paul@810     11 
 
 paul@810     12 
Each cache file has the following general format:
 
 paul@810     13 
 
 paul@810     14 
{{{{#!table
 
 paul@810     15 
{{{
 
 paul@810     16 
<filename>
 
 paul@810     17 
 
 paul@810     18 
}}}
 
 paul@810     19 
|| The main program filename
 
 paul@810     20 
==
 
 paul@810     21 
{{{
 
 paul@810     22 
imports:
 
 paul@810     23 
<required module-names>
 
 paul@810     24 
<possibly-required module-names>
 
 paul@810     25 
 
 paul@810     26 
}}}
 
 paul@810     27 
||
 
 paul@810     28 
 * Comma-separated list of modules explicitly imported by this module
 
 paul@810     29 
 * Comma-separated list of modules implicitly imported by this module
 
 paul@810     30 
==
 
 paul@810     31 
{{{
 
 paul@810     32 
deferred:
 
 paul@810     33 
<deferred references>
 
 paul@810     34 
 
 paul@810     35 
}}}
 
 paul@810     36 
|| Comma-separated list of references not identified within this module
 
 paul@810     37 
==
 
 paul@810     38 
{{{
 
 paul@810     39 
special:
 
 paul@810     40 
<special-name> <reference> <qualified-names>
 
 paul@810     41 
...
 
 paul@810     42 
 
 paul@810     43 
}}}
 
 paul@861     44 
|| Special name and corresponding reference plus comma-separated list of usage
 
 paul@861     45 
.. namespaces
 
 paul@810     46 
==
 
 paul@810     47 
{{{
 
 paul@810     48 
members:
 
 paul@810     49 
<qualified-name> <reference>
 
 paul@810     50 
...
 
 paul@810     51 
 
 paul@810     52 
}}}
 
 paul@810     53 
|| Reference for each member of the static namespace hierarchy of the module
 
 paul@810     54 
==
 
 paul@810     55 
{{{
 
 paul@810     56 
class relationships:
 
 paul@810     57 
<qualified-class-name> <base-class-references>
 
 paul@810     58 
...
 
 paul@810     59 
 
 paul@810     60 
}}}
 
 paul@810     61 
|| Comma-separated list of base classes for each class
 
 paul@810     62 
==
 
 paul@810     63 
{{{
 
 paul@810     64 
instance attributes:
 
 paul@810     65 
<qualified-class-name> <instance-attribute-names>
 
 paul@810     66 
...
 
 paul@810     67 
 
 paul@810     68 
}}}
 
 paul@810     69 
|| Comma-separated list of instance attributes for each class
 
 paul@810     70 
==
 
 paul@810     71 
{{{
 
 paul@810     72 
instance attribute constants:
 
 paul@810     73 
<qualified-class-name> <attribute-name> <reference>
 
 paul@810     74 
...
 
 paul@810     75 
 
 paul@810     76 
}}}
 
 paul@810     77 
|| Reference for the named constant instance attribute in the given class
 
 paul@810     78 
==
 
 paul@810     79 
{{{
 
 paul@810     80 
names used:
 
 paul@810     81 
<qualified-class/function/module-name> <names>
 
 paul@810     82 
...
 
 paul@810     83 
 
 paul@810     84 
}}}
 
 paul@810     85 
|| Comma-separated list of names in each namespace
 
 paul@810     86 
==
 
 paul@810     87 
{{{
 
 paul@810     88 
name references:
 
 paul@810     89 
<qualified-name> <reference>
 
 paul@810     90 
...
 
 paul@810     91 
 
 paul@810     92 
}}}
 
 paul@810     93 
|| Correspondence between name and resolved identity
 
 paul@810     94 
==
 
 paul@810     95 
{{{
 
 paul@810     96 
initialised-names:
 
 paul@810     97 
<qualified-name> <definition-version> <reference>
 
 paul@810     98 
...
 
 paul@810     99 
 
 paul@810    100 
}}}
 
 paul@810    101 
|| Identity of a given definition of a name
 
 paul@810    102 
==
 
 paul@810    103 
{{{
 
 paul@810    104 
aliased-names:
 
 paul@810    105 
<qualified-name> <definition-version> <original-name> <attribute-names> <access-number>
 
 paul@810    106 
...
 
 paul@810    107 
 
 paul@810    108 
}}}
 
 paul@810    109 
|| Name definition by access operation
 
 paul@810    110 
==
 
 paul@810    111 
{{{
 
 paul@810    112 
function parameters:
 
 paul@810    113 
<qualified-function-name> <parameter-names>
 
 paul@810    114 
...
 
 paul@810    115 
 
 paul@810    116 
}}}
 
 paul@810    117 
|| Comma-separated list of parameters for each function
 
 paul@810    118 
==
 
 paul@810    119 
{{{
 
 paul@810    120 
function default parameters:
 
 paul@810    121 
<qualified-function-name> <parameter-names-with-defaults>
 
 paul@810    122 
...
 
 paul@810    123 
 
 paul@810    124 
}}}
 
 paul@810    125 
||
 
 paul@861    126 
Comma-separated parameter definitions for each function, with each definition
 
 paul@861    127 
being of the form...
 
 paul@810    128 
{{{
 
 paul@810    129 
<name>=<references>
 
 paul@810    130 
}}}
 
 paul@810    131 
...and with the references being semicolon-separated
 
 paul@810    132 
==
 
 paul@810    133 
{{{
 
 paul@810    134 
function locals:
 
 paul@810    135 
<qualified-function-name> <local-variable-name> <reference>
 
 paul@810    136 
...
 
 paul@810    137 
 
 paul@810    138 
}}}
 
 paul@810    139 
|| Identity of the given local name in the given class
 
 paul@810    140 
==
 
 paul@810    141 
{{{
 
 paul@810    142 
scope globals:
 
 paul@810    143 
<qualified-function-name> <global-variable-names>
 
 paul@810    144 
...
 
 paul@810    145 
 
 paul@810    146 
}}}
 
 paul@810    147 
|| Comma-separated list of global names in each namespace
 
 paul@810    148 
==
 
 paul@810    149 
{{{
 
 paul@810    150 
attribute usage:
 
 paul@810    151 
<qualified-name> <local/global/qualified-variable-name> <usages>
 
 paul@810    152 
...
 
 paul@810    153 
 
 paul@810    154 
}}}
 
 paul@810    155 
||
 
 paul@861    156 
Attribute usage details for the given name in the given namespace, with usages
 
 paul@861    157 
being a semicolon-separated list of usage alternatives, each being a
 
 paul@861    158 
comma-separated list of attribute names or {} (meaning no attribute names
 
 paul@861    159 
used), attribute names employing ! if invoked
 
 paul@810    160 
==
 
 paul@810    161 
{{{
 
 paul@810    162 
attribute accesses:
 
 paul@810    163 
<qualified-name> <attribute-chains>
 
 paul@810    164 
...
 
 paul@810    165 
 
 paul@810    166 
}}}
 
 paul@810    167 
|| Comma-separated list of attribute chains used on anonymous/unidentified objects
 
 paul@810    168 
==
 
 paul@810    169 
{{{
 
 paul@810    170 
constant accesses:
 
 paul@810    171 
<qualified-function-name> <attribute-chain> <reference> <remaining attribute-chain>
 
 paul@810    172 
...
 
 paul@810    173 
 
 paul@810    174 
}}}
 
 paul@861    175 
||
 
 paul@861    176 
Identity of the given attribute chain in the given namespace, with any
 
 paul@861    177 
unresolved attribute chain provided
 
 paul@810    178 
==
 
 paul@810    179 
{{{
 
 paul@810    180 
attribute access usage:
 
 paul@810    181 
<qualified-function-name> <local/global-variable-name> <attribute-name> <definition-versions>
 
 paul@810    182 
...
 
 paul@810    183 
 
 paul@810    184 
}}}
 
 paul@861    185 
||
 
 paul@861    186 
Indicates, for each access involving the given name and first attribute name
 
 paul@861    187 
in the given namespace, the definitions that may provide the name
 
 paul@810    188 
==
 
 paul@810    189 
{{{
 
 paul@810    190 
attribute access-modifiers:
 
 paul@810    191 
<qualified-function-name> <local/global-variable-name> <attribute-name> <access-modifiers>
 
 paul@810    192 
...
 
 paul@810    193 
 
 paul@810    194 
}}}
 
 paul@861    195 
||
 
 paul@861    196 
Indicates, for accesses involving the given name and first attribute name in
 
 paul@861    197 
the given namespace, the modifiers applying to each access, where = indicates
 
 paul@861    198 
assignment, ! indicates invocation, and _ indicates access
 
 paul@810    199 
==
 
 paul@810    200 
{{{
 
 paul@810    201 
constant literals:
 
 paul@810    202 
<qualified-name> <value-type> <encoding> <constant-literal>
 
 paul@810    203 
...
 
 paul@810    204 
 
 paul@810    205 
}}}
 
 paul@861    206 
||
 
 paul@861    207 
Describes a constant literal in the given namespace having the indicated type,
 
 paul@861    208 
encoding (if a string), and value
 
 paul@810    209 
==
 
 paul@810    210 
{{{
 
 paul@810    211 
constant values:
 
 paul@810    212 
<qualified-name> <value-type> <encoding> <constant-literal>
 
 paul@810    213 
...
 
 paul@810    214 
 
 paul@810    215 
}}}
 
 paul@810    216 
|| Describes a constant literal identified using a locally-qualified name
 
 paul@810    217 
==
 
 paul@810    218 
{{{
 
 paul@810    219 
exception namespaces:
 
 paul@810    220 
<qualified-names>
 
 paul@810    221 
...
 
 paul@810    222 
}}}
 
 paul@810    223 
|| Comma-separated list of namespaces that need to handle exceptions
 
 paul@810    224 
}}}}
 
 paul@810    225 
 
 paul@810    226 
A qualified name is a name prefixed with the namespace it appears in.