Class: Amp::Help::HelpEntry

Inherits:
Object show all
Defined in:
lib/amp/help/help.rb

Overview

The generic HelpEntry class encapsulates a entry in the help system. The entry has text that it provides to the user, as well as a name. The base HelpEntry class does not track its own name, because well, that’s not useful! All it needs to know how to do is present its text when asked for it.

Direct Known Subclasses

CommandHelpEntry, ErbHelpEntry, MarkdownHelpEntry

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, text = "") ⇒ HelpEntry

Creates a new HelpEntry, and registers it in the Help system, making it immediately available. It is for this reason that all subclasses should call super, because that registration is important!

Parameters:

  • name (String, #to_s) —

    the name under which to register this help entry

  • text (String) (defaults to: "") —

    (“”) the text for the entry.



95
96
97
98
 
# File 'lib/amp/help/help.rb', line 95

def initialize(name, text = "")
  @text = text
  HelpRegistry.register(name, self)
end

Class Method Details

.from_file(filename) ⇒ HelpEntry

Singleton method that opens a file and returns a HelpEntry representing it. What makes this method spiffy is that it tries to detect the type of file – markdown, ERb, et cetera, based on the file’s extension, and picks the appropriate class to represent that help entry.

The entry is registered under the name of the file - without any extensions - and the file’s full contents are provided as the initial text.

Parameters:

  • filename (String) —

    the path to the file to load

Returns:

  • (HelpEntry) —

    a help entry representing the file as best as we can.



73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/amp/help/help.rb', line 73

def from_file(filename)
  klass = case File.extname(filename).downcase
          when ".md", ".markdown"
            MarkdownHelpEntry
          when ".erb"
            ErbHelpEntry
          else
            HelpEntry
          end
  without_entry_dir = File.expand_path(File.join(File.dirname(__FILE__), "entries"))
  name = filename[without_entry_dir.size+1..-1].gsub(/\//,":")
  klass.new(name.split(".", 2).first, File.read(filename))
end

Instance Method Details

#desc ⇒ Object

Describes the entry briefly, so if the user must pick, they have a decent shot at knowing what this entry is about. Hopefully.

In the generic case, use the text and grab the first few words.

Returns:

  • a description of the entry based on its content



121
122
123
 
# File 'lib/amp/help/help.rb', line 121

def desc
  %Q{a regular help entry ("#{text.split[0..5].join(" ")} ...")}
end

#text(options = {}) ⇒ String

Returns the help text to display for this entry.

In the generic case, just return the @text variable.

Parameters:

  • options (Hash) (defaults to: {}) —

    the options for the process - that way the help commands can access the user’s run-time options and global configuration. For example, if the user passes in –verbose or –quiet, each help entry could handle that differently. Who are we to judge?

Returns:

  • (String) —

    the help text for the entry.



110
111
112
 
# File 'lib/amp/help/help.rb', line 110

def text(options = {})
  @text
end