class CTioga2::Commands::Documentation::MarkedUpText
The documentation strings are written in a simple markup language.
todo we should provide tags to specifically mark TODO items in documentation, in such a way that it would be easy to make a list of them, and possibly ignore it for output.
Constants
- LinkRE
A few constants to help writing out the paragraph markup
- MarkOnceRE
Attributes
The reference Doc
object
The elements that make up the MarkedUpText
Public Class Methods
Creates a MarkedUpText
object.
# File lib/ctioga2/commands/doc/markup.rb, line 202 def initialize(doc, text = nil) @elements = [] @doc = doc if text parse_from_string(text) end end
Public Instance Methods
# File lib/ctioga2/commands/doc/markup.rb, line 211 def dump puts "Number of elements: #{@elements.size}" for el in @elements puts "#{el.class} -> #{el.to_s}" end end
Parses the given string and append the results to the MarkedUpText's elements.
Markup
elements:
-
a line beginning with '> ' is an example for command-line
-
a line beginning with '# ' is an example for use within a command file.
-
a line beginning with '@ ' is a generic verbatim text.
-
a line beginning with ' *' is an element of an itemize. The itemize finishes when a new paragraph is starting.
-
a {group: …} or {type: …} or {command: …} is a link to the element.
-
a blank line marks a paragraph break.
todo Add elements to do some inline markup (such as bold, code, italics; mostly code for now will do very fine)
# File lib/ctioga2/commands/doc/markup.rb, line 237 def parse_from_string(string) @last_type = nil @last_string = "" lines = string.split(/[ \t]*\n/) for l in lines l.chomp! case l when /^[#>@]\s(.*)/ # a verbatim line case l[0,1] when '#' type = :cmdfile when '>' type = :cmdline else type = :example end if @last_type == type @last_string << "#{$1}\n" else flush_element @last_type = type @last_string = "#{$1}\n" end when /^\s\*\s*(.*)/ flush_element @last_type = :item @last_string = "#{$1}\n" when /^\s*$/ # Blank line: flush_element @last_type = nil @last_string = "" else case @last_type when :item, :paragraph # simply go on @last_string << "#{l}\n" else flush_element @last_type = :paragraph @last_string = "#{l}\n" end end end flush_element end
# File lib/ctioga2/commands/doc/markup.rb, line 283 def to_s return @elements.map do |x| x.to_s end.join("") end
Protected Instance Methods
Adds the element accumulated so far to the @elements array.
# File lib/ctioga2/commands/doc/markup.rb, line 317 def flush_element case @last_type when :cmdline, :cmdfile @elements << MarkupVerbatim.new(@doc, @last_string, "examples-#{@last_type}") when :example @elements << MarkupVerbatim.new(@doc, @last_string, "examples") when :paragraph @elements << MarkupParagraph.new(@doc, parse_paragraph_markup(doc, @last_string)) when :item if @elements.last.is_a?(MarkupItemize) @elements.last.items << parse_paragraph_markup(doc, @last_string) else @elements << MarkupItemize.new(@doc, [ parse_paragraph_markup(doc, @last_string)]) end else # In principle, nil return end end
Parses the markup found within a paragraph (ie: links and other text attributes, but not verbatim, list or other markings) and returns an array containing the MarkupItem
elements.
# File lib/ctioga2/commands/doc/markup.rb, line 301 def parse_paragraph_markup(doc, string) els = [] while string =~ /#{LinkRE}|#{MarkOnceRE}/ els << MarkupText.new(doc, $`) if $1 els << MarkupLink.new(doc, $2, $1) elsif $3 els << MarkupText.new(doc, $3, true, :code) end string = $' end els << MarkupText.new(doc, string) return els end