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

doc[RW]

The reference Doc object

elements[RW]

The elements that make up the MarkedUpText

Public Class Methods

new(doc, text = nil) click to toggle source

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

dump() click to toggle source
# 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
parse_from_string(string) click to toggle source

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
to_s() click to toggle source
# 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

flush_element() click to toggle source

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
parse_paragraph_markup(doc, string) click to toggle source

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