cliqr 1.2.0 → 2.0.0

data/lib/cliqr/parser/token_factory.rb

@@ -61,7 +61,7 @@ module Cliqr
       # @param [String] name Long name of the option
       # @param [String] arg THe argument that was parsed to get the option name
       #
-      # @return [Cliqr::CLI::OptionConfig] Requested option configuration
+      # @return [Cliqr::CLI::Option] Requested option configuration
       def get_option_config(name, arg)
         fail Cliqr::Error::UnknownCommandOption,
              "unknown option \"#{arg}\"" unless @config.option?(name)

data/lib/cliqr/usage/command_usage_context.rb

@@ -0,0 +1,94 @@
+# encoding: utf-8
+
+require 'cliqr/usage/option_usage_context'
+
+module Cliqr
+  module Usage
+    # The context in which the usage template will be executed
+    #
+    # @api private
+    class CommandUsageContext
+      include Cliqr::Command::Color
+
+      # Name of the current command in context
+      #
+      # @return [String]
+      attr_reader :name
+
+      # Description of the current command
+      #
+      # @return [String]
+      attr_reader :description
+
+      # Pre-configured command's actions
+      #
+      # @return [Array<Cliqr::CLI::CommandUsageContext>]
+      attr_reader :actions
+
+      # List of options configured for current context
+      #
+      # @return [Array<Cliqr::CLI::OptionUsageContext>]
+      attr_reader :options
+
+      # Command for the current context
+      #
+      # @return [String]
+      attr_reader :command
+
+      # Wrap a [Cliqr::CLI::Config] instance for usage template
+      def initialize(type, config)
+        super(config)
+
+        @type = type
+        @config = config
+
+        @name = config.name
+        @description = config.description
+        @actions = @config.actions
+                   .map { |action| CommandUsageContext.new(type, action) }
+                   .select { |action|  type == :shell ? action.name != 'shell' : true }
+        @options = @config.options.values.map { |option| Usage::OptionUsageContext.new(option) }
+        @command = @config.command
+      end
+
+      # Check if command has a description
+      def description?
+        non_empty?(@description)
+      end
+
+      # Check if there are any preconfigured options
+      def options?
+        non_empty?(@config.options)
+      end
+
+      # Check if current command allows arguments
+      def arguments?
+        @config.arguments == Cliqr::Config::ENABLE_CONFIG
+      end
+
+      # Check if current command has any actions
+      def actions?
+        non_empty?(@actions)
+      end
+
+      # Check if the help is enabled
+      #
+      # @return [Boolean]
+      def help?
+        @config.help?
+      end
+
+      # Check if running inside shell
+      def shell?
+        @type == :shell
+      end
+
+      private
+
+      # Check if a obj is non-empty
+      def non_empty?(obj)
+        !(obj.nil? || obj.empty?)
+      end
+    end
+  end
+end

data/lib/cliqr/usage/option_usage_context.rb

@@ -0,0 +1,86 @@
+# encoding: utf-8
+
+module Cliqr
+  module Usage
+    # Wrapper of [Cliqr::CLI::OptionConfig] to be used in usage rendering
+    #
+    # @api private
+    class OptionUsageContext
+      # Name of the option
+      #
+      # @return [String]
+      attr_reader :name
+
+      # Short name of the option
+      #
+      # @return [String]
+      attr_reader :short
+
+      # Option's type
+      #
+      # @return [Symbol]
+      attr_reader :type
+
+      # Option's description
+      #
+      # @return [String]
+      attr_reader :description
+
+      # Default value for this option
+      #
+      # @return [Object]
+      attr_reader :default
+
+      # Create a new option usage context
+      def initialize(option_config)
+        @option_config = option_config
+
+        @name = @option_config.name
+        @short = @option_config.short
+        @type = @option_config.type
+        @description = @option_config.description
+        @default = @option_config.default
+      end
+
+      # Check if current option is a boolean option
+      def boolean?
+        @option_config.boolean? && !help? && !version?
+      end
+
+      # Check if the option has a short name
+      def short?
+        @option_config.short?
+      end
+
+      # Check if the option has non-empty description
+      def description?
+        @option_config.description?
+      end
+
+      # Assert if the details of this options should be printed
+      def details?
+        @option_config.description? || @option_config.type? || @option_config.default?
+      end
+
+      # Check if the option has a non-default type
+      def type?
+        @option_config.type? && !help? && !version?
+      end
+
+      # check if the option should display default setting
+      def default?
+        @option_config.default? && !help? && !version?
+      end
+
+      # Check if the option is for getting help
+      def help?
+        @option_config.name == 'help'
+      end
+
+      # Check if the option is for version
+      def version?
+        @option_config.name == 'version'
+      end
+    end
+  end
+end

data/lib/cliqr/usage/templates/partial/action_list.erb

@@ -0,0 +1,10 @@
+<% if actions? %>
+<%= bold('Available actions:') %>
+<%= black("[ Type \"#{"#{command} " unless shell?}help [action-name]\" to get more information about that action ]\n") if help? %>
+<%
+   actions.each { |action|
+%>    <%= green(action.name) %><%= " -- #{action.description}" if action.description? %>
+<%
+   }
+%>
+<% end %>

data/lib/cliqr/usage/templates/partial/command_name.erb

@@ -0,0 +1,3 @@
+<% parts = command.to_s.split(' ')
+%><%= "#{black(parts[0...-1].join(' '))}#{parts.length > 1 ? ' ' : ''}#{bold(yellow(parts[parts.length - 1]))}"
+%><% unless description.nil? || description.empty? %> -- <%= description %><% end %>

data/lib/cliqr/usage/templates/partial/option_list.erb

@@ -0,0 +1,18 @@
+<% if options? %>
+<%= bold('Available options:') %>
+<%
+   options.each { |option|
+%>
+    --<%=
+    '[no-]' if option.boolean?
+%><%=
+    option.name
+%><%=
+    ", -#{option.short}" if option.short?
+%><%=
+    if option.details?
+      "  : #{" <#{option.type}>" if option.type?}#{" #{option.description}" if option.description?}#{" (default => #{option.default.inspect})" if option.default?}"
+    end
+%><%
+   }
+end %>

data/lib/cliqr/usage/templates/partial/usage_info.erb

@@ -0,0 +1,5 @@
+<%= bold('USAGE:') %>
+    <%= command %><%=
+    ' [actions]' if actions? %><%=
+    ' [options]' if options? %><%=
+    ' [arguments]' if arguments? %>

data/lib/cliqr/usage/templates/usage/cli.erb

@@ -0,0 +1,4 @@
+<%= render(:command_name) %>
+
+<%= render(:usage_info) %>
+<%= render(:option_list) %><%= "\n" if options? %><%= render(:action_list) %>

data/lib/cliqr/usage/templates/usage/shell.erb

@@ -0,0 +1,2 @@
+<%= render(:command_name) %>
+<%= render(:action_list) %>

data/lib/cliqr/usage/usage_builder.rb

@@ -0,0 +1,59 @@
+# encoding: utf-8
+
+require 'erb'
+require 'cliqr/error'
+require 'cliqr/usage/command_usage_context'
+
+module Cliqr
+  module Usage
+    # Builds the usage information based on the configuration settings
+    #
+    # @api private
+    class UsageBuilder
+      TEMPLATES_PATH = "#{File.expand_path(File.dirname(__FILE__))}/templates"
+
+      USAGE_TYPES = {
+          :cli => "#{TEMPLATES_PATH}/usage/cli.erb",
+          :shell => "#{TEMPLATES_PATH}/usage/shell.erb"
+      }
+
+      # Create a new usage builder
+      def initialize(type)
+        @type = type
+        @template_file = USAGE_TYPES[type]
+      end
+
+      # Build the usage information
+      #
+      # @param [Cliqr::Config::Command] config Configuration of the command line interface
+      #
+      # @return [String]
+      def build(config)
+        usage_context = Usage::CommandUsageContext.new(@type, config)
+        usage_context.instance_eval do
+          def render(partial_name)
+            TemplateRenderer.render("#{TEMPLATES_PATH}/partial/#{partial_name}.erb", self)
+          end
+        end
+
+        # Add a extra newline at the end of usage text
+        "#{TemplateRenderer.render(@template_file, usage_context)}\n"
+      end
+    end
+
+    # Renders a template file based on configuration settings
+    #
+    # @api private
+    class TemplateRenderer
+      # Render a partial script
+      #
+      # @return [Nothing]
+      def self.render(template_file_path, context)
+        template_file_path = File.expand_path(template_file_path, __FILE__)
+        template = ERB.new(File.new(template_file_path).read, nil, '%')
+        result = template.result(context.instance_eval { binding })
+        Cliqr::Util.trim_newlines(result)
+      end
+    end
+  end
+end

data/lib/cliqr/util.rb

@@ -1,6 +1,6 @@
 # encoding: utf-8
 
-require 'cliqr/cli/shell_command'
+require 'cliqr/command/shell_command'
 
 module Cliqr
   # Utility methods
@@ -17,59 +17,59 @@ module Cliqr
 
     # Build a help action for a parent config
     #
-    # @return [Cliqr::CLI::Config] New action config
+    # @return [Cliqr::CLI::Action] New action config
     def self.build_help_action(config)
-      cli = Cliqr.interface do
-        name 'help'
-        description "The help action for command \"#{config.command}\" which provides details " \
-                    'and usage information on how to use the command.'
-        handler Util.help_action_handler(config)
-        help :disable if config.help?
-        shell :disable
+      Cliqr::Config::Action.new.tap do |action_config|
+        action_config.name = 'help'
+        action_config.description = \
+          "The help action for command \"#{config.command}\" which provides details " \
+          'and usage information on how to use the command.'
+        action_config.handler = Util.help_action_handler(config)
+        action_config.help = :disable if config.help?
+        action_config.finalize
       end
-      cli.config
     end
 
     # Build a help option for a parent config
     #
-    # @return [Cliqr::CLI::OptionConfig] New option config
+    # @return [Cliqr::CLI::Option] New option config
     def self.build_help_option(config)
-      Cliqr::CLI::OptionConfig.new.tap do |option_config|
+      Cliqr::Config::Option.new.tap do |option_config|
         option_config.name = 'help'
         option_config.short = 'h'
         option_config.description = "Get helpful information for action \"#{config.command}\" " \
                                     'along with its usage information.'
-        option_config.type = Cliqr::CLI::BOOLEAN_ARGUMENT_TYPE
-        option_config.operator = Cliqr::CLI::ArgumentOperator::DEFAULT_ARGUMENT_OPERATOR
+        option_config.type = Cliqr::Config::BOOLEAN_ARGUMENT_TYPE
+        option_config.operator = Cliqr::Command::ArgumentOperator::DEFAULT_ARGUMENT_OPERATOR
         option_config.finalize
       end
     end
 
     # Build a version action for a parent config
     #
-    # @return [Cliqr::CLI::Config] New action config
+    # @return [Cliqr::CLI::Action] New action config
     def self.build_version_action(config)
-      cli = Cliqr.interface do
-        name 'version'
-        description "Get version information for command \"#{config.command}\"."
-        handler do
+      Cliqr::Config::Action.new.tap do |action_config|
+        action_config.name = 'version'
+        action_config.description = "Get version information for command \"#{config.command}\"."
+        action_config.arguments = Cliqr::Config::DISABLE_CONFIG
+        action_config.handler = proc do
           puts config.version
         end
-        shell :disable
+        action_config.finalize
       end
-      cli.config
     end
 
     # Build a version option for a parent config
     #
-    # @return [Cliqr::CLI::OptionConfig] New option config
+    # @return [Cliqr::CLI::Option] New option config
     def self.build_version_option(config)
-      Cliqr::CLI::OptionConfig.new.tap do |option_config|
+      Cliqr::Config::Option.new.tap do |option_config|
         option_config.name = 'version'
         option_config.short = 'v'
         option_config.description = "Get version information for command \"#{config.command}\"."
-        option_config.type = Cliqr::CLI::BOOLEAN_ARGUMENT_TYPE
-        option_config.operator = Cliqr::CLI::ArgumentOperator::DEFAULT_ARGUMENT_OPERATOR
+        option_config.type = Cliqr::Config::BOOLEAN_ARGUMENT_TYPE
+        option_config.operator = Cliqr::Command::ArgumentOperator::DEFAULT_ARGUMENT_OPERATOR
         option_config.finalize
       end
     end
@@ -82,21 +82,53 @@ module Cliqr
         fail Cliqr::Error::IllegalArgumentError,
              "too many arguments for \"#{command}\" command" if arguments.length > 1
         action_config = arguments.length == 0 ? config : config.action(arguments.first)
-        puts Cliqr::CLI::UsageBuilder.build(action_config)
+        puts Cliqr::Usage::UsageBuilder.new(environment).build(action_config)
       end
     end
 
     # Build a shell action for a parent config
     #
-    # @return [Cliqr::CLI::Config] New action config
-    def self.build_shell_action(config)
-      cli = Cliqr.interface do
-        name 'shell'
-        description "Execute a shell in the context of \"#{config.command}\" command."
-        handler Cliqr::CLI::ShellCommand
-        shell :disable
+    # @return [Cliqr::CLI::Action] New action config
+    def self.build_shell_action(config, shell_config)
+      Cliqr::Config::Action.new.tap do |action_config|
+        if shell_config.name?
+          action_config.name = shell_config.name
+        else
+          action_config.name = 'shell'
+        end
+
+        action_config.handler = Cliqr::Command::ShellCommand.new(shell_config)
+        action_config.arguments = Cliqr::Config::DISABLE_CONFIG
+
+        # allow description to be overridden
+        description = shell_config.description
+        description = "Execute a shell in the context of \"#{config.command}\" command." \
+          unless shell_config.description?
+        action_config.description = description
+
+        action_config.options = shell_config.options
+        action_config.events = shell_config.events
+
+        action_config.instance_eval do
+          def skip_validation?
+            true
+          end
+        end
+
+        action_config.finalize
+      end
+    end
+
+    # Build shell config for a parent config
+    #
+    # @return [Cliqr::CLI::Shell] New action config
+    def self.build_shell_config(config)
+      Cliqr::Config::Shell.new.tap do |shell_config|
+        shell_config.enabled = config.actions?
+        shell_config.prompt = Command::ShellPromptBuilder.new(config)
+        shell_config.banner = Command::ShellBannerBuilder.new
+        shell_config.finalize
       end
-      cli.config
     end
 
     # Sanitize raw command line arguments
@@ -128,8 +160,23 @@ module Cliqr
     # @return [Proc]
     def self.forward_to_help_handler
       proc do
+        fail Cliqr::Error::IllegalArgumentError,
+             'no arguments allowed for default help action' unless arguments.empty?
         forward "#{command} help"
       end
     end
+
+    # Remove newlines from the end of a string
+    #
+    # @return [String]
+    def self.trim_newlines(str)
+      index = str.length - 1
+      count = 0
+      while str[index] == "\n" && index >= 0
+        count += 1
+        index -= 1
+      end
+      str[0...-count]
+    end
   end
 end