Class: Giblish::DocIdExtension::DocidProcessor

Inherits:
Asciidoctor::Extensions::Preprocessor
  • Object
show all
Defined in:
lib/giblish/docid/docid.rb

Overview

A preprocessor extension to the Asciidoctor engine that transforms all <<:docid:>> references found in the adoc source into the matching file reference.

It requiers a populated ‘id_2_node’ with => src_node before the first invokation of the ‘process’ method via Asciidoctor.

When running, it builds a publicly available ‘node_2_ids’ map.

Constant Summary collapse

DOCID_REF_REGEX =

The regex that matches docid references in files

/<<\s*:docid:\s*(.*?)>>/
PASS_MACRO_REGEX = 
/pass:\[.*\]/

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(opts) ⇒ DocidProcessor

required options:

id_2_node

{docid => src_node }

Raises:

  • (ArgumentError) 


84
85
86
87
88
89
90
91
92
 
# File 'lib/giblish/docid/docid.rb', line 84

def initialize(opts)
  raise ArgumentError, "Missing required option: :id_2_node!" unless opts.key?(:id_2_node)

  super(opts)
  @id_2_node = opts[:id_2_node]

  # init new keys in the hash with an empty array
  @node_2_ids = Hash.new { |h, k| h[k] = [] }
end

Instance Attribute Details

#node_2_ids ⇒ Object (readonly)

=> [referenced doc_id’s]



79
80
81
 
# File 'lib/giblish/docid/docid.rb', line 79

def node_2_ids
  @node_2_ids
end

Instance Method Details

#process(document, reader) ⇒ Object

This hook is called by Asciidoctor once for each document before Asciidoctor processes the adoc content.

It replaces references of the format <<:docid: ID-1234,Hello >> with references to a resolved relative path.



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/giblish/docid/docid.rb', line 103

def process(document, reader)
  # Add doc as a source dependency for doc ids
  gib_data = document.attributes["giblish-info"]
  if gib_data.nil?
    Giblog.logger.error "The docid preprocessor did not find required info in the doc attribute. (Doc title: #{document.title}"
    return reader
  end

  src_node = gib_data[:src_node]

  # Convert all docid refs to valid relative refs
  reader.lines.each do |line|
    # remove commented lines
    next if line.start_with?("//")

    @node_2_ids[src_node] += parse_line(line, src_node)
  end

  # we only care for one ref to a specific target, remove duplicates
  @node_2_ids[src_node] = @node_2_ids[src_node].uniq

  # the asciidoctor engine wants the reader back
  reader
end