diff options
| -rw-r--r-- | Rakefile | 16 | ||||
| -rw-r--r-- | doc/leap.md | 285 | ||||
| -rw-r--r-- | lib/leap_cli.rb | 2 | ||||
| -rw-r--r-- | lib/leap_cli/commands/ca.rb | 8 | ||||
| -rw-r--r-- | lib/leap_cli/commands/clean.rb | 2 | ||||
| -rw-r--r-- | lib/leap_cli/commands/compile.rb | 2 | ||||
| -rw-r--r-- | lib/leap_cli/commands/deploy.rb | 6 | ||||
| -rw-r--r-- | lib/leap_cli/commands/inspect.rb | 6 | ||||
| -rw-r--r-- | lib/leap_cli/commands/list.rb | 8 | ||||
| -rw-r--r-- | lib/leap_cli/commands/new.rb | 8 | ||||
| -rw-r--r-- | lib/leap_cli/commands/node.rb | 18 | ||||
| -rw-r--r-- | lib/leap_cli/commands/shell.rb | 4 | ||||
| -rw-r--r-- | lib/leap_cli/commands/test.rb | 18 | ||||
| -rw-r--r-- | lib/leap_cli/commands/user.rb | 2 | ||||
| -rw-r--r-- | lib/leap_cli/commands/vagrant.rb | 16 | ||||
| -rw-r--r-- | lib/leap_cli/markdown_document_listener.rb | 134 | ||||
| -rw-r--r-- | lib/lib_ext/markdown_document_listener.rb | 122 |
17 files changed, 609 insertions, 48 deletions
@@ -27,6 +27,11 @@ $spec_path = 'leap_cli.gemspec' $base_dir = File.dirname(__FILE__) $spec = eval(File.read(File.join($base_dir, $spec_path))) $gem_path = File.join($base_dir, 'pkg', "#{$spec.name}-#{$spec.version}.gem") +require File.join([$base_dir, 'lib','leap_cli','version.rb']) +LeapCli::REQUIRE_PATHS.each do |path| + path = File.expand_path(path, $base_dir) + $LOAD_PATH.unshift path unless $LOAD_PATH.include?(path) +end def built_gem_path Dir[File.join($base_dir, "#{$spec.name}-*.gem")].sort_by{|f| File.mtime(f)}.last @@ -122,3 +127,14 @@ end # rd.rdoc_files.include("README.rdoc","lib/**/*.rb","bin/**/*") # rd.title = 'Your application title' # end + +desc "Dumps all command line options to doc/leap.md" +task :doc do + Dir.chdir($base_dir + "/doc") do + if system('../bin/leap _doc --format=LeapCli::MarkdownDocumentListener') + puts "updated doc/leap.md" + else + puts "error" + end + end +end
\ No newline at end of file diff --git a/doc/leap.md b/doc/leap.md new file mode 100644 index 0000000..b176541 --- /dev/null +++ b/doc/leap.md @@ -0,0 +1,285 @@ +@title = 'Command Line Reference' + +The command "leap" can be used to manage a bevy of servers running the LEAP platform from the comfort of your own home. + + +# Global Options + +* `--log FILE` +Override default log file +Default Value: None + +* `-v|--verbose LEVEL` +Verbosity level 0..2 +Default Value: 1 + +* `--help` +Show this message + +* `--version` +Display version number and exit + +* `--yes` +Skip prompts and assume "yes" + + +# leap add-user USERNAME + +Adds a new trusted sysadmin + + + +**Options** + +* `--pgp-pub-key arg` +OpenPGP public key file for this new user +Default Value: None + +* `--ssh-pub-key arg` +SSH public key file for this new user +Default Value: None + +* `--self` +lets you choose among your public keys + + +# leap cert + +Manage X.509 certificates + + + +## leap cert ca + +Creates two Certificate Authorities (one for validating servers and one for validating clients). + +See see what values are used in the generation of the certificates (like name and key size), run `leap inspect provider` and look for the "ca" property. To see the details of the created certs, run `leap inspect <file>`. + +## leap cert csr + +Creates a CSR for use in buying a commercial X.509 certificate. + +The CSR created is for the for the provider's primary domain. The properties used for this CSR come from `provider.ca.server_certificates`. + +## leap cert dh + +Creates a Diffie-Hellman parameter file. + + + +## leap cert update <node-filter> + +Creates or renews a X.509 certificate/key pair for a single node or all nodes, but only if needed. + +This command will a generate new certificate for a node if some value in the node has changed that is included in the certificate (like hostname or IP address), or if the old certificate will be expiring soon. Sometimes, you might want to force the generation of a new certificate, such as in the cases where you have changed a CA parameter for server certificates, like bit size or digest hash. In this case, use --force. If <node-filter> is empty, this command will apply to all nodes. + +**Options** + +* `--force` +Always generate new certificates + + +# leap clean + +Removes all files generated with the "compile" command. + + + +# leap compile + +Compiles node configuration files into hiera files used for deployment. + + + +# leap deploy FILTER + +Apply recipes to a node or set of nodes. + +The FILTER can be the name of a node, service, or tag. + +**Options** + +* `--tags TAG[,TAG]` +Specify tags to pass through to puppet (overriding the default). +Default Value: leap_base,leap_service + +* `--fast` +Makes the deploy command faster by skipping some slow steps. A "fast" deploy can be used safely if you recently completed a normal deploy. + + +# leap help command + +Shows a list of commands or help for one command + +Gets help for the application or its commands. Can also list the commands in a way helpful to creating a bash-style completion function + +**Options** + +* `-c` +List commands one per line, to assist with shell completion + + +# leap inspect FILE + +Prints details about a file. Alternately, the argument FILE can be the name of a node, service or tag. + + + +# leap list [FILTER] + +List nodes and their classifications + +Prints out a listing of nodes, services, or tags. If present, the FILTER can be a list of names of nodes, services, or tags. If the name is prefixed with +, this acts like an AND condition. For example: + +`leap list node1 node2` matches all nodes named "node1" OR "node2" + +`leap list openvpn +local` matches all nodes with service "openvpn" AND tag "local" + +**Options** + +* `--print arg` +What attributes to print (optional) +Default Value: None + + +# leap local + +Manage local virtual machines. + +This command provides a convient way to manage Vagrant-based virtual machines. If FILTER argument is missing, the command runs on all local virtual machines. The Vagrantfile is automatically generated in 'test/Vagrantfile'. If you want to run vagrant commands manually, cd to 'test'. + +## leap local destroy [FILTER] + +Destroys the virtual machine(s), reclaiming the disk space + + + +## leap local reset [FILTER] + +Resets virtual machine(s) to the last saved snapshot + + + +## leap local save [FILTER] + +Saves the current state of the virtual machine as a new snapshot + + + +## leap local start [FILTER] + +Starts up the virtual machine(s) + + + +## leap local status [FILTER] + +Print the status of local virtual machine(s) + + + +## leap local stop [FILTER] + +Shuts down the virtual machine(s) + + + +# leap new DIRECTORY + +Creates a new provider instance in the specified directory, creating it if necessary. + + + +**Options** + +* `--contacts arg` +Default email address contacts. +Default Value: None + +* `--domain arg` +The primary domain of the provider. +Default Value: None + +* `--name arg` +The name of the provider. +Default Value: None + +* `--platform arg` +File path of the leap_platform directory. +Default Value: None + + +# leap node + +Node management + + + +## leap node add NAME [SEED] + +Create a new configuration file for a node named NAME. + +If specified, the optional argument SEED can be used to seed values in the node configuration file. + +The format is property_name:value. + +For example: `leap node add web1 ip_address:1.2.3.4 services:webapp`. + +To set nested properties, property name can contain '.', like so: `leap node add web1 ssh.port:44` + +Separeate multiple values for a single property with a comma, like so: `leap node add mynode services:webapp,dns` + +**Options** + +* `--local` +Make a local testing node (by automatically assigning the next available local IP address). Local nodes are run as virtual machines on your computer. + + +## leap node init FILTER + +Bootstraps a node or nodes, setting up SSH keys and installing prerequisite packages + +This command prepares a server to be used with the LEAP Platform by saving the server's SSH host key, copying the authorized_keys file, and installing packages that are required for deploying. Node init must be run before deploying to a server, and the server must be running and available via the network. This command only needs to be run once, but there is no harm in running it multiple times. + +**Options** + +* `--echo` +If set, passwords are visible as you type them (default is hidden) + + +## leap node mv OLD_NAME NEW_NAME + +Renames a node file, and all its related files. + + + +## leap node rm NAME + +Removes all the files related to the node named NAME. + + + +# leap ssh NAME + +Log in to the specified node with an interactive shell. + + + +# leap test + +Run tests. + + + +## leap test init + +Creates files needed to run tests. + + + +## leap test run + +Run tests. + + +Default Command: run diff --git a/lib/leap_cli.rb b/lib/leap_cli.rb index 384a5f2..714211a 100644 --- a/lib/leap_cli.rb +++ b/lib/leap_cli.rb @@ -24,6 +24,8 @@ require 'leap_cli/config/secrets' require 'leap_cli/config/object_list' require 'leap_cli/config/manager' +require 'leap_cli/markdown_document_listener' + module LeapCli::Commands; end # diff --git a/lib/leap_cli/commands/ca.rb b/lib/leap_cli/commands/ca.rb index 7c6fc4d..d3f864a 100644 --- a/lib/leap_cli/commands/ca.rb +++ b/lib/leap_cli/commands/ca.rb @@ -9,6 +9,7 @@ module LeapCli; module Commands command :cert do |cert| cert.desc 'Creates two Certificate Authorities (one for validating servers and one for validating clients).' + cert.long_desc 'See see what values are used in the generation of the certificates (like name and key size), run `leap inspect provider` and look for the "ca" property. To see the details of the created certs, run `leap inspect <file>`.' cert.command :ca do |ca| ca.action do |global_options,options,args| assert_config! 'provider.ca.name' @@ -17,7 +18,7 @@ module LeapCli; module Commands end end - cert.desc 'Creates or renews a X.509 certificate/key pair for a single node or all nodes, but only if needed' + cert.desc 'Creates or renews a X.509 certificate/key pair for a single node or all nodes, but only if needed.' cert.long_desc 'This command will a generate new certificate for a node if some value in the node has changed ' + 'that is included in the certificate (like hostname or IP address), or if the old certificate will be expiring soon. ' + 'Sometimes, you might want to force the generation of a new certificate, ' + @@ -45,7 +46,7 @@ module LeapCli; module Commands end end - cert.desc 'Creates a Diffie-Hellman parameter file' # (needed for server-side of some TLS connections) + cert.desc 'Creates a Diffie-Hellman parameter file.' # (needed for server-side of some TLS connections) cert.command :dh do |dh| dh.action do |global_options,options,args| long_running do @@ -79,7 +80,8 @@ module LeapCli; module Commands # nice details about CSRs: # http://www.redkestrel.co.uk/Articles/CSR.html # - cert.desc 'Creates a CSR for use in buying a commercial X.509 certificate' + cert.desc "Creates a CSR for use in buying a commercial X.509 certificate." + cert.long_desc "The CSR created is for the for the provider's primary domain. The properties used for this CSR come from `provider.ca.server_certificates`." cert.command :csr do |csr| #c.switch 'sign', :desc => 'additionally creates a cert that is signed by your own CA (recommended only for testing)', :negatable => false csr.action do |global_options,options,args| diff --git a/lib/leap_cli/commands/clean.rb b/lib/leap_cli/commands/clean.rb index 8847b7d..a9afff5 100644 --- a/lib/leap_cli/commands/clean.rb +++ b/lib/leap_cli/commands/clean.rb @@ -1,7 +1,7 @@ module LeapCli module Commands - desc 'Removes all files generated with the "compile" command' + desc 'Removes all files generated with the "compile" command.' command :clean do |c| c.action do |global_options,options,args| Dir.glob(path([:hiera, '*'])).each do |file| diff --git a/lib/leap_cli/commands/compile.rb b/lib/leap_cli/commands/compile.rb index 0e645d6..3cdd5dd 100644 --- a/lib/leap_cli/commands/compile.rb +++ b/lib/leap_cli/commands/compile.rb @@ -2,7 +2,7 @@ module LeapCli module Commands - desc 'Compiles node configuration files into hiera files used for deployment' + desc 'Compiles node configuration files into hiera files used for deployment.' command :compile do |c| c.action do |global_options,options,args| compile_hiera_files diff --git a/lib/leap_cli/commands/deploy.rb b/lib/leap_cli/commands/deploy.rb index b5595f0..5b1e4d5 100644 --- a/lib/leap_cli/commands/deploy.rb +++ b/lib/leap_cli/commands/deploy.rb @@ -4,9 +4,9 @@ module LeapCli DEFAULT_TAGS = ['leap_base','leap_service'] - desc 'Apply recipes to a node or set of nodes' - long_desc 'The node-filter can be the name of a node, service, or tag.' - arg_name 'node-filter' + desc 'Apply recipes to a node or set of nodes.' + long_desc 'The FILTER can be the name of a node, service, or tag.' + arg_name 'FILTER' command :deploy do |c| # --fast diff --git a/lib/leap_cli/commands/inspect.rb b/lib/leap_cli/commands/inspect.rb index 97d0b20..0c40356 100644 --- a/lib/leap_cli/commands/inspect.rb +++ b/lib/leap_cli/commands/inspect.rb @@ -1,11 +1,11 @@ module LeapCli; module Commands - desc 'Prints information about a file or node.' - arg_name '<file-or-node>', :optional => false + desc 'Prints details about a file. Alternately, the argument FILE can be the name of a node, service or tag.' + arg_name 'FILE' command :inspect do |c| c.action do |global_options,options,args| object = args.first - assert! object, 'A file path or node name is required' + assert! object, 'A file path or node/service/tag name is required' method = inspection_method(object) if method && defined?(method) self.send(method, object, options) diff --git a/lib/leap_cli/commands/list.rb b/lib/leap_cli/commands/list.rb index 02389e7..4ff2367 100644 --- a/lib/leap_cli/commands/list.rb +++ b/lib/leap_cli/commands/list.rb @@ -4,13 +4,13 @@ module LeapCli; module Commands desc 'List nodes and their classifications' long_desc 'Prints out a listing of nodes, services, or tags. ' + - 'The node-filter can be a list of names of nodes, services, or tags. ' + + 'If present, the FILTER can be a list of names of nodes, services, or tags. ' + 'If the name is prefixed with +, this acts like an AND condition. ' + "For example:\n\n" + - " * node1 node2 -> matches all nodes named \"node1\" OR \"node2\"\n\n" + - " * openvpn +local -> matches all nodes with service \"openvpn\" AND tag \"local\"" + "`leap list node1 node2` matches all nodes named \"node1\" OR \"node2\"\n\n" + + "`leap list openvpn +local` matches all nodes with service \"openvpn\" AND tag \"local\"" - arg_name '[node-filter]', :optional => true + arg_name 'FILTER', :optional => true command :list do |c| c.flag 'print', :desc => 'What attributes to print (optional)' c.action do |global_options,options,args| diff --git a/lib/leap_cli/commands/new.rb b/lib/leap_cli/commands/new.rb index b6eb4f1..bf8e7f1 100644 --- a/lib/leap_cli/commands/new.rb +++ b/lib/leap_cli/commands/new.rb @@ -6,10 +6,10 @@ module LeapCli; module Commands arg_name 'DIRECTORY' skips_pre command :new do |c| - c.flag 'name', :desc => "The name of the provider" #, :default_value => 'Example' - c.flag 'domain', :desc => "The primary domain of the provider" #, :default_value => 'example.org' - c.flag 'platform', :desc => "File path of the leap_platform directory" #, :default_value => '../leap_platform' - c.flag 'contacts', :desc => "Default email address contacts" #, :default_value => 'root' + c.flag 'name', :desc => "The name of the provider." #, :default_value => 'Example' + c.flag 'domain', :desc => "The primary domain of the provider." #, :default_value => 'example.org' + c.flag 'platform', :desc => "File path of the leap_platform directory." #, :default_value => '../leap_platform' + c.flag 'contacts', :desc => "Default email address contacts." #, :default_value => 'root' c.action do |global, options, args| directory = File.expand_path(args.first) diff --git a/lib/leap_cli/commands/node.rb b/lib/leap_cli/commands/node.rb index bb02fa9..e8f2c73 100644 --- a/lib/leap_cli/commands/node.rb +++ b/lib/leap_cli/commands/node.rb @@ -10,13 +10,13 @@ module LeapCli; module Commands desc 'Node management' command :node do |node| - node.desc 'Create a new configuration file for a node' - node.long_desc ["If specified, the optional argument seed-options can be used to seed values in the node configuration file.", + node.desc 'Create a new configuration file for a node named NAME.' + node.long_desc ["If specified, the optional argument SEED can be used to seed values in the node configuration file.", "The format is property_name:value.", "For example: `leap node add web1 ip_address:1.2.3.4 services:webapp`.", "To set nested properties, property name can contain '.', like so: `leap node add web1 ssh.port:44`", - "To set multiple values for a single property, use ',', like so: `leap node add mynode services:webapp,dns`"].join("\n\n") - node.arg_name '<node-name> [seed-options]' # , :optional => false, :multiple => false + "Separeate multiple values for a single property with a comma, like so: `leap node add mynode services:webapp,dns`"].join("\n\n") + node.arg_name 'NAME [SEED]' # , :optional => false, :multiple => false node.command :add do |add| add.switch :local, :desc => 'Make a local testing node (by automatically assigning the next available local IP address). Local nodes are run as virtual machines on your computer.', :negatable => false add.action do |global_options,options,args| @@ -48,7 +48,7 @@ module LeapCli; module Commands "copying the authorized_keys file, and installing packages that are required for deploying. " + "Node init must be run before deploying to a server, and the server must be running and available via the network. " + "This command only needs to be run once, but there is no harm in running it multiple times." - node.arg_name '<node-filter>' #, :optional => false, :multiple => false + node.arg_name 'FILTER' #, :optional => false, :multiple => false node.command :init do |init| init.switch 'echo', :desc => 'If set, passwords are visible as you type them (default is hidden)', :negatable => false init.action do |global,options,args| @@ -68,8 +68,8 @@ module LeapCli; module Commands end end - node.desc 'Renames a node file, and all its related files' - node.arg_name '<old-name> <new-name>' + node.desc 'Renames a node file, and all its related files.' + node.arg_name 'OLD_NAME NEW_NAME' node.command :mv do |mv| mv.action do |global_options,options,args| node = get_node_from_args(args) @@ -82,8 +82,8 @@ module LeapCli; module Commands end end - node.desc 'Removes a node file, and all its related files' - node.arg_name '<node-name>' #:optional => false #, :multiple => false + node.desc 'Removes all the files related to the node named NAME.' + node.arg_name 'NAME' #:optional => false #, :multiple => false node.command :rm do |rm| rm.action do |global_options,options,args| node = get_node_from_args(args) diff --git a/lib/leap_cli/commands/shell.rb b/lib/leap_cli/commands/shell.rb index 5d8fc66..cc17408 100644 --- a/lib/leap_cli/commands/shell.rb +++ b/lib/leap_cli/commands/shell.rb @@ -1,7 +1,7 @@ module LeapCli; module Commands - desc 'Log in to the specified node with an interactive shell' - arg_name '<node-name>', :optional => false, :multiple => false + desc 'Log in to the specified node with an interactive shell.' + arg_name 'NAME' #, :optional => false, :multiple => false command :ssh do |c| c.action do |global_options,options,args| node = get_node_from_args(args) diff --git a/lib/leap_cli/commands/test.rb b/lib/leap_cli/commands/test.rb index e895a5e..80a6333 100644 --- a/lib/leap_cli/commands/test.rb +++ b/lib/leap_cli/commands/test.rb @@ -1,23 +1,23 @@ module LeapCli; module Commands - desc 'Run tests' - command :test do |c| - c.desc 'Creates files needed to run tests' - c.command :init do |c| - c.action do |global_options,options,args| + desc 'Run tests.' + command :test do |test| + test.desc 'Creates files needed to run tests.' + test.command :init do |init| + init.action do |global_options,options,args| generate_test_client_cert generate_test_client_openvpn_config end end - c.desc 'Run tests' - c.command :run do |c| - c.action do |global_options,options,args| + test.desc 'Run tests.' + test.command :run do |run| + run.action do |global_options,options,args| log 'not yet implemented' end end - c.default_command :run + test.default_command :run end private diff --git a/lib/leap_cli/commands/user.rb b/lib/leap_cli/commands/user.rb index aed29b7..d0146b6 100644 --- a/lib/leap_cli/commands/user.rb +++ b/lib/leap_cli/commands/user.rb @@ -15,7 +15,7 @@ module LeapCli module Commands desc 'Adds a new trusted sysadmin' - arg_name '<username>', :optional => false, :multiple => false + arg_name 'USERNAME' #, :optional => false, :multiple => false command :'add-user' do |c| c.switch 'self', :desc => 'lets you choose among your public keys', :negatable => false diff --git a/lib/leap_cli/commands/vagrant.rb b/lib/leap_cli/commands/vagrant.rb index 5aeed74..56e887a 100644 --- a/lib/leap_cli/commands/vagrant.rb +++ b/lib/leap_cli/commands/vagrant.rb @@ -3,11 +3,11 @@ require 'fileutils' module LeapCli; module Commands - desc "Manage local virtual machines" - long_desc "This command provides a convient way to manage Vagrant-based virtual machines. If node-filter argument is missing, the command runs on all local virtual machines. The Vagrantfile is automatically generated in 'test/Vagrantfile'. If you want to run vagrant commands manually, cd to 'test'." + desc "Manage local virtual machines." + long_desc "This command provides a convient way to manage Vagrant-based virtual machines. If FILTER argument is missing, the command runs on all local virtual machines. The Vagrantfile is automatically generated in 'test/Vagrantfile'. If you want to run vagrant commands manually, cd to 'test'." command :local do |local| local.desc 'Starts up the virtual machine(s)' - local.arg_name 'node-filter', :optional => true #, :multiple => false + local.arg_name 'FILTER', :optional => true #, :multiple => false local.command :start do |start| start.action do |global_options,options,args| vagrant_command(["up", "sandbox on"], args) @@ -15,7 +15,7 @@ module LeapCli; module Commands end local.desc 'Shuts down the virtual machine(s)' - local.arg_name 'node-filter', :optional => true #, :multiple => false + local.arg_name 'FILTER', :optional => true #, :multiple => false local.command :stop do |stop| stop.action do |global_options,options,args| if global_options[:yes] @@ -27,7 +27,7 @@ module LeapCli; module Commands end local.desc 'Destroys the virtual machine(s), reclaiming the disk space' - local.arg_name 'node-filter', :optional => true #, :multiple => false + local.arg_name 'FILTER', :optional => true #, :multiple => false local.command :destroy do |destroy| destroy.action do |global_options,options,args| if global_options[:yes] @@ -39,7 +39,7 @@ module LeapCli; module Commands end local.desc 'Print the status of local virtual machine(s)' - local.arg_name 'node-filter', :optional => true #, :multiple => false + local.arg_name 'FILTER', :optional => true #, :multiple => false local.command :status do |status| status.action do |global_options,options,args| vagrant_command("status", args) @@ -47,7 +47,7 @@ module LeapCli; module Commands end local.desc 'Saves the current state of the virtual machine as a new snapshot' - local.arg_name 'node-filter', :optional => true #, :multiple => false + local.arg_name 'FILTER', :optional => true #, :multiple => false local.command :save do |status| status.action do |global_options,options,args| vagrant_command("sandbox commit", args) @@ -55,7 +55,7 @@ module LeapCli; module Commands end local.desc 'Resets virtual machine(s) to the last saved snapshot' - local.arg_name 'node-filter', :optional => true #, :multiple => false + local.arg_name 'FILTER', :optional => true #, :multiple => false local.command :reset do |reset| reset.action do |global_options,options,args| vagrant_command("sandbox rollback", args) diff --git a/lib/leap_cli/markdown_document_listener.rb b/lib/leap_cli/markdown_document_listener.rb new file mode 100644 index 0000000..60b012e --- /dev/null +++ b/lib/leap_cli/markdown_document_listener.rb @@ -0,0 +1,134 @@ +# +# A class to generate a markdown file with all the information available with the +# help subcommand. +# +# This is adapted from GLI::Commands::RdocDocumentListener +# + +require 'stringio' +require 'gli/commands/help_modules/arg_name_formatter' + +module LeapCli + class MarkdownDocumentListener + + def initialize(global_options,options,arguments) + @io = File.new(File.basename($0) + ".md",'w') + @nest = '' + @commands = [File.basename($0)] + @arg_name_formatter = GLI::Commands::HelpModules::ArgNameFormatter.new + end + + def beginning + end + + # Called when processing has completed + def ending + @io.close + end + + # Gives you the program description + def program_desc(desc) + @io.puts "@title = 'Command Line Reference'" + #@io.puts "# #{File.basename($0)} - #{desc}" + @io.puts + end + + def program_long_desc(desc) + @io.puts desc + @io.puts + end + + # Gives you the program version + def version(version) + #@io.puts "v#{version}" + #@io.puts + end + + def options + #@io.puts "<div class='options'>" + @io.puts + if @nest.size == 0 + @io.puts "# Global Options" + else + #@io.puts "#{@nest}# Options" + @io.puts "**Options**" + end + @io.puts + end + + # Gives you a flag in the current context + def flag(name,aliases,desc,long_desc,default_value,arg_name,must_match,type) + invocations = ([name] + Array(aliases)).map { |_| add_dashes(_) }.join('|') + usage = "#{invocations} #{arg_name || 'arg'}" + #@io.puts "#{@nest}## #{usage}" + @io.puts "* `#{usage}` " + @io.puts String(desc).strip + " " + @io.puts String(long_desc).strip + " " if long_desc + @io.puts "Default Value: #{default_value || 'None'} " + @io.puts "Must Match: #{must_match.to_s} " unless must_match.nil? + @io.puts + end + + # Gives you a switch in the current context + def switch(name,aliases,desc,long_desc,negetable) + if negetable + name = "[no-]#{name}" if name.to_s.length > 1 + aliases = aliases.map { |_| _.to_s.length > 1 ? "[no-]#{_}" : _ } + end + invocations = ([name] + aliases).map { |_| add_dashes(_) }.join('|') + #@io.puts "#{@nest}## #{invocations}" + @io.puts "* `#{invocations}` " + @io.puts String(desc).strip + " " + #@io.puts + #@io.puts String(long_desc).strip + @io.puts + end + + def end_options + #@io.puts "</div>" + end + + def commands + #@io.puts "#{@nest}## Commands" + #@nest = "#{@nest}#" + end + + # Gives you a command in the current context and creates a new context of this command + def command(name,aliases,desc,long_desc,arg_name,arg_options) + @commands.push(name) + #@io.puts "#{@nest}## Command: <tt>#{([name] + aliases).join('|')} #{@arg_name_formatter.format(arg_name,arg_options)}</tt>" + @io.puts + @io.puts "#{@nest}# #{@commands.join ' '} #{@arg_name_formatter.format(arg_name,arg_options)}" + @io.puts + @io.puts String(desc).strip + @io.puts + @io.puts String(long_desc).strip + @nest = "#{@nest}#" + end + + # Ends a command, and "pops" you back up one context + def end_command(name) + @nest.gsub!(/\#$/,'') + @commands.pop + end + + # Gives you the name of the current command in the current context + def default_command(name) + @io.puts "Default Command: #{name}" unless name.nil? + end + + def end_commands + @nest.gsub!(/\#$/,'') + end + + private + + def add_dashes(name) + name = "-#{name}" + name = "-#{name}" if name.length > 2 + name + end + + + end +end diff --git a/lib/lib_ext/markdown_document_listener.rb b/lib/lib_ext/markdown_document_listener.rb new file mode 100644 index 0000000..55026e9 --- /dev/null +++ b/lib/lib_ext/markdown_document_listener.rb @@ -0,0 +1,122 @@ +require 'stringio' +require 'gli/commands/help_modules/arg_name_formatter' + +# +# adaption of RdocDocumentListener to use Markdown +# see http://rtomayko.github.com/ronn/ronn-format.7 +# + +module GLI + module Commands + class MarkdownDocumentListener + + def initialize(global_options,options,arguments) + @io = STDOUT #File.new(File.basename($0) + ".rdoc",'w') + @nest = '' + @arg_name_formatter = GLI::Commands::HelpModules::ArgNameFormatter.new + end + + def beginning + end + + # Called when processing has completed + def ending + #@io.close + end + + # Gives you the program description + def program_desc(desc) + @io.puts "== #{File.basename($0)} - #{desc}" + @io.puts + end + + def program_long_desc(desc) + @io.puts desc + @io.puts + end + + # Gives you the program version + def version(version) + @io.puts "v#{version}" + @io.puts + end + + def options + if @nest.size == 0 + @io.puts "=== Global Options" + else + @io.puts "#{@nest}=== Options" + end + end + + # Gives you a flag in the current context + def flag(name,aliases,desc,long_desc,default_value,arg_name,must_match,type) + invocations = ([name] + Array(aliases)).map { |_| add_dashes(_) }.join('|') + usage = "#{invocations} #{arg_name || 'arg'}" + @io.puts "#{@nest}=== #{usage}" + @io.puts + @io.puts String(desc).strip + @io.puts + @io.puts "[Default Value] #{default_value || 'None'}" + @io.puts "[Must Match] #{must_match.to_s}" unless must_match.nil? + @io.puts String(long_desc).strip + @io.puts + end + + # Gives you a switch in the current context + def switch(name,aliases,desc,long_desc,negetable) + if negetable + name = "[no-]#{name}" if name.to_s.length > 1 + aliases = aliases.map { |_| _.to_s.length > 1 ? "[no-]#{_}" : _ } + end + invocations = ([name] + aliases).map { |_| add_dashes(_) }.join('|') + @io.puts "#{@nest}=== #{invocations}" + @io.puts String(desc).strip + @io.puts + @io.puts String(long_desc).strip + @io.puts + end + + def end_options + end + + def commands + @io.puts "#{@nest}=== Commands" + @nest = "#{@nest}=" + end + + # Gives you a command in the current context and creates a new context of this command + def command(name,aliases,desc,long_desc,arg_name,arg_options) + @io.puts "#{@nest}=== Command: <tt>#{([name] + aliases).join('|')} #{@arg_name_formatter.format(arg_name,arg_options)}</tt>" + @io.puts String(desc).strip + @io.puts + @io.puts String(long_desc).strip + @nest = "#{@nest}=" + end + + # Ends a command, and "pops" you back up one context + def end_command(name) + @nest.gsub!(/=$/,'') + end + + # Gives you the name of the current command in the current context + def default_command(name) + @io.puts "[Default Command] #{name}" unless name.nil? + end + + def end_commands + @nest.gsub!(/=$/,'') + end + + private + + def add_dashes(name) + name = "-#{name}" + name = "-#{name}" if name.length > 2 + name + end + + + end + end +end |