razor-client 0.14.0 → 0.15.0

data/lib/razor/cli/parse.rb

@@ -14,6 +14,14 @@ module Razor::CLI
           @dump = true
         end
 
+        opts.on "-f", "--full", "Show full details when viewing entities" do
+          @format = 'full'
+        end
+
+        opts.on "-s", "--short", "Show shortened details when viewing entities" do
+          @format = 'short'
+        end
+
         opts.on "-u", "--url URL",
           "The full Razor API URL, can also be set\n" + " "*37 +
           "with the RAZOR_API environment variable\n" + " "*37 +
@@ -21,7 +29,12 @@ module Razor::CLI
           parse_and_set_api_url(url, :opts)
         end
 
+        opts.on "-v", "--version", "Show the version of Razor" do
+          @show_version = true
+        end
+
         opts.on "-h", "--help", "Show this screen" do
+          # If searching for a command's help, leave the argument for navigation.
           @option_help = true
         end
 
@@ -35,41 +48,97 @@ module Razor::CLI
       end.join("\n")
     end
 
+    def version
+      <<-VERSION
+Razor Server version: #{navigate.server_version}
+Razor Client version: #{Razor::CLI::VERSION}
+      VERSION
+    end
+
     def help
       output = get_optparse.to_s
       begin
-        output << list_things("Collections", navigate.collections)
-        output << "\n\n      Navigate to entries of a collection using COLLECTION NAME, for example,\n      'nodes node15'  for the  details of a node or 'nodes node15 log' to see\n      the log for node15\n"
-        output << list_things("Commands", navigate.commands)
-        output << "\n\n      Pass arguments to commands either directly by name ('--name=NAME')\n      or save the JSON body for the  command  in a file and pass it with\n      '--json FILE'.  Using --json is the only way to pass  arguments in\n      nested structures such as the configuration for a broker.\n"
+        output << <<-HELP
+#{list_things("Collections", navigate.collections)}
+
+      Navigate to entries of a collection using COLLECTION NAME, for example,
+      'nodes node15'  for the  details of a node or 'nodes node15 log' to see
+      the log for node15
+#{list_things("Commands", navigate.commands)}
+
+      Pass arguments to commands either directly by name ('--name=NAME')
+      or save the JSON body for the  command  in a file and pass it with
+      '--json FILE'.  Using --json is the only way to pass  arguments in
+      nested structures such as the configuration for a broker.
+
+HELP
+      rescue RestClient::Unauthorized
+        output << <<-UNAUTH
+Error: Credentials are required to connect to the server at #{@api_url}"
+UNAUTH
       rescue
-        output << "\nCould not connect to the server at #{@api_url}. More help is available after "
-        output << "pointing\nthe client to a Razor server"
+        output << <<-ERR
+Error: Could not connect to the server at #{@api_url}. More help is available after pointing
+the client to a Razor server
+ERR
       end
       output
     end
 
+    def show_version?
+      !!@show_version
+    end
+
     def show_help?
       !!@option_help
     end
 
+    def show_command_help?
+      !!@command_help
+    end
+
     def dump_response?
       !!@dump
     end
 
-    attr_reader :api_url
+    attr_reader :api_url, :format, :args
 
     def initialize(args)
       parse_and_set_api_url(ENV["RAZOR_API"] || DEFAULT_RAZOR_API, :env)
       @args = args.dup
-      rest = get_optparse.order(args)
-      if rest.any?
-        @navigation = rest
+      @format = 'short'
+      @args = get_optparse.order(@args)
+      @args = set_help_vars(@args)
+      if @args == ['version'] or @show_version
+        @show_version = true
+      elsif @args.any?
+        @navigation = @args.dup
       else
+        # Called with no remaining arguments to parse.
         @option_help = true
       end
     end
 
+    # This method sets the appropriate help flags `@command_help` and `@option_help`,
+    # then returns a new set of arguments.
+    def set_help_vars(rest)
+      # Find and remove 'help' variations anywhere in the command.
+      if rest.any? { |arg| ['-h', '--help'].include? arg } or
+          rest.first == 'help' or rest.drop(1).first == 'help'
+        rest = rest.reject { |arg| ['-h', '--help', 'help'].include? arg }
+        # If anything is left, assume it is a command.
+        if rest.any?
+          @command_help = true
+        else
+          @option_help = true
+        end
+      end
+      if @option_help && rest.any?
+        @command_help = true
+      end
+      rest
+    end
+
     def navigate
       @navigate ||=Navigate.new(self, @navigation)
     end

data/lib/razor/cli/transforms.rb

@@ -0,0 +1,39 @@
+module Razor::CLI
+  module Transforms
+    module_function
+    def identity(any)
+      any
+    end
+    def if_present(obj)
+      obj.nil? ? "---" : obj
+    end
+    def join_names(arr)
+      (arr.nil? or arr.empty?) ? '(none)' : arr.map { |item| item['name'] }.join(", ")
+    end
+    def nested(nested_obj)
+      (nested_obj.nil? or nested_obj.empty?) ? '(none)' : nested_obj.to_s
+    end
+    def shallow_hash(hash)
+      (hash.nil? or hash.empty?) ? '(none)' :
+          hash.map {|key, val| "#{key}: #{val}"}.join(', ')
+    end
+    def select_name(item)
+      item and item['name'] or "---"
+    end
+    def mac(mac)
+      mac ? mac.gsub(/-/, ":") : "---"
+    end
+    def name(obj)
+      obj ? obj['name'] : "---"
+    end
+    def name_if_present(obj)
+      obj ? obj['name'] : "---"
+    end
+    def count_column(hash)
+      hash['count']
+    end
+    def count(arr)
+      arr.size
+    end
+  end
+end

data/lib/razor/cli/version.rb

@@ -0,0 +1,46 @@
+# -*- encoding: utf-8 -*-
+module Razor
+  module CLI
+    # Define the Razor version, and stash it in a constant.  When we build a
+    # package for shipping we burn the version directly into this file, by
+    # modifying the text on the fly during package building.
+    #
+    # That "burns in" the value, but if that hasn't happened we do our best to
+    # work out a reasonable version number: If we are running from a git
+    # checkout, and we have git installed, determine this with `git describe`,
+    #
+    # If we don't have git, or it fails, but have the metadata, parse out some
+    # useful information directly from the checkout; this isn't great, but does
+    # give some guidance as to where the user was working.
+    #
+    # Finally, fall back to a default version placeholder.
+    #
+    #
+    # The next line is the one that our packaging tools modify, so please make
+    # sure that any change to it is discussed and agreed first.
+    version = '0.15.0'
+
+    if version == "DEVELOPMENT"
+      root = File.expand_path("../../..", File.dirname(__FILE__))
+      if File.directory? File.join(root, ".git")
+        git_version = %x{cd '#{root}' && git describe --tags --dirty --always 2>&1}
+        if $?.success?
+          version = 'v' + git_version
+        else                      # try to read manually...
+          head = File.read(File.join(root, ".git", "HEAD")) rescue nil
+          if head and match = %r{^ref: (refs/heads/(.[^\n]+))$}.match(head.lines.first)
+            version = 'git-' + match[2]
+            if sha = File.read(File.join(root, ".git", match[1]))[0,8] rescue nil
+              version += '-' + sha
+            end
+          end
+        end
+      end
+    end
+
+    # The running version of Razor.  Razor follows the tenets of [semantic
+    # versioning](http://semver.org), and this version number reflects the rules
+    # as of SemVer 2.0.0
+    VERSION = version.chomp
+  end
+end

data/lib/razor/cli/views.rb

@@ -0,0 +1,25 @@
+module Razor::CLI
+  module Views
+    module_function
+    def views
+      @views ||= YAML::load_file(File::join(File::dirname(__FILE__), "views.yaml"))
+    end
+
+    def transform(item, transform_name)
+      Razor::CLI::Transforms.send(transform_name || 'identity', item)
+    end
+
+    def find_formatting(spec, format, remaining_navigation)
+      remaining_navigation ||= ''
+      # Scope will narrow by traversing the spec.
+      scope = views
+      spec = spec ? spec.split('/').drop_while { |i| i != 'collections'} : []
+      spec = spec + remaining_navigation.split(' ')
+      while spec.any?
+        val = spec.shift
+        scope = (scope[val] or {})
+      end
+      scope["+#{format}"] or {}
+    end
+  end
+end

data/lib/razor/cli/views.yaml

@@ -0,0 +1,189 @@
+---
+
+# This file contains instructions for how the client should format various
+# objects based on the object's 'spec' path. The structure uses a `+` prefix
+# to denote metadata. `member` is used to describe a member of a group.
+#
+# Accepted metadata annotations are:
+# `+short`: This section configures what the output for the object looks like in short format.
+# `+show`: This section configures which attributes are shown in the output.
+# `+layout`: This configures whether to use 'list' or 'table' output.
+# `+column`: This changes which column is used in the field formatting.
+collections:
+  brokers:
+    +short:
+      +layout: table
+      +show:
+        name:
+        broker-type:
+        configuration:
+          +format: nested
+        policies:
+          +format: count_column
+    member:
+      +short:
+        +layout: list
+        +show:
+          name:
+          broker-type:
+          configuration:
+          policies:
+            +format: count_column
+  nodes:
+    +short:
+      +layout: table
+      +show:
+        name:
+        dhcp_mac:
+          +format: mac
+        tags:
+          +format: join_names
+        policy:
+          +format: select_name
+    member:
+      +short:
+        +layout: list
+        +show:
+          name:
+          dhcp_mac:
+            +format: mac
+          state:
+          last_checkin:
+          tags:
+            +format: join_names
+      tags:
+        +short:
+          +layout: table
+          +show:
+            name:
+            rule:
+              +format: nested
+            nodes:
+              +format: count_column
+            policies:
+              +format: count_column
+      hw_info:
+        +short:
+          +layout: list
+    log:
+      +short:
+        +layout: table
+#        +show:
+#          event:
+#          task:
+#          timestamp:
+  policies:
+    +short:
+      +layout: table
+      +show:
+        name:
+        repo:
+          +format: name
+        task:
+          +format: name
+        broker:
+          +format: name
+        enabled:
+        max_count:
+        tags:
+          +format: join_names
+        nodes:
+          +format: count_column
+    member:
+      +short:
+        +show:
+          name:
+          repo:
+            +format: name
+          task:
+            +format: name
+          broker:
+            +format: name
+          enabled:
+          max_count:
+          tags:
+            +format: join_names
+          nodes:
+            +format: count_column
+  tasks:
+    +short:
+      +layout: table
+      +show:
+        name:
+        description:
+        base:
+          +format: name_if_present
+        boot_seq:
+          +format: shallow_hash
+    member:
+      +short:
+        +show:
+          name:
+          description:
+          os:
+          boot_seq:
+  repos:
+    +short:
+      +layout: table
+      +show:
+        name:
+        iso_url:
+          +format: if_present
+        url:
+          +format: if_present
+        task:
+          +format: name
+    member:
+      +short:
+        +layout: list
+        +show:
+          name:
+          iso_url:
+            +format: if_present
+          url:
+            +format: if_present
+          task:
+            +format: name
+  tags:
+    +short:
+      +layout: table
+      +show:
+        name:
+        rule:
+          +format: nested
+        nodes:
+          +format: count_column
+        policies:
+          +format: count_column
+    member:
+      +short:
+        +layout: list
+        +show:
+          name:
+          rule:
+            +format: nested
+          nodes:
+            +format: count_column
+          policies:
+            +format: count_column
+  commands:
+    +short:
+      +layout: table
+      +show:
+        name:
+        command:
+        name parameter:
+          +format: name
+        errors:
+          +format: count
+        status:
+    member:
+      +short:
+        +show:
+          name:
+          command:
+          params:
+          errors:
+            +format: count
+          status:
+          submitted_at:

data/spec/cli/format_spec.rb

@@ -0,0 +1,77 @@
+# Needed to make the client work on Ruby 1.8.7
+unless Kernel.respond_to?(:require_relative)
+  module Kernel
+    def require_relative(path)
+      require File.join(File.dirname(caller[0]), path.to_str)
+    end
+  end
+end
+
+require "rspec/expectations"
+require_relative '../spec_helper'
+
+describe Razor::CLI::Format do
+  include described_class
+
+  def format(doc, args = {})
+    args = {:format => 'short', :args => ['something', 'else'], :show_command_help? => false}.merge(args)
+    parse = double(args)
+    format_document doc, parse
+  end
+
+  context 'additional details' do
+    it "tells additional details for a hash" do
+      doc = {'abc' => {'def' => 'ghi'}}
+      result = format doc
+      result.should =~ /Query additional details via: `razor something else \[abc\]`\z/
+    end
+    it "tells additional details for an array" do
+      doc = {'abc' => ['def']}
+      result = format doc
+      result.should =~ /Query additional details via: `razor something else \[abc\]`\z/
+    end
+    it "tells multiple additional details" do
+      doc = {'abc' => ['def'], 'ghi' => {'jkl' => 'mno'}}
+      result = format doc
+      result.should =~ /Query additional details via: `razor something else \[abc, ghi\]`\z/
+    end
+    it "tells no additional details for a string" do
+      doc = {'abc' => 'def'}
+      result = format doc
+      result.should_not =~ /Query additional details/
+    end
+    it "hides array spec array from additional details" do
+      doc = {'abc' => [], 'spec' => ['def', 'jkl']}
+      result = format doc
+      result.should =~ /Query additional details via: `razor something else \[abc\]`\z/
+    end
+    it "hides array +spec array from additional details" do
+      doc = {'abc' => [], '+spec' => ['def', 'jkl']}
+      result = format doc
+      result.should =~ /Query additional details via: `razor something else \[abc\]`\z/
+    end
+    it "only shows additional details for nested objects" do
+      doc = {'one-prop' => 'val', 'abc' => [], 'prop' => 'jkl'}
+      result = format doc
+      result.should =~ /Query additional details via: `razor something else \[abc\]`\z/
+    end
+    it "tells how to query by name" do
+      doc = {'items' => [{'name' => 'entirely'}, {'name' => 'bar'} ]}
+      result = format doc
+      result.should =~ /Query an entry by including its name, e.g. `razor something else entirely`\z/
+    end
+  end
+
+  context 'empty display' do
+    it "works right when it has nothing to display as a table" do
+      doc = {"spec"=>"http://api.puppetlabs.com/razor/v1/collections/policies", "items"=>[]}
+      result = format doc
+      result.should == "There are no items for this query."
+    end
+    it "works right when it has nothing to display as a list" do
+      doc = {"spec"=>"http://api.puppetlabs.com/razor/v1/collections/policies/member", "items"=>[]}
+      result = format doc
+      result.should == "There are no items for this query."
+    end
+  end
+end