Class: CTioga2::Commands::Documentation::MarkedUpText

Inherits:
Object
  • Object
show all
Includes:
Log
Defined in:
lib/ctioga2/commands/doc/markup.rb

Overview

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.

Defined Under Namespace

Classes: MarkupItem, MarkupItemize, MarkupLink, MarkupParagraph, MarkupText, MarkupVerbatim

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Log

context, counts, debug, error, fatal, #format_exception, #identify, info, init_logger, log_to, logger, set_level, #spawn, warn

Constructor Details

#initialize(doc, text = nil) ⇒ MarkedUpText

Creates a MarkedUpText object.



202
203
204
205
206
207
208
 
# 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

Instance Attribute Details

#doc ⇒ Object

The reference Doc object



196
197
198
 
# File 'lib/ctioga2/commands/doc/markup.rb', line 196

def doc
  @doc
end

#elements ⇒ Object

The elements that make up the MarkedUpText



199
200
201
 
# File 'lib/ctioga2/commands/doc/markup.rb', line 199

def elements
  @elements
end

Instance Method Details

#dump ⇒ Object 



211
212
213
214
215
216
 
# 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) ⇒ Object

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 … or … or … 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)



237
238
239
240
241
242
243
244
245
246
247
248
249
250
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
276
277
278
279
280
281
 
# 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 ⇒ Object 



283
284
285
286
287
 
# File 'lib/ctioga2/commands/doc/markup.rb', line 283

def to_s
  return @elements.map do |x|
    x.to_s
  end.join("")
end