Class: Runfile::DocoptHelper

Inherits:
Object
  • Object
show all
Includes:
Colsole
Defined in:
lib/runfile/docopt_helper.rb

Overview

The DocoptHelper class handles the dynamic generation of the docopt document and the docopt part of the execution (meaning, to call Docopt so it returns the parsed arguments or halts with usage message).

Instance Method Summary collapse

Constructor Details

#initialize(options) ⇒ DocoptHelper

The constructor expects to an object that responds to all the textual details needed to generate a docopt document (name, version, summary, options) and an array of Action objects. The superspace argument will be the name of runfile, in case we are running a named.runfile. It is only needed to generate the proper ‘run superspace (-h|–help|–version)` line



18
19
20
21
22
23
24
25
26
27
28
 
# File 'lib/runfile/docopt_helper.rb', line 18

def initialize(options)
  @superspace = options.superspace
  @name       = options.name
  @version    = options.version
  @summary    = options.summary
  @actions    = options.actions
  @options    = options.options
  @params     = options.params
  @env_vars   = options.env_vars
  @examples   = options.examples
end

Instance Method Details

#args(argv) ⇒ Object

Call the docopt handler, which will either return a parsed arguments list, or halt execution and show usage.



125
126
127
 
# File 'lib/runfile/docopt_helper.rb', line 125

def args(argv)
  Docopt.docopt(docopt, version: @version, argv:argv)
end

#docopt ⇒ Object

Generate a document based on all the actions, help messages and options we have collected from the Runfile DSL.



32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/runfile/docopt_helper.rb', line 32

def docopt
  width = detect_terminal_size[0]
  doc = []
  doc << (@version ? "#{@name} #{@version}" : "#{@name}")
  doc << "#{@summary}" if @summary
  doc += docopt_usage
  doc += docopt_commands width
  doc += docopt_options width
  doc += docopt_params width
  doc += docopt_env_vars width
  doc += docopt_examples width
  doc.join "\n"
end

#docopt_commands(width) ⇒ Object

Return all docopt lines for the ‘Commands’ section



62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/runfile/docopt_helper.rb', line 62

def docopt_commands(width)
  doc = []
  caption_printed = false
  @actions.each do |_name, action|
    action.help or next
    doc << "Commands:" unless caption_printed
    caption_printed = true
    helpline = "      #{action.help}"
    wrapped  = word_wrap helpline, width
    doc << "  #{action.usage}\n#{wrapped}\n" unless action.usage == false
  end
  doc
end

#docopt_env_vars(width) ⇒ Object

Return all docopt params for ‘Environment Variables’ section



90
91
92
 
# File 'lib/runfile/docopt_helper.rb', line 90

def docopt_env_vars(width)
  section_block @env_vars, width
end

#docopt_examples(width) ⇒ Object

Return all docopt lines for the ‘Examples’ section



95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/runfile/docopt_helper.rb', line 95

def docopt_examples(width)
  return [] if @examples.empty?

  doc = ["Examples:"]
  base_command = @superspace ? "run #{@superspace}" : "run"
  @examples.each do |command|
    helpline = "  #{base_command} #{command}"
    wrapped  = word_wrap helpline, width
    doc << "#{wrapped}"
  end
  doc
end

#docopt_options(width) ⇒ Object

Return all docopt lines for the various ‘Options’ sections



77
78
79
80
81
82
 
# File 'lib/runfile/docopt_helper.rb', line 77

def docopt_options(width)
  @options['Options'] = {} unless @options['Options']
  @options['Options']['-h --help'] = 'Show this screen'
  @options['Options']['--version'] = 'Show version number' if @version
  section_block @options, width
end

#docopt_params(width) ⇒ Object

Return all docopt params for ‘Params’ section



85
86
87
 
# File 'lib/runfile/docopt_helper.rb', line 85

def docopt_params(width)
  section_block @params, width
end

#docopt_usage ⇒ Object

Return all docopt lines for the ‘Usage’ section



47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/runfile/docopt_helper.rb', line 47

def docopt_usage 
  doc = ["\nUsage:"];
  @actions.each do |_name, action|
    doc << "  run #{action.usage}" unless action.usage == false
  end
  basic_flags = @version ? "(-h|--help|--version)" : "(-h|--help)"
  if @superspace
    doc << "  run #{@superspace} #{basic_flags}\n"
  else
    doc << "  run #{basic_flags}\n"
  end
  doc
end

#section_block(definitions, width) ⇒ Object

Return a generic block containing scope section (e.g. “Options”), followed by key value paragraphs.



110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/runfile/docopt_helper.rb', line 110

def section_block(definitions, width)
  doc = []
  definitions.each do |scope, values|
    doc << "#{scope}:"
    values.each do |label, text|
      helpline = "      #{text}"
      wrapped  = word_wrap helpline, width
      doc << "  #{label}\n#{wrapped}\n"
    end
  end
  doc
end