module Configliere::Commandline

Command line tool to manage param info

@example

Settings.use :commandline

Attributes

description[RW]
rest[RW]
unknown_argvs[R]
usage[W]

Public Instance Methods

dashed_flag_for(setting_name, flag_name=nil) click to toggle source

Returns a flag in dashed form, suitable for recycling into the commandline of an external program. Can specify a specific flag name, otherwise the given setting key is used

@example

Settings.dashed_flag_for(:flux_capacitance)
#=> --flux-capacitance=0.7
Settings.dashed_flag_for(:screw_you, :hello_friend)
#=> --hello-friend=true
# File lib/configliere/commandline.rb, line 107
def dashed_flag_for setting_name, flag_name=nil
  return unless self[setting_name]
  flag_name ||= setting_name
  (self[setting_name] == true ? "--#{flag_name.to_s.gsub(/_/,"-")}" : "--#{flag_name.to_s.gsub(/_/,"-")}=#{self[setting_name]}" )
end
dashed_flags(*settings_and_names) click to toggle source

dashed_flag_for each given setting that has a value

# File lib/configliere/commandline.rb, line 114
def dashed_flags *settings_and_names
  settings_and_names.map{|args| dashed_flag_for(*args) }.compact
end
die(str, exit_code=-1) click to toggle source

die with a warning

@example

Settings.define :foo, :finally => lambda{ Settings.foo.to_i < 5 or die("too much foo!") }

@param str [String] the string to dump out before exiting @param exit_code [Integer] UNIX exit code to set, default -1

# File lib/configliere/commandline.rb, line 158
def die str, exit_code=-1
  dump_help "****\n#{str}\n****"
  exit exit_code
end
dump_help(str=nil) click to toggle source

Write the help string to stderr

# File lib/configliere/commandline.rb, line 124
def dump_help str=nil
  warn help(str)+"\n"
end
help(str=nil) click to toggle source

The contents of the help message. Lists the usage as well as any defined parameters and environment variables

# File lib/configliere/commandline.rb, line 130
def help str=nil
  buf = []
  buf << usage
  buf << "\n"+@description if @description
  buf << param_lines
  buf << commands_help if respond_to?(:commands_help)
  buf << "\n\n"+str if str
  buf.flatten.compact.join("\n")+"\n"
end
process_argv!() click to toggle source

Parse the command-line args into the params hash.

‘–happy_flag’ produces :happy_flag => true in the params hash ‘–foo=foo_val’ produces :foo => ‘foo_val’ in the params hash. ‘–’ Stop parsing; all remaining args are piled into :rest

self.rest contains all arguments that don’t start with a ‘–’

and all args following the '--' sentinel if any.
# File lib/configliere/commandline.rb, line 46
def process_argv!
  args = ARGV.dup
  self.rest = []
  @unknown_argvs = []
  until args.empty? do
    arg = args.shift
    case
    # end of options parsing
    when arg == '--'
      self.rest += args
      break
    # --param=val or --param
    when arg =~ /\A--([\w\-\.]+)(?:=(.*))?\z/
      param, val = [$1, $2]
      warn "Configliere uses _underscores not dashes for params" if param.include?('-')
      @unknown_argvs << param.to_sym if (not has_definition?(param))
      self[param] = parse_value(val)
    # -abc
    when arg =~ /\A-(\w\w+)\z/
      $1.each_char do |flag|
        param = find_param_for_flag(flag)
        unless param then @unknown_argvs << flag ; next ; end
        self[param] = true
      end
    # -a val
    when arg =~ /\A-(\w)\z/
      flag = find_param_for_flag($1)
      unless flag then @unknown_argvs << flag ; next ; end
      if (not args.empty?) && (args.first !~ /\A-/)
        val = args.shift
      else
        val = nil
      end
      self[flag] = parse_value(val)
    # -a=val
    when arg =~ /\A-(\w)=(.*)\z/
      flag, val = [find_param_for_flag($1), $2]
      unless flag then @unknown_argvs << flag ; next ; end
      self[flag] = parse_value(val)
    else
      self.rest << arg
    end
  end
  @unknown_argvs.uniq!
end
raw_script_name() click to toggle source

the script basename, for recycling into help messages

# File lib/configliere/commandline.rb, line 147
def raw_script_name
  File.basename($0)
end
resolve!(print_help_and_exit=true) click to toggle source

Processing to reconcile all options

  • processes all commandline params

  • calls up the resolve! chain.

  • if the –help param was given, prints out a usage statement describing all define’d params and exits

If the –help param was given, Will print out a usage statement describing all define’d params and exit. To avoid this, pass ‘false` as the first argument.

@param [true,false] print_help_and_exit whether to print help and exit if the –help param was given

Calls superclass method
# File lib/configliere/commandline.rb, line 26
def resolve!(print_help_and_exit=true)
  process_argv!
  if print_help_and_exit && self[:help]
    dump_help
    exit(2)
  end
  super()
  self
end
usage() click to toggle source

Usage line

# File lib/configliere/commandline.rb, line 141
def usage
  %Q{usage: #{raw_script_name} [...--param=val...]}
end

Protected Instance Methods

find_param_for_flag(flag) click to toggle source

Retrieve the first param defined with the given flag.

# File lib/configliere/commandline.rb, line 175
def find_param_for_flag(flag)
  params_with(:flag).each do |param_name, param_flag|
    return param_name if flag.to_s == param_flag.to_s
  end
  nil
end
find_width(param_names) click to toggle source

run through the params and find the width needed to pretty-print them

# File lib/configliere/commandline.rb, line 209
def find_width(param_names)
  [ 20,
    param_names.map{|param_name| param_with_type(param_name).length }
  ].flatten.max + 2
end
param_line(name, definition, width, has_flags) click to toggle source

pretty-print a param

# File lib/configliere/commandline.rb, line 195
def param_line(name, definition, width, has_flags)
  desc = definition_of(name, :description).to_s.strip
  buf = ['  ']
  buf << (definition[:flag] ? "-#{definition[:flag]}," : "   ") if has_flags
  buf << sprintf("--%-#{width}s", param_with_type(name))
  buf << (desc.empty? ? name : desc)
  buf << "[Default: #{definition[:default]}]"  if definition[:default]
  buf << '[Required]'                          if definition[:required]
  buf << '[Encrypted]'                         if definition[:encrypted]
  buf << "[Env Var: #{definition[:env_var]}]"  if definition[:env_var]
  buf.join(' ')
end
param_lines() click to toggle source
# File lib/configliere/commandline.rb, line 182
def param_lines
  pdefs = definitions.reject{|name, definition| definition[:internal] }
  return if pdefs.empty?
  buf = ["\nParams:"]
  width     = find_width(pdefs.keys)
  has_flags = (not params_with(:flag).empty?)
  pdefs.sort_by{|pn, pd| pn.to_s }.each do |name, definition|
    buf << param_line(name, definition, width, has_flags)
  end
  buf
end
param_with_type(param) click to toggle source
# File lib/configliere/commandline.rb, line 215
def param_with_type(param)
  str  = param.to_s
  type = definition_of(param, :type)
  case type
  when :boolean then str += ''
  when nil      then str += '=String'
  else               str += "=#{type}"
  end
  str
end
parse_value(val) click to toggle source

handle –param (true), –param=” (set as nil), –param=hi (‘hi’)

# File lib/configliere/commandline.rb, line 166
def parse_value val
  case
  when val == nil then true  # --flag    option on its own means 'set that option'
  when val == '' then nil    # --flag='' the explicit empty string means nil
  else val                   # else just return the value
  end
end