Class TopicRegistry
java.lang.Object
network.ike.docs.plugin.registry.TopicRegistry
The generated topic registry: every AsciiDoc file under a scan root, parsed
by
TopicHeader, in the shape IKE-TOPIC-REGISTRY.md gives
topic-registry.yaml: topics grouped into domains by the prefix of
their id, each with the registry's field names (id, file,
title, type, keywords, status,
char-count, related, summary), then what a build can
add on top: assemblies and plain files with their document attributes, the
findings the headers raise, and a generation stamp. This is the registry's
build-time revision: generated from the files on every run where, before it,
the same registry was kept by hand at src/docs/asciidoc/topic-registry.yaml.
Pure Java with no Maven dependency, so it is testable without a build;
TopicRegistryMojo is the wiring around it.- Since:
- 109
-
Nested Class Summary
Nested Classes -
Field Summary
FieldsModifier and TypeFieldDescriptionDirectory names never entered by the scan. -
Method Summary
Modifier and TypeMethodDescriptionstatic List<TopicHeader> Add files to an existing registry, or refresh their entries, without rescanning the roots: each file is parsed alone, placed in its domain in id order, counted, and checked for a duplicate id against the ids the registry already holds.static StringThe domain a topic belongs to: the part of its id before the first hyphen, the{domain-prefix}-{slug}rule ofIKE-TOPIC-REGISTRY.md.Read a registry written byyaml(Map)back into its model.model(List<TopicRegistry.Scan> scans, Path base, Instant now) The registry as an ordered map, ready for YAML: the schema's keys first (registry-version,generated,topic-count,domainswith theirtopics), thenassemblies,other-filesandfindings.otherEntry(TopicHeader o, String fileValue) An assembly or plain file: its path, title, document attributes and include count.static TopicRegistry.ScanScan one root.static TopicRegistry.ScanScan from one root file: the file and every.adocfile it reaches throughinclude::lines, followed recursively and resolved relative to the including file as the AsciiDoc preprocessor does.topicEntry(TopicHeader t, String fileValue) One topic in the registry's field order (id,file,title,type,keywords,status,char-count,dependencies,related,summary,supersedes,notes), then what the header adds: provenance, scope note, citation, license, the anchor and header verdicts, unknown:topic-*:attributes underextra, document attributes, and the include count.tree(TopicRegistry.Scan scan, Path base) The scan as an indented tree for the build log: directories, then each file with its id, type and status, and the files that are not topics with their include counts.static StringRender the registry model as YAML in the registry's block style: two-space indent, sequences indented under their key, one scalar per line.static StringRender a model as YAML in the registry's block style under a given header comment, the shape shared by the registry, the term index and the package manifest.
-
Field Details
-
SKIPPED_DIRS
-
-
Method Details
-
scan
Scan one root.- Parameters:
root- the directory to scanmaxFiles- the most.adocfiles the scan will accept- Returns:
- the scan result
- Throws:
IOException- if the tree cannot be readIllegalStateException- if the root holds more thanmaxFiles.adocfiles
-
scanFrom
Scan from one root file: the file and every.adocfile it reaches throughinclude::lines, followed recursively and resolved relative to the including file as the AsciiDoc preprocessor does. Files under the root that are not reached are left out. An include whose target cannot be resolved statically (an attribute reference, an absolute path, a URI, a path above the root) or that names a missing file is a finding; a target that is not an.adocfile (a diagram, a CSV) is passed over. Each file is read once, so an include cycle ends.- Parameters:
root- the scan root; registry paths are relative to itrootFile- the.adocfile to start from, underroot- Returns:
- the scan result
- Throws:
IOException- if a file cannot be readIllegalArgumentException- ifrootFileis not an.adocfile underroot
-
domainOf
-
model
The registry as an ordered map, ready for YAML: the schema's keys first (registry-version,generated,topic-count,domainswith theirtopics), thenassemblies,other-filesandfindings. Topics are grouped bydomainand sorted by id. A file path is relative to its root, prefixed with the root when several roots were scanned.- Parameters:
scans- the scanned rootsbase- the directory root paths are made relative to (the module base directory)now- the generation instant- Returns:
- the registry model
-
yaml
Render the registry model as YAML in the registry's block style: two-space indent, sequences indented under their key, one scalar per line. Written directly rather than through SnakeYAML's emitter, which cost 40 percent of a large run and about 45 ms of class loading on every small one; the output round-trips throughload(Path)unchanged.- Parameters:
model- the registry model frommodel(List, Path, Instant)- Returns:
- the YAML text
-
yaml
Render a model as YAML in the registry's block style under a given header comment, the shape shared by the registry, the term index and the package manifest.- Parameters:
model- the model, an ordered map of scalars, lists and mapscomment- the header comment, without the leading#- Returns:
- the YAML text
-
tree
The scan as an indented tree for the build log: directories, then each file with its id, type and status, and the files that are not topics with their include counts.- Parameters:
scan- the scanbase- the directory the root is shown relative to- Returns:
- the lines, without newlines
-
load
Read a registry written byyaml(Map)back into its model.- Parameters:
registryFile- the generated registry file- Returns:
- the model, with the same shape
model(List, Path, Instant)produces - Throws:
IOException- if the file cannot be read or is not a generated registry
-
add
public static List<TopicHeader> add(Map<String, Object> model, Path base, List<Path> files, Instant now) throws IOExceptionAdd files to an existing registry, or refresh their entries, without rescanning the roots: each file is parsed alone, placed in its domain in id order, counted, and checked for a duplicate id against the ids the registry already holds. An entry for the same file is replaced, so a re-ingested document is safe to add again. Files the registry lists but that no longer exist are not noticed here; a full scan is.- Parameters:
model- the registry model, frommodel(List, Path, Instant)orload(Path); updated in placebase- the module base directory the registry's roots are relative tofiles- the files to add, relative tobaseor absolute; each must be an.adocfile under one of the registry's rootsnow- the update instant, recorded asgenerated- Returns:
- the parsed headers of the added files, in the order given
- Throws:
IOException- if a file cannot be readIllegalArgumentException- if a file is missing, is not AsciiDoc, or lies under none of the registry's roots
-
otherEntry
An assembly or plain file: its path, title, document attributes and include count.- Parameters:
o- the parsed header of a file that is not a topicfileValue- the file path to record- Returns:
- the registry entry
-
topicEntry
One topic in the registry's field order (id,file,title,type,keywords,status,char-count,dependencies,related,summary,supersedes,notes), then what the header adds: provenance, scope note, citation, license, the anchor and header verdicts, unknown:topic-*:attributes underextra, document attributes, and the include count. Shared withidoc:diff, which generates the registry for each side of a comparison in this same shape.- Parameters:
t- the parsed topic headerfileValue- the file path to record- Returns:
- the registry entry
-