Class: MarkdownLint::Doc
- Inherits:
-
Object
- Object
- MarkdownLint::Doc
- Defined in:
- lib/mdl/doc.rb
Overview
Representation of the markdown document passed to rule checks
Instance Attribute Summary collapse
-
#elements ⇒ Object
readonly
A list of top level Kramdown::Element objects from the parsed document.
-
#lines ⇒ Object
readonly
A list of raw markdown source lines.
-
#parsed ⇒ Object
readonly
A Kramdown::Document object containing the parsed markdown document.
Class Method Summary collapse
-
.new_from_file(filename) ⇒ Object
Alternate ‘constructor’ passing in a filename.
Instance Method Summary collapse
-
#element_line(element) ⇒ Object
Returns the actual source line for a given element.
-
#element_linenumber(element) ⇒ Object
Returns the line number a given element is located on in the source file.
-
#element_linenumbers(elements) ⇒ Object
Returns a list of line numbers for all elements passed in.
-
#element_lines(elements) ⇒ Object
Returns the actual source lines for a list of elements.
-
#extract_text(element, prefix = "") ⇒ Object
Extracts the text from an element whose children consist of text elements and other things.
-
#find_type(type, nested = true) ⇒ Object
Find all elements of a given type, returning their options hash.
-
#find_type_elements(type, nested = true, elements = @elements) ⇒ Object
Find all elements of a given type, returning a list of the element objects themselves.
-
#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.
-
#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).
-
#indent_for(line) ⇒ Object
Returns how much a given line is indented.
-
#initialize(text) ⇒ Doc
constructor
Create a new document given a string containing the markdown source.
-
#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.
-
#matching_lines(re) ⇒ Object
Returns line numbers for lines that match the given regular expression.
-
#matching_text_element_lines(re, exclude_nested = [:a]) ⇒ Object
Returns line numbers for lines that match the given regular expression.
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.
129 130 131 |
# File 'lib/mdl/doc.rb', line 129 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.
118 119 120 121 |
# File 'lib/mdl/doc.rb', line 118 def element_linenumber(element) element = element. 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.
137 138 139 |
# File 'lib/mdl/doc.rb', line 137 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.
145 146 147 |
# File 'lib/mdl/doc.rb', line 145 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
232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 |
# File 'lib/mdl/doc.rb', line 232 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. } 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 |
#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.
97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 |
# File 'lib/mdl/doc.rb', line 97 def find_type_elements_except(type, nested_except=[], elements=@elements) results = [] if type.class == Symbol type = [type] end if nested_except.class == Symbol nested_except = [nested_except] end elements.each do |e| results.push(e) if type.include?(e.type) unless nested_except.include?(e.type) or e.children.empty? results.concat(find_type_elements_except(type, nested_except, 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.
155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 |
# File 'lib/mdl/doc.rb', line 155 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.
200 201 202 |
# File 'lib/mdl/doc.rb', line 200 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.
176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 |
# File 'lib/mdl/doc.rb', line 176 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
207 208 209 210 |
# File 'lib/mdl/doc.rb', line 207 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, 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).
216 217 218 219 220 221 222 223 224 225 226 |
# File 'lib/mdl/doc.rb', line 216 def matching_text_element_lines(re, exclude_nested=[:a]) matches = [] find_type_elements_except(:text, exclude_nested).each do |e| first_line = e.[: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 |