Lichen

Annotated docs/wiki/Cache

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