TermIndex.java
package network.ike.docs.plugin.registry;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
/**
* The term index {@code IKE-INDEX.md} and {@code IKE-TOPIC-REGISTRY.md}
* describe, {@code term-index.yaml}: the reverse mapping from the index
* terms a topic marks ({@code indexterm:[primary, secondary]},
* {@code indexterm2:[term]}, {@code ((term))}, {@code (((primary, secondary)))})
* to the topics that mark them. The registry's keywords say what a topic
* is about; its index terms say what it discusses.
*
* <p>Terms are collected once, when a topic is parsed, and kept on its
* registry entry as {@code index-terms}, each level joined with
* {@code " > "}; the index is then derived from the registry alone, so an
* incremental registry run never reopens a file to rebuild it
* (IKE-Network/ike-issues#1341).
*
* @since 136
*/
public final class TermIndex {
/** The key under which a level lists the topics indexed at it. */
public static final String TOPICS_KEY = "_topics";
/** The separator between the levels of a term as the registry records it. */
public static final String LEVEL_SEPARATOR = " > ";
/** A macro, group 1, or an inline term, groups 2 (the concealing third parenthesis) and 3. */
private static final Pattern TERM = Pattern.compile(
"(?<!\\w)indexterm2?:\\[([^\\]]*)]|\\(\\((\\(?)([^()]+?)\\)?\\)\\)");
private TermIndex() {
}
/**
* The index terms one file marks, in order of appearance, each as its
* levels joined with {@link #LEVEL_SEPARATOR}; a term marked twice is
* listed once. A visible term, {@code ((term))}, is one level; a
* concealed one, {@code (((primary, secondary)))}, splits on commas as
* {@code indexterm:[]} does. Lines that are comments are passed over.
*
* @param content the file content
* @return the terms, empty when the file marks none
*/
public static List<String> termsOf(String content) {
List<String> terms = new ArrayList<>();
for (String line : content.lines().toList()) {
if (line.startsWith("//")) {
continue;
}
Matcher term = TERM.matcher(line);
while (term.find()) {
if (term.group(1) != null) {
add(terms, levels(term.group(1)));
} else if (term.group(2).isEmpty()) {
add(terms, List.of(term.group(3).strip()));
} else {
add(terms, levels(term.group(3)));
}
}
}
return List.copyOf(terms);
}
private static List<String> levels(String list) {
List<String> levels = new ArrayList<>();
for (String part : list.split(",")) {
String level = part.strip();
if (!level.isEmpty()) {
levels.add(level);
}
}
return levels;
}
private static void add(List<String> terms, List<String> levels) {
if (levels.isEmpty()) {
return;
}
String term = String.join(LEVEL_SEPARATOR, levels);
if (!terms.contains(term)) {
terms.add(term);
}
}
/**
* The term index as an ordered map, ready for YAML, from a registry
* model whose topic entries carry {@code index-terms}: {@code generated},
* {@code term-count}, then {@code terms}, a tree of levels in
* alphabetical order, each level with its {@code _topics} in id order
* and its sub-levels after.
*
* @param registry the registry model, from {@code TopicRegistry.model}
* or {@code TopicRegistry.load}
* @param now the generation instant, recorded as a date
* @return the term index model
*/
@SuppressWarnings("unchecked")
public static Map<String, Object> model(Map<String, Object> registry, Instant now) {
TreeMap<String, Object> tree = new TreeMap<>();
int[] count = {0};
for (Object d : (List<Object>) registry.getOrDefault("domains", List.of())) {
Map<String, Object> domain = (Map<String, Object>) d;
for (Object t : (List<Object>) domain.getOrDefault("topics", List.of())) {
Map<String, Object> topic = (Map<String, Object>) t;
String id = String.valueOf(topic.get("id"));
for (Object term : (List<Object>) topic.getOrDefault("index-terms", List.of())) {
TreeMap<String, Object> level = tree;
for (String part : String.valueOf(term).split(Pattern.quote(LEVEL_SEPARATOR))) {
level = (TreeMap<String, Object>) level.computeIfAbsent(part, k -> {
count[0]++;
return new TreeMap<>();
});
}
List<String> topics = (List<String>) level.computeIfAbsent(TOPICS_KEY, k -> new ArrayList<>());
if (!topics.contains(id)) {
topics.add(id);
}
}
}
}
Map<String, Object> model = new LinkedHashMap<>();
model.put("generated", now.atOffset(ZoneOffset.UTC).toLocalDate().toString());
model.put("term-count", count[0]);
model.put("terms", ordered(tree, false));
return model;
}
/** A level with {@code _topics} first (the root has none), then its sub-levels in order, each sorted. */
@SuppressWarnings("unchecked")
private static Map<String, Object> ordered(TreeMap<String, Object> level, boolean withTopics) {
Map<String, Object> out = new LinkedHashMap<>();
if (withTopics) {
List<String> topics = (List<String>) level.get(TOPICS_KEY);
List<String> sorted = topics == null ? new ArrayList<>() : new ArrayList<>(topics);
sorted.sort(null);
out.put(TOPICS_KEY, sorted);
}
for (Map.Entry<String, Object> e : level.entrySet()) {
if (!e.getKey().equals(TOPICS_KEY)) {
out.put(e.getKey(), ordered((TreeMap<String, Object>) e.getValue(), true));
}
}
return out;
}
/**
* Render the term index as YAML, in the registry's block style.
*
* @param model the model from {@link #model}
* @return the YAML text
*/
public static String yaml(Map<String, Object> model) {
return TopicRegistry.yaml(model, "term-index.yaml, generated by idoc:topic-registry from the index terms. Do not edit.");
}
}