← Back to branch summary

~ubuntu-branches/ubuntu/wily/ruby-cri/wily-proposed

« back to all changes in this revision

Viewing changes to .pc/privacy-breach.patch/README.adoc

  • Committer: Package Import Robot
  • Author(s): Cédric Boutillier
  • Date: 2014-04-14 15:15:48 UTC
  • mfrom: (1.1.3)
  • Revision ID: package-import@ubuntu.com-20140414151548-xni482c106hiik3q
Tags: 2.6.0-1
* Imported Upstream version 2.6.0
* Add asciidoctor to Build-Depends, now that the README file has a .adoc
  extension
* Add privacy-breach.patch to remove remote badges from the README file

Show diffs side-by-side

added added

removed removed

Lines of Context:
.pc/privacy-breach.patch/README.adoc
 
1
= Cri =
 
2
 
 
3
link:http://rubygems.org/gems/cri[image:http://img.shields.io/gem/v/cri.svg[]]
 
4
link:https://travis-ci.org/ddfreyne/cri[image:http://img.shields.io/travis/ddfreyne/cri.svg[]]
 
5
link:https://coveralls.io/r/ddfreyne/cri[image:http://img.shields.io/coveralls/ddfreyne/cri.svg[]]
 
6
link:https://codeclimate.com/github/ddfreyne/cri[image:http://img.shields.io/codeclimate/github/ddfreyne/cri.svg[]]
 
7
link:http://inch-pages.github.io/github/ddfreyne/cri/[image:http://inch-pages.github.io/github/ddfreyne/cri.png[]]
 
8
 
 
9
Cri is a library for building easy-to-use commandline tools with support for
 
10
nested commands.
 
11
 
 
12
== Usage ==
 
13
 
 
14
The central concept in Cri is the _command_, which has option definitions as
 
15
well as code for actually executing itself. In Cri, the commandline tool
 
16
itself is a command as well.
 
17
 
 
18
Here’s a sample command definition:
 
19
 
 
20
[source,ruby]
 
21
--------------------------------------------------------------------------------
 
22
command = Cri::Command.define do
 
23
  name        'dostuff'
 
24
  usage       'dostuff [options]'
 
25
  aliases     :ds, :stuff
 
26
  summary     'does stuff'
 
27
  description 'This command does a lot of stuff. I really mean a lot.'
 
28
 
 
29
  flag   :h,  :help,  'show help for this command' do |value, cmd|
 
30
    puts cmd.help
 
31
    exit 0
 
32
  end
 
33
  flag   nil, :more,  'do even more stuff'
 
34
  option :s,  :stuff, 'specify stuff to do', argument: :required
 
35
 
 
36
  run do |opts, args, cmd|
 
37
    stuff = opts.fetch(:stuff, 'generic stuff')
 
38
    puts "Doing #{stuff}!"
 
39
 
 
40
    if opts[:more]
 
41
      puts 'Doing it even more!'
 
42
    end
 
43
  end
 
44
end
 
45
--------------------------------------------------------------------------------
 
46
 
 
47
To run this command, invoke the `#run` method with the raw arguments. For
 
48
example, for a root command (the commandline tool itself), the command could
 
49
be called like this:
 
50
 
 
51
[source,ruby]
 
52
--------------------------------------------------------------------------------
 
53
command.run(ARGV)
 
54
--------------------------------------------------------------------------------
 
55
 
 
56
Each command has automatically generated help. This help can be printed using
 
57
`Cri::Command#help`; something like this will be shown:
 
58
 
 
59
--------------------------------------------------------------------------------
 
60
usage: dostuff [options]
 
61
 
 
62
does stuff
 
63
 
 
64
    This command does a lot of stuff. I really mean a lot.
 
65
 
 
66
options:
 
67
 
 
68
    -h --help      show help for this command
 
69
       --more      do even more stuff
 
70
    -s --stuff     specify stuff to do
 
71
--------------------------------------------------------------------------------
 
72
 
 
73
=== General command metadata ===
 
74
 
 
75
Let’s disect the command definition and start with the first five lines:
 
76
 
 
77
[source,ruby]
 
78
--------------------------------------------------------------------------------
 
79
name        'dostuff'
 
80
usage       'dostuff [options]'
 
81
aliases     :ds, :stuff
 
82
summary     'does stuff'
 
83
description 'This command does a lot of stuff. I really mean a lot.'
 
84
--------------------------------------------------------------------------------
 
85
 
 
86
These lines of the command definition specify the name of the command (or the
 
87
commandline tool, if the command is the root command), the usage, a list of
 
88
aliases that can be used to call this command, a one-line summary and a (long)
 
89
description. The usage should not include a “usage:” prefix nor the name of
 
90
the supercommand, because the latter will be automatically prepended.
 
91
 
 
92
Aliases don’t make sense for root commands, but for subcommands they do.
 
93
 
 
94
=== Command-line options ===
 
95
 
 
96
The next few lines contain the command’s option definitions:
 
97
 
 
98
[source,ruby]
 
99
--------------------------------------------------------------------------------
 
100
flag   :h,  :help,  'show help for this command' do |value, cmd|
 
101
  puts cmd.help
 
102
  exit 0
 
103
end
 
104
flag   nil, :more,  'do even more stuff'
 
105
option :s,  :stuff, 'specify stuff to do', argument: :required
 
106
--------------------------------------------------------------------------------
 
107
 
 
108
Options can be defined using the following methods:
 
109
 
 
110
* `Cri::CommandDSL#option` or `Cri::CommandDSL#opt`
 
111
* `Cri::CommandDSL#flag` (implies no arguments passed to option)
 
112
* `Cri::CommandDSL#required` (implies required argument)
 
113
* `Cri::CommandDSL#optional` (implies optional argument)
 
114
 
 
115
All these methods take the short option form as their first argument, and a
 
116
long option form as their second argument. Either the short or the long form
 
117
can be nil, but not both (because that would not make any sense). In the
 
118
example above, the `--more` option has no short form.
 
119
 
 
120
Each of the above methods also take a block, which will be executed when the
 
121
option is found. The argument to the block are the option value (`true` in
 
122
case the option does not have an argument) and the command.
 
123
 
 
124
==== Multivalued options ====
 
125
 
 
126
Each of these four methods take a `:multiple` option. When set to true, multiple
 
127
option valus are accepted, and the option values will be stored in an array.
 
128
 
 
129
For example, to parse the command line options string `-o foo.txt -o bar.txt`
 
130
into an array, so that `options[:output]` contains `[ 'foo.txt', 'bar.txt' ]`,
 
131
you can use an option definition like this:
 
132
 
 
133
[source,ruby]
 
134
--------------------------------------------------------------------------------
 
135
option :o, :output, 'specify output paths', argument: :required, multiple: true
 
136
--------------------------------------------------------------------------------
 
137
 
 
138
This can also be used for flags (options without arguments). In this case, the
 
139
length of the options array is relevant.
 
140
 
 
141
For example, you can allow setting the verbosity level using `-v -v -v`. The
 
142
value of `options[:verbose].size` would then be the verbosity level (three in
 
143
this example). The option definition would then look like this:
 
144
 
 
145
[source,ruby]
 
146
--------------------------------------------------------------------------------
 
147
flag :v, :verbose, 'be verbose (use up to three times)', multiple: true
 
148
--------------------------------------------------------------------------------
 
149
 
 
150
=== The run block ===
 
151
 
 
152
The last part of the command defines the execution itself:
 
153
 
 
154
[source,ruby]
 
155
--------------------------------------------------------------------------------
 
156
run do |opts, args, cmd|
 
157
  stuff = opts.fetch(:stuff, 'generic stuff')
 
158
  puts "Doing #{stuff}!"
 
159
 
 
160
  if opts[:more]
 
161
    puts 'Doing it even more!'
 
162
  end
 
163
end
 
164
--------------------------------------------------------------------------------
 
165
 
 
166
The +Cri::CommandDSL#run+ method takes a block with the actual code to
 
167
execute. This block takes three arguments: the options, any arguments passed
 
168
to the command, and the command itself.
 
169
 
 
170
Instead of defining a run block, it is possible to declare a class, the
 
171
_command runner_ class (`Cri::CommandRunner`) that will perform the actual
 
172
execution of the command. This makes it easier to break up large run blocks
 
173
into manageable pieces.
 
174
 
 
175
=== Subcommands ===
 
176
 
 
177
Commands can have subcommands. For example, the `git` commandline tool would be
 
178
represented by a command that has subcommands named `commit`, `add`, and so on.
 
179
Commands with subcommands do not use a run block; execution will always be
 
180
dispatched to a subcommand (or none, if no subcommand is found).
 
181
 
 
182
To add a command as a subcommand to another command, use the
 
183
`Cri::Command#add_command` method, like this:
 
184
 
 
185
[source,ruby]
 
186
--------------------------------------------------------------------------------
 
187
root_cmd.add_command(cmd_add)
 
188
root_cmd.add_command(cmd_commit)
 
189
root.cmd.add_command(cmd_init)
 
190
--------------------------------------------------------------------------------
 
191
 
 
192
== Contributors ==
 
193
 
 
194
* Toon Willems
 
195
* Ken Coar
 
196
 
 
197
Thanks for Lee “injekt” Jarvis for link:https://github.com/injekt/slop[Slop],
 
198
which has inspired the design of Cri 2.0.