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) ⇒ Doc

Create a new document given a string containing the markdown source



30
31
32
33
34
35
 
# File 'lib/mdl/doc.rb', line 30

def initialize(text)
  @lines = text.split("\n")
  @parsed = Kramdown::Document.new(text, :input => 'MarkdownLint')
  @elements = @parsed.root.children
  add_levels(@elements)
end

Instance Attribute Details

#elements ⇒ Object (readonly)

A list of top level Kramdown::Element objects from the parsed document.



25
26
27
 
# File 'lib/mdl/doc.rb', line 25

def elements
  @elements
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.



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

def lines
  @lines
end

#parsed ⇒ Object (readonly)

A Kramdown::Document object containing the parsed markdown document.



20
21
22
 
# File 'lib/mdl/doc.rb', line 20

def parsed
  @parsed
end

Class Method Details

.new_from_file(filename) ⇒ Object

Alternate ‘constructor’ passing in a filename



40
41
42
43
44
45
46
 
# File 'lib/mdl/doc.rb', line 40

def self.new_from_file(filename)
  if filename == "-"
    self.new(STDIN.read)
  else
    self.new(File.read(filename))
  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.



102
103
104
 
# File 'lib/mdl/doc.rb', line 102

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.



91
92
93
94
 
# File 'lib/mdl/doc.rb', line 91

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.



110
111
112
 
# File 'lib/mdl/doc.rb', line 110

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.



118
119
120
 
# File 'lib/mdl/doc.rb', line 118

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

#extract_text(element, prefix = "") ⇒ Object

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



205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/mdl/doc.rb', line 205

def extract_text(element, prefix="")
  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 { |e|
    if e.type == :text
      e.value
    elsif [:strong, :em, :p].include?(e.type)
      extract_text(e, prefix).join("\n")
    elsif e.type == :smart_quote
      quotes[e.value]
    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, "")
  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.



59
60
61
 
# File 'lib/mdl/doc.rb', line 59

def find_type(type, nested=true)
  find_type_elements(type, nested).map { |e| e.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.



73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/mdl/doc.rb', line 73

def find_type_elements(type, nested=true, elements=@elements)
  results = []
  if type.class == Symbol
    type = [type]
  end
  elements.each do |e|
    results.push(e) if type.include?(e.type)
    if nested and not e.children.empty?
      results.concat(find_type_elements(type, nested, e.children))
    end
  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.



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/mdl/doc.rb', line 128

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.



173
174
175
 
# File 'lib/mdl/doc.rb', line 173

def indent_for(line)
  return 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.



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/mdl/doc.rb', line 149

def list_style(item)
  if item.type != :li
    raise "list_style called with non-list element"
  end
  line = element_line(item).strip
  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(re) ⇒ Object

Returns line numbers for lines that match the given regular expression



180
181
182
183
 
# File 'lib/mdl/doc.rb', line 180

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

#matching_text_element_lines(re) ⇒ 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).



189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/mdl/doc.rb', line 189

def matching_text_element_lines(re)
  matches = []
  find_type_elements(:text).each do |e|
    first_line = e.options[:location]
    lines = e.value.split("\n")
    lines.each_with_index do |l, i|
      matches << first_line + i if re.match(l)
    end
  end
  matches
end