Class: MarkdownLint::Doc

Inherits:
Object
  • Object
show all
Defined in:
lib/mdl/doc.rb

Overview

Representation of the markdown document passed to rule checks

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(text, ignore_front_matter = false) ⇒ Doc

Create a new document given a string containing the markdown source



29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/mdl/doc.rb', line 29

def initialize(text, ignore_front_matter = false)
  regex = /\A---\n(.*?)---\n\n?/m
  if ignore_front_matter && regex.match(text)
    @front_matter = regex.match(text).to_s
    @offset = @front_matter.count("\n")
    text.sub!(regex, '')
  else
    @front_matter = ''
    @offset = 0
  end
  # The -1 is to cause split to preserve an extra entry in the array so we
  # can tell if there's a final newline in the file or not.
  @lines = text.split(/\R/, -1)
  @parsed = Kramdown::Document.new(text, :input => 'MarkdownLint')
  @elements = @parsed.root.children
  add_annotations(@elements)
end

Instance Attribute Details

#elements ⇒ Object (readonly)

A list of raw markdown source lines. Note that the list is 0-indexed, while line numbers in the parsed source are 1-indexed, so you need to subtract 1 from a line number to get the correct line. The element_line* methods take care of this for you.



14
15
16
 
# File 'lib/mdl/doc.rb', line 14

def elements
  @elements
end

#front_matter ⇒ Object (readonly)

A list of raw markdown source lines. Note that the list is 0-indexed, while line numbers in the parsed source are 1-indexed, so you need to subtract 1 from a line number to get the correct line. The element_line* methods take care of this for you.



14
15
16
 
# File 'lib/mdl/doc.rb', line 14

def front_matter
  @front_matter
end

#lines ⇒ Object (readonly)

A list of raw markdown source lines. Note that the list is 0-indexed, while line numbers in the parsed source are 1-indexed, so you need to subtract 1 from a line number to get the correct line. The element_line* methods take care of this for you.



14
15
16
 
# File 'lib/mdl/doc.rb', line 14

def lines
  @lines
end

#offset ⇒ Object (readonly)

A list of raw markdown source lines. Note that the list is 0-indexed, while line numbers in the parsed source are 1-indexed, so you need to subtract 1 from a line number to get the correct line. The element_line* methods take care of this for you.



14
15
16
 
# File 'lib/mdl/doc.rb', line 14

def offset
  @offset
end

#parsed ⇒ Object (readonly)

A list of raw markdown source lines. Note that the list is 0-indexed, while line numbers in the parsed source are 1-indexed, so you need to subtract 1 from a line number to get the correct line. The element_line* methods take care of this for you.



14
15
16
 
# File 'lib/mdl/doc.rb', line 14

def parsed
  @parsed
end

Class Method Details

.new_from_file(filename, ignore_front_matter = false) ⇒ Object

Alternate ‘constructor’ passing in a filename



50
51
52
53
54
55
56
57
58
59
 
# File 'lib/mdl/doc.rb', line 50

def self.new_from_file(filename, ignore_front_matter = false)
  if filename == '-'
    new($stdin.read.scrub, ignore_front_matter)
  else
    new(
      File.read(filename, :encoding => 'UTF-8').scrub,
      ignore_front_matter,
    )
  end
end

Instance Method Details

#element_line(element) ⇒ Object

Returns the actual source line for a given element. You can pass in an element object or an options hash here. This is useful if you need to examine the source line directly for your rule to make use of information that isn’t present in the parsed document.



140
141
142
 
# File 'lib/mdl/doc.rb', line 140

def element_line(element)
  @lines[element_linenumber(element) - 1]
end

#element_linenumber(element) ⇒ Object

Returns the line number a given element is located on in the source file. You can pass in either an element object or an options hash here.



129
130
131
132
 
# File 'lib/mdl/doc.rb', line 129

def element_linenumber(element)
  element = element.options if element.is_a?(Kramdown::Element)
  element[:location]
end

#element_linenumbers(elements) ⇒ Object

Returns a list of line numbers for all elements passed in. You can pass in a list of element objects or a list of options hashes here.



148
149
150
 
# File 'lib/mdl/doc.rb', line 148

def element_linenumbers(elements)
  elements.map { |e| element_linenumber(e) }
end

#element_lines(elements) ⇒ Object

Returns the actual source lines for a list of elements. You can pass in a list of elements objects or a list of options hashes here.



156
157
158
 
# File 'lib/mdl/doc.rb', line 156

def element_lines(elements)
  elements.map { |e| element_line(e) }
end

#extract_as_text(element) ⇒ Object

Returns the element as plaintext



280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
 
# File 'lib/mdl/doc.rb', line 280

def extract_as_text(element)
  quotes = {
    :rdquo => '"',
    :ldquo => '"',
    :lsquo => "'",
    :rsquo => "'",
  }
  # If anything goes amiss here, e.g. unknown type, then nil will be
  # returned and we'll just not catch that part of the text, which seems
  # like a sensible failure mode.
  element.children.map do |e|
    if %i{text codespan}.include?(e.type)
      e.value
    elsif %i{strong em p a}.include?(e.type)
      extract_as_text(e).join("\n")
    elsif e.type == :smart_quote
      quotes[e.value]
    end
  end.join.split("\n")
end

#extract_text(element, prefix = '', restore_whitespace = true) ⇒ Object

Extracts the text from an element whose children consist of text elements and other things



251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/mdl/doc.rb', line 251

def extract_text(element, prefix = '', restore_whitespace = true)
  quotes = {
    :rdquo => '"',
    :ldquo => '"',
    :lsquo => "'",
    :rsquo => "'",
  }
  # If anything goes amiss here, e.g. unknown type, then nil will be
  # returned and we'll just not catch that part of the text, which seems
  # like a sensible failure mode.
  lines = element.children.map do |e|
    if e.type == :text
      e.value
    elsif %i{strong em p codespan}.include?(e.type)
      extract_text(e, prefix, restore_whitespace).join("\n")
    elsif e.type == :smart_quote
      quotes[e.value]
    end
  end.join.split("\n")
  # Text blocks have whitespace stripped, so we need to add it back in at
  # the beginning. Because this might be in something like a blockquote,
  # we optionally strip off a prefix given to the function.
  lines[0] = element_line(element).sub(prefix, '') if restore_whitespace
  lines
end

#find_type(type, nested = true) ⇒ Object

Find all elements of a given type, returning their options hash. The options hash has most of the useful data about an element and often you can just use this in your rules.

# Returns [ { :location => 1, :element_level => 2 }, ... ]
elements = find_type(:li)

If nested is set to false, this returns only top level elements of a given type.



72
73
74
 
# File 'lib/mdl/doc.rb', line 72

def find_type(type, nested = true)
  find_type_elements(type, nested).map(&:options)
end

#find_type_elements(type, nested = true, elements = @elements) ⇒ Object

Find all elements of a given type, returning a list of the element objects themselves.

Instead of a single type, a list of types can be provided instead to find all types.

If nested is set to false, this returns only top level elements of a given type.



86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/mdl/doc.rb', line 86

def find_type_elements(type, nested = true, elements = @elements)
  results = []
  type = [type] if type.instance_of?(Symbol)
  elements.each do |e|
    results.push(e) if type.include?(e.type)
    if nested && !e.children.empty?
      results.concat(find_type_elements(type, nested, e.children))
    end
  end
  results
end

#find_type_elements_except(type, nested_except = [], elements = @elements) ⇒ Object

A variation on find_type_elements that allows you to skip drilling down into children of specific element types.

Instead of a single type, a list of types can be provided instead to find all types.

Unlike find_type_elements, this method will always search for nested elements, and skip the element types given to nested_except.



108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/mdl/doc.rb', line 108

def find_type_elements_except(
  type, nested_except = [], elements = @elements
)
  results = []
  type = [type] if type.instance_of?(Symbol)
  nested_except = [nested_except] if nested_except.instance_of?(Symbol)
  elements.each do |e|
    results.push(e) if type.include?(e.type)
    next if nested_except.include?(e.type) || e.children.empty?

    results.concat(
      find_type_elements_except(type, nested_except, e.children),
    )
  end
  results
end

#header_style(header) ⇒ Object

Returns the header ‘style’ - :atx (hashes at the beginning), :atx_closed (atx header style, but with hashes at the end of the line also), :setext (underlined). You can pass in the element object or an options hash here.



166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
 
# File 'lib/mdl/doc.rb', line 166

def header_style(header)
  if header.type != :header
    raise 'header_style called with non-header element'
  end

  line = element_line(header)
  if line.start_with?('#')
    if line.strip.end_with?('#')
      :atx_closed
    else
      :atx
    end
  else
    :setext
  end
end

#indent_for(line) ⇒ Object

Returns how much a given line is indented. Hard tabs are treated as an indent of 8 spaces. You need to pass in the raw string here.



211
212
213
 
# File 'lib/mdl/doc.rb', line 211

def indent_for(line)
  line.match(/^\s*/)[0].gsub("\t", ' ' * 8).length
end

#list_style(item) ⇒ Object

Returns the list style for a list: :asterisk, :plus, :dash, :ordered or :ordered_paren depending on which symbol is used to denote the list item. You can pass in either the element itself or an options hash here.



188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/mdl/doc.rb', line 188

def list_style(item)
  raise 'list_style called with non-list element' if item.type != :li

  line = element_line(item).strip.gsub(/^>\s+/, '')
  if line.start_with?('*')
    :asterisk
  elsif line.start_with?('+')
    :plus
  elsif line.start_with?('-')
    :dash
  elsif line.match('[0-9]+\.')
    :ordered
  elsif line.match('[0-9]+\)')
    :ordered_paren
  else
    :unknown
  end
end

#matching_lines(regex) ⇒ Object

Returns line numbers for lines that match the given regular expression



218
219
220
221
222
223
224
 
# File 'lib/mdl/doc.rb', line 218

def matching_lines(regex)
  @lines.each_with_index
        .select { |text, _linenum| regex.match(text) }
        .map do |i|
          i[1] + 1
        end
end

#matching_text_element_lines(regex, exclude_nested = [:a]) ⇒ Object

Returns line numbers for lines that match the given regular expression. Only considers text inside of ‘text’ elements (i.e. regular markdown text and not code/links or other elements).



230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
 
# File 'lib/mdl/doc.rb', line 230

def matching_text_element_lines(regex, exclude_nested = [:a])
  matches = []
  find_type_elements_except(:text, exclude_nested).each do |e|
    first_line = e.options[:location]
    # We'll error out if kramdown doesn't have location information for
    # the current element. It's better to just not match in these cases
    # rather than crash.
    next if first_line.nil?

    lines = e.value.split("\n")
    lines.each_with_index do |l, i|
      matches << (first_line + i) if regex.match(l)
    end
  end
  matches
end

#to_s ⇒ Object

Reconstruct the full file content from front matter and lines



303
304
305
 
# File 'lib/mdl/doc.rb', line 303

def to_s
  @front_matter + @lines.join("\n")
end