Class: Giblish::DocidCollector

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

Overview

Parse all adoc files for :docid: attributes

Constant Summary collapse

ID_MIN_LENGTH =

The minimum number of characters required for a valid doc id

2
ID_MAX_LENGTH =

The maximum number of characters required for a valid doc id

10

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Class Attribute Details

.docid_cacheObject (readonly)

Returns the value of attribute docid_cache.


18
19
20
# File 'lib/giblish/docid.rb', line 18

def docid_cache
  @docid_cache
end

.docid_depsObject (readonly)

Returns the value of attribute docid_deps.


18
19
20
# File 'lib/giblish/docid.rb', line 18

def docid_deps
  @docid_deps
end

Class Method Details

.clear_cacheObject


20
21
22
# File 'lib/giblish/docid.rb', line 20

def clear_cache
  @docid_cache = {}
end

.clear_depsObject


24
25
26
# File 'lib/giblish/docid.rb', line 24

def clear_deps
  @docid_deps = {}
end

Instance Method Details

#add_source_dep(src_path) ⇒ Object

add a new source document to the docid_deps


59
60
61
62
63
# File 'lib/giblish/docid.rb', line 59

def add_source_dep(src_path)
  return if docid_deps.key? src_path

  docid_deps[src_path] = []
end

#parse_file(path) ⇒ Object

Check if a :docid: <id> entry exists in the header. According to www.methods.co.nz/asciidoc/userguide.html#X95 the header is optional, but if it exists it:

  • must start with a titel (=+ <My Title>)

  • ends with one or more blank lines

  • does not contain any blank line


47
48
49
50
51
52
53
54
55
56
# File 'lib/giblish/docid.rb', line 47

def parse_file(path)
  Giblog.logger.debug { "parsing file #{path} for docid..." }
  Giblish.process_header_lines_from_file(path) do |line|
    m = /^:docid: +(.*)$/.match(line)
    if m
      # There is a docid defined, cache the path and doc id
      validate_and_add m[1], path
    end
  end
end

#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.


70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
# File 'lib/giblish/docid.rb', line 70

def process(document, reader)
  # Add doc as a source dependency for doc ids
  src_path = document.attributes["docfile"]

  # Note: the nil check is there to prevent us adding generated
  # asciidoc docs that does not exist in the file system (e.g. the
  # generated index pages). This is a bit hackish and should maybe be
  # done differently
  return if src_path.nil?

  add_source_dep src_path

  # Convert all docid refs to valid relative refs
  reader.lines.each do |line|
    line.gsub!(/<<\s*:docid:\s*(.*?)>>/) do |_m|
      # parse the ref
      target_id, section, display_str =
        parse_doc_id_ref Regexp.last_match(1)

      # The result is a valid ref in the form
      # <<target_doc.adoc#[section][,display_str]>>
      Giblog.logger.debug { "Replace docid ref in doc #{src_path}..." }
      if docid_cache.key? target_id
        # add the referenced doc id as a target dependency of this document
        docid_deps[src_path] << target_id
        docid_deps[src_path] = docid_deps[src_path].uniq

        # resolve the doc id ref to a valid relative path
        "<<#{get_rel_path(src_path, target_id)}##{section}#{display_str}>>"
      else
        "<<UNKNOWN_DOC, Could not resolve doc id reference !!!>>"
      end
    end
  end
  reader
end