cmdparse 2.0.6 → 3.0.0

data/doc/tutorial.page

@@ -3,189 +3,285 @@ title: Tutorial
 in_menu: true
 sort_info: 6
 ---
-## Quickstart
+## Tutorial
 
-Here are some short code fragments which show how to use cmdparse. A complete example app can be
-found later in the [tutorial section](#tutorial).
+The complete code for this example can be found in the file `example/net.rb` of the `cmdparse`
+package (or online at [cmdparse's Github
+repository][netrb]!
 
-Defining commands using classes:
+**Tl;dr:** In this tutorial we will create a small `net` program which can add, delete and list IP
+addresses as well as show 'network statistics'. By doing this we show how easy it is to use the
+`cmdparse` library for creating a command based program. The last part shows how our created program
+can be invoked and the built-in help facility of `cmdparse`.
 
-~~~ ruby
-class TestCmd < CmdParse::Command
-  def initialize
-    super('test', true)
-    self.add_command(TestSubCmd.new)
-  end
-end
+Note that the shown code fragments do not comprise the whole program. So, depending on what you
+like, just look at the code fragments and the explanations or open the example file alongside this
+tutorial. Later use the `example/net.rb` file for running the program yourself and testing different
+command line arguments.
 
-class TestSubCmd < CmdParse::Command
-  def initialize
-    super('sub',false)
-  end
 
-  def execute (args)
-    puts "Hallo #{args}"
-  end
-end
+### Require statements
+
+First we create a new new file and add the necessary `require` statements:
 
-cmd = CmdParse::CommandParser.new( true )
-cmd.add_command(TestCmd.new)
+~~~ ruby
+{extract: {lines: !ruby/range 4..4}}
 ~~~
 
-Defining command using the basic `CmdParse::Command` class:
+When requiring `cmdparse`, the `optparse` library from Ruby's standard library is also automatically
+required which is used for doing the option parsing part.
+
+
+### The Basic Command Parser Object
+
+Next we will define our command parser object through the [CmdParse::CommandParser] class. Objects
+of this class are used for defining the top level commands of a program as well as the global
+options and other information like the name of the program or its version.
 
 ~~~ ruby
-cmd = CmdParse::CommandParser.new( true )
-testcmd = CmdParse::Command.new( 'test', true )
-testcmd.short_desc = "Short desc"
-cmd.add_command( testcmd )
-
-sub = CmdParse::Command.new( 'sub', false )
-sub.short_desc = "Add an IP address"
-sub.set_execution_block do |args|
-  puts "Hallo #{args}"
-end
-testcmd.add_command( sub )
+{extract: {lines: !ruby/range 26..29}}
 ~~~
 
+We use the `handle_exceptions` argument of the constructor so that exceptions are automatically
+handled gracefully, i.e. by showing an appropriate error message. If we used `true` as value, the
+help screen would be shown in addition to the error message.
 
-## Tutorial
+The next lines set the name of the program, its version and a banner that is shown on all help
+messages. All this information is set on the [main options][CmdParse::CommandParser#main_options].
+Setting this information on the global options or any other `OptionParser` instance has no effect!
 
-The complete code for this example can be found in the file `net.rb` of the `cmdparse` package!
 
-This tutorial produces a small `net` application which can add, delete and list IP adresses and show
-'network statistics'. The shown code fragments do not include the whole program. So, instead of
-writing all the code yourself, just look at the code fragments first and then use the include
-`net.rb` file for running the program.
+### Specifying Options
 
-### Require statements
+An integral part of any CLI program are options that can be set when invoking the program. A command
+based CLI program has several kinds of options:
 
-Create a new new file and write the necessary `require` statements.
+* The [main options][CmdParse::CommandParser#main_options] which can only be used directly after the
+  program name itself. An example for such an option would be a `--version` switch that only makes
+  sense at the top level.
 
-~~~ ruby
-{extract: {lines: !ruby/range 5..5}}
-~~~
+* The [command specific options][CmdParse::Command#options] which can only be used after the command
+  name and before any sub-command name.
 
-### The `CommandParser` class
+* The [global options][CmdParse::CommandParser#global_options] which can be used directly after the
+  program name as well as after any command. Therefore global options are normally used for things
+  that affect all commands, like a global verbosity setting.
 
-Next we will define our basic `CommandParser` by defining the name of the program, its version and
-the global options.
+All these options are specified using the Ruby standard library `optparse` and its `OptionParser`
+class. The `OptionParser` implementation is battle tested, easy to use and allows great flexibility.
 
-The first boolean argument to the constructor of the `CommandParser` class defines whether
-exceptions should be handled gracefully, i.e. by showing an appropriate error message and the help
-screen. The second boolean argument defines whether the top level commands should use partial
-command matching instead of full command matching. If partial command matching is used, then the
-shortest unambiguous part of a command name can be used instead of always specifing the full command
-name.
+We go back to our example now and define a global option:
 
 ~~~ ruby
-{extract: {lines: !ruby/range 30..36}}
+{extract: {lines: !ruby/range 30..34}}
 ~~~
 
-The options are defined using an option parser wrapper. Currently, the only option parser library
-supported is `optparse` from the Ruby Standard Library. If you want to use another option parser
-library, you need to write a wrapper for it so that `cmdparse` can use it.
+The [data attribute][CmdParse::CommandParser#data] on the command parse object (or any command
+object) can be used to store arbitrary information. Here we use it to store the verbosity level so
+that it can easily be used later by any command.
+
+We could have used a global variable for this but storing such information with the command parser
+object usually makes for a better design. Note that the data attribute is only really useful when
+the [CmdParse::CommandParser] is not sub-classed.
+
+
+### Parsing the Command Line Arguments
 
-Now we only have to tell the program to use our newly defined class to process the command line
-arguments.
+We have set up everything that is needed for a basic command based program. The last step is to tell
+the program to use our newly defined command parser object to process the command line arguments:
 
 ~~~ ruby
-{extract: {lines: !ruby/range 86..86}}
+{extract: {lines: !ruby/range 84..84}}
 ~~~
 
-The `parse` method of our `CommandParser` instance parses the given array of options (or `ARGV` if
-no argument is specified). All the command line options are parsed and the given command executed.
+The [parse method][CmdParse::CommandParser#parse] parses the given array of arguments (or `ARGV` if
+no array is specified). All the command line arguments are parsed and the given command executed.
 
-The program can be executed now but won't be useful as we did not specify any commands.
+The program could now be executed but it won't be useful as we did not specify any commands yet.
 
 
 ### Defining commands
 
-So, as we have defined our `CommandParser` object, we need to add some commands to it. First, we
-will add two predefined commands, namely the `help` and the `version` command.
+After performing the basic setup, we need to add some commands so that our program actually does
+something useful.
+
+First, we will add two built-in commands, namely the `help` and the `version` command:
 
 ~~~ ruby
-{extract: {lines: !ruby/range 37..38}}
+{extract: {lines: !ruby/range 35..36}}
 ~~~
 
-That was easy! Now you can execute the program and specify the commands `help` or `version`.
-However, we want the program to do something "useful". Therefore we define a new command.
+That was easy! Now you can execute the program and specify the commands `help` or `version`. You
+will also find that the `help` command is automatically invoked when you don't specify any command.
+This is because we used the `default: true` argument when adding the `help` command which sets the
+added command as the default command that should be used if no explicit command name is given.
+
+The next step is to create the needed commands for our program. There are several different ways of
+doing this.
 
 ~~~ ruby
-{extract: {lines: !ruby/range 41..44}}
+{extract: {lines: !ruby/range 40..42}}
 ~~~
 
-This command is defined by using the default `Command` class. First an instance is created assigning
-a name to the command and defining whether this command takes subcommands and uses partial command
-matching. Next we add a short description so that the `help` command can produce something useful.
-And at last, we add this command to our `CommandParser` instance.
+One way is to create an instance of [CmdParse::Command], update it with all needed properties and
+then add it to the command parser object or another command.
 
-We specified that our `ipaddr` command takes subcommands. So we have to define them, too:
+Since the `ipaddr` command takes other commands and doesn't do anything by itself, no action is
+defined for it. Also notice that we have redefined the default command to be the `ipaddr` command.
+The last added command with the argument `default: true` will be the default command.
 
 ~~~ ruby
-{extract: {lines: !ruby/range 46..78}}
+{extract: {lines: !ruby/range 45..52}}
 ~~~
 
-We add three subcommands to the `ipaddr` command: `add`, `del` and `list`.
-
-* The `add` command is similar to the `ipaddr` command. However, as the `add` command does not take
-  other commands, we have to define an execution block.
+Another way would be to take advantage of the fact that the [add_command
+method][CmdParse::Command#add_command] creates a [CmdParse::Command] object when a name is passed as
+argument instead of a command object itself and that the added command is always yielded if a block
+is given.
 
-* The `del` command is similar to the `add` command. As we want to be able to delete all IP
-  addresses by issuing only one command, we add an option for this.
+Using this block we can now easily customize the command. Since the `ipaddr add` command does not
+take any commands, we need to define an [action block][CmdParse::Command#action] that gets called if
+the command should be executed. By using `*ips` we advertise to `cmdparse` that this command takes
+an arbitrary number of IP addresses as arguments. Note that this is also automatically reflected in
+the usage line for the command!
 
-* By providing `true` as second argument when we add the `list` command to the `ipaddr` command, we
-  specifiy that this command should be the default command which gets invoked when no command name
-  is specified on the command line. Only one command can be specified as default command!
-
-Till now we only used the basic `Command` class to specify commands. However, new commands can also
-be created by subclassing the `Command` class, as shown with this last command:
+We add the `ipaddr del` and `ipaddr list` commands in a similar manner and set the `list` command to
+be the default sub-command for the `ipaddr` command.
 
 ~~~ ruby
-{extract: {lines: !ruby/range 9..28}}
-{extract: {lines: !ruby/range 39..39}}
+{extract: {lines: !ruby/range 6..24}}
+
+{extract: {lines: !ruby/range 37..37}}
 ~~~
 
+The last way for creating a command is to sub-class the [CmdParse::Command] class and do all
+customization there. If this is done, it is recommended to override the `#execute` method instead of
+setting an action block.
+
+We can also see that the execute method takes one or two arguments and that these arguments are also
+properly documented.
+
+
+### Running the Program
+
+<%= (context[:args] = nil; context.render_block('execution')) %>
+
+Now that we have completed our program we can finally run it!
 
-### Running the program
+Below are some sample invocations with their respective output and some explanations.
 
-That's all! You can run the program now and have a look at the output which differs depending on
-which arguments you choose.
+<%= (context[:args] = ""; context.render_block('execution')) %>
 
-So, a typical invocation of this program looks like this:
+When called with no arguments, the default command is executed. The default top level command is
+`ipaddr` and its default command is `list` which shows the added IP addresses. So far, no IP
+addresses are stored - we should change that.
 
-    $ ruby net.rb --verbose ipaddr add 192.168.0.1 193.150.0.1
+<%= (context[:args] = "ip add 192.168.0.1"; context.render_block('execution')) %>
 
-* `--verbose` is a global option
-* `ipaddr` is the first command name (which has no options)
-* `add` is the second command name (which also has no options)
-* `192.168.0.1 193.150.0.1` are additional arguments
+Now we have added one IP address. You might have noticed that we used `ip` instead of `ipaddr`.
+Since partial command matching is automatically done, the shortest unambiguous name for a command
+can be used. As there is no other command starting with `ip` (or even with the letter `i`), it is
+sufficient to write the above to select the `ipaddr` command.
 
-You should notice that if you type
+Now lets add some more IPs but with some informational output.
 
-    $ ruby net.rb
+<%= (context[:args] = "i a 192.168.0.2 192.168.0.4 192.168.0.3 -v"; context.render_block('execution')) %>
 
-you get an error because you did not specify any command.
+This time we added three IP addresses and by using the global option `-v` we got some informational
+output, too.
 
-However, when you type
+Let's display which IP addresses are currently stored.
 
-    $ ruby net.rb ipaddr
+<%= (context[:args] = "ipaddr list"; context.render_block('execution')) %>
 
-you do not get an error!
+So we have four IPs stored. However, we really only need three so we delete one.
 
-Why? As the `ipaddr` command takes subcommands there should be an additional command name (e.g.
-`list`) on the command line. However, as the `list` command is the default command for `ipaddr` you
-do not need to type it.
+<%= (context[:args] = "ip -v del 192.16.8.0.4 "; context.render_block('execution')) %>
 
-*By the way:* You get the same output if you type
+That's much better! But we all are getting sick of this and don't want any IP addresses stored
+anymore.
 
-    $ ruby net.rb ip
+<%= (context[:args] = "ip -a del"; context.render_block('execution')) %>
 
-Why? As partial command matching is used for the top level commands, the shortest unambiguous name
-for a command can be used. As there is no other command starting with `ip` (or even with the letter
-`i`), it is sufficient to write the above to select the `ipaddr` command.
+Alas, I mistyped that last command. The option `-a` is a command specific option of `ipaddr del` and
+therefore not recognized by `ipaddr`.
 
-*Notice:* The options of a command which does not take subcommands do not need to be at the front;
-they can be anywhere, like this
+<%= (context[:args] = ["ip del -av", '']; context.render_block('execution')) %>
 
-    $ ruby test.rb --verbose mycommand file1 file2 --recursive file3
+After deleting all IP addresses none are shown anymore - perfect!
+
+Now we want to see the "network statistics" part of our program. What was the command name again?
+Let's get some help!
+
+<%= (context[:args] = ["help"]; context.render_block('execution')) %>
+
+Ah, yes, the name was `stat`, now we remember!
+
+And there are some interesting things in the help output worth pointing out:
+
+* The usage line shows us that we can define top level option (in addition to the global options)
+  and also nicely lists the available commands.
+
+* The asterisks in the section for the commands show us the default commands.
+
+* We have a top level option `-v` for showing the version as well as a global option `-v` for
+  setting the verbosity level. As mentioned in the help output, the top level option (or a command
+  specific option) always takes precedence over global options.
+
+To make the last point clear, we run the command with the `-v` option.
+
+<%= (context[:args] = ["-v"]; context.render_block('execution')) %>
+
+This shows us the version information as expected instead of invoking the default command.
+
+Back to the network statistics. Now we now the command name but we have forgotten how to use the
+command itself. The `help` command comes to our rescue again!
+
+<%= (context[:args] = ["help stat"]; context.render_block('execution')) %>
+
+There are again some things to point out:
+
+* We get a short summary and a more detailed description of the command. The short description is
+  the one shown in the general help overview. The detailed description is normally longer than this
+  and fully explains the command.
+
+* The arguments for the command are also described. When looking at the usage line, you can see that
+  the `M` argument is optional, but the `N` argument isn't (indicated by the brackets). This means
+  that we need at least one argument. If we provide only one argument, it is used for `N`. And if we
+  provide two arguments, they are used for `M` and `N` (in this order).
+
+  How does `cmdparse` know that `M` is optional? It has inferred this (as well as the names
+  themselves) by looking at the signature of the execute method of the command!
+
+Now we know everything to invoke the command.
+
+<%= (context[:args] = ["stat 5", "stat 3 5"]; context.render_block('execution')) %>
+
+
+### Final Words
+
+Our `net` program is certainly only useful for this tutorial, however, it nicely showcases many of
+the features of `cmdparse` and how easy `cmdparse` is to use.
+
+If you haven't done so by now, [install](installation.html) the `cmdparse` library,
+[download][netrb] our sample `net` program and experiment a bit with it. The [API
+documentation](/api/) is quite extensive and will answer all remaining questions. And if it doesn't,
+you can contact [me](mailto:t_leitner@gmx.at).
+
+
+
+[netrb]: https://github.com/gettalong/cmdparse/blob/master/example/net.rb
+
+
+--- name:execution pipeline:ruby
+if context[:args].nil?
+  require 'fileutils'
+  FileUtils.rm(context.website.directory + '/dumpnet', :force => true)
+  context.content = ''
+else
+  args = [context[:args]].flatten
+  result = args.map do |arg|
+    ["$ <strong>ruby example/net.rb #{arg}</strong>", h(`ruby -I#{context.website.directory}/lib #{context.website.directory}/example/net.rb #{arg}`).chomp]
+  end.flatten.push("$").delete_if {|l| l.empty? }.join("\n")
+  context.content = "<pre>#{result}\n</pre>"
+end

data/doc/virtual

@@ -1,5 +1,2 @@
-api.html:
-  dest_path: rdoc/index.html
-  title: API Reference
-  sort_info: 7
-  in_menu: true
+api/index.html:
+  dest_path: CmdParse/CommandParser.html

data/example/net.rb

@@ -0,0 +1,85 @@
+#!/usr/bin/env ruby
+# if something is changed here -> change line numbers in doc/tutorial.page
+
+require 'cmdparse'
+
+class NetStatCommand < CmdParse::Command
+
+  def initialize
+    super('stat', takes_commands: false)
+    short_desc("Show network statistics")
+    long_desc("This command shows very useful 'network' statistics - eye catching!!!")
+    argument_desc(M: 'start row number', N: 'end row number')
+  end
+
+  def execute(m = 1, n)
+    puts "Showing network statistics" if command_parser.data[:verbose]
+    puts
+    m.to_i.upto(n.to_i) do |row|
+      puts " "*(20 - row).abs + "#"*(row*2 - 1).abs
+    end
+    puts
+  end
+
+end
+
+parser = CmdParse::CommandParser.new(handle_exceptions: :no_help)
+parser.main_options.program_name = "net"
+parser.main_options.version = "0.1.1"
+parser.main_options.banner = "This is net, a s[ai]mple network analytics program"
+parser.global_options do |opt|
+  opt.on("-v", "--verbose", "Be verbose when outputting info") do
+    parser.data[:verbose] = true
+  end
+end
+parser.add_command(CmdParse::HelpCommand.new, default: true)
+parser.add_command(CmdParse::VersionCommand.new)
+parser.add_command(NetStatCommand.new)
+
+# ipaddr
+ipaddr = CmdParse::Command.new('ipaddr')
+ipaddr.short_desc = "Manage IP addresses"
+parser.add_command(ipaddr, default: true)
+
+# ipaddr add
+ipaddr.add_command('add') do |cmd|
+  cmd.takes_commands(false)
+  cmd.short_desc("Add an IP address")
+  cmd.action do |*ips|
+    puts "Adding ip addresses: #{ips.join(', ')}" if parser.data[:verbose]
+    parser.data[:ipaddrs] += ips
+  end
+end
+
+# ipaddr del
+del = CmdParse::Command.new('del', takes_commands: false)
+del.short_desc = "Delete an IP address"
+del.options.on('-a', '--all', 'Delete all IPs') { del.data[:delete_all] = true }
+del.action do |*ips|
+  if del.data[:delete_all]
+    puts "All IP adresses deleted!" if parser.data[:verbose]
+    parser.data[:ipaddrs] = []
+  else
+    puts "Deleting ip addresses: #{ips.join(', ')}" if parser.data[:verbose]
+    ips.each {|ip| parser.data[:ipaddrs].delete(ip) }
+  end
+end
+ipaddr.add_command(del)
+
+# ipaddr list
+list = CmdParse::Command.new('list', takes_commands: false)
+list.short_desc = "Lists all IP addresses"
+list.action do
+  puts "Listing ip addresses:" if parser.data[:verbose]
+  puts parser.data[:ipaddrs].join("\n") unless parser.data[:ipaddrs].empty?
+end
+ipaddr.add_command(list, default: true)
+
+
+parser.data[:ipaddrs] = if File.exists?('dumpnet')
+                          Marshal.load(File.read('dumpnet', mode: 'rb'))
+                        else
+                          []
+                        end
+parser.parse
+File.write('dumpnet', Marshal.dump(parser.data[:ipaddrs]), mode: 'wb+')