class Buryspam::Help

Generate Help text by extracting related comments and code from this script. This class is used to generate help for the configuration parameters and command line options when the --help option is used. This class is a singleton, so its only instance must be created using instance instead of new,

Constants

CMD_ARGUMENTS

Map GetoptLong constants to more friendly strings.

DOC_CATEGORIES

The DOC_CATEGORIES list contains two hashes, one for each category of documentation:

The options specified on the command line
The configuration parameters specified in ~/.buryspamrc.

Each category has several attributes:

:item_name is the name of the category being documented (configuration parameters, command line options).
:block_regex is a regular expression that matches the chunk of code containing all the relevant documentation and the code items. This regular expression should capture the relevent chuck of code in its first capture.
:item_regex is a regular expression that extracts each of the items being documented from the block of code matched by the :block_regex. The first capture should be the description of the item (comments); the second capture should be the item name.
:text and :html contain the text and html procedures that render the help contents.
:html_enclosure is an array of exactly two strings which delimit the html contents. These could be <table> and </table> delimiters, for example.

Note that this is a list of hashes so as to preserve ordering (command line options before configuration parameters) during display and HTML generation of multiple categories.

SCRIPT

The full pathname of this script.

USAGE

Message to display in response to the --help option or when an invalid option is specified on the command line.

Public Class Methods

new() click to toggle source

Create a Help object by extracting and storing chunks of code containing help documentation from this script.

# File buryspam.rb, line 4809
def initialize
  DOC_CATEGORIES.each { |category|
    md = category[:block_regex].match(IO.binread(SCRIPT))
    if md.nil? || md[1].nil?
      raise "Cannot extract documentation for #{category[:item_name]}s."
    end
    category[:chunk] = md[1]
    category[:items] = []
  }
end

Public Instance Methods

search(item = "") click to toggle source

Display a usage message if no/empty item given. Otherwise, attempt to find item in the list of command line options and configuration parameters. If it's found then display that item's help text. If it's not found, then display all the command line options and configuration parameters. If item is '*' then help text in HTML format is displayed for all command line options/configuration parameters.

# File buryspam.rb, line 4826
def search(item = "")
  if item.empty?
    print USAGE
    return
  end

  item_help = extract(item)
  if item_help.empty?
    print "'#{item}': invalid command line option/configuration parameter\n\n"
    display_valid
  else
    print item_help.join("")
  end
end

Private Instance Methods

display_valid() click to toggle source

Show all the valid items (configuration parameters, command line options) on standard error. This method is typically called when an invalid item was specified after the --help option on the command line.

# File buryspam.rb, line 4883
def display_valid
  DOC_CATEGORIES.each { |category|
    puts("Available #{category[:item_name]}s:")
    category[:items].map! { |o| o.gsub(/^--/, "") }
    print(" " + category[:items].sort.join(", ").format + "\n\n")
  }
end

extract(item) click to toggle source

Extract and returns the formatted option/parameter documentation from the chunk of code isolated by the constructor. item is the name of the command line option or configuration parameter being extracted. If item is '*', then the HTML version of all item documentation is returned.

# File buryspam.rb, line 4847
def extract(item)
  format = item == '*' ? :html : :text
  results = []
  DOC_CATEGORIES.each { |category|
    # The cumulative documentation output strings extracted
    # from this chunk of code.
    result = []
    category[:chunk].scan(category[:item_regex]) { |matches|
      # matches[0] is the commented description
      # matches[1] is the name of the option/parameter.
      desc, name = matches[0..1]

      # Remove leading hashes from description and unfold lines
      # that were too long.
      matches[0] = desc.gsub(/^\s*#/, "").gsub(/\\\n\s*/, "")
      # Keep a list of valid items for use by the display_valid method.
      category[:items] << name
      next unless item == '*' || /\A(--)?#{item}\z/.match(name)
      result << category[format].call(*matches)
    }
    next if result.empty?
    if format == :html
      # Insert all the sorted item documentation in-between the
      # HTML delimiters.
      category[:html_enclosure][1,0] = result.sort
      result = category[:html_enclosure]
    end
    results << result
  }
  results
end