lucie-lib 0.0.19 → 0.0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d360d1b1df80af97909d1adaf500676d1b1e3458
-  data.tar.gz: d7dd3d37e576f03d004a4bbda818389f171ea0a7
+  metadata.gz: 87f0e44f7eec657401b9a2c77468dc9c61f216c2
+  data.tar.gz: 97b29ace94517aeff18c3398c93dc8f4659dff4f
 SHA512:
-  metadata.gz: ae4610d8dbd353d7e39ed7a5ed5f491af07c13b4b3ecf4ab3bee58d8535014725bb80dc826c99eca21ed9025f0b4f597b88e4dcc310d3a7f6ff9d6c44385f615
-  data.tar.gz: dbc5258cbf7d2d7a1575b7f85efd6ee74f411e8ef4b0b2e5dec27c8ed63ced6afa272952d60fcfa1377d482e27cd6c48f1f9b5d81be6fab4c4e815b275e29733
+  metadata.gz: aaaa30a83a84dce02f4025757df1d3f680a9496750fdd5d3343a8c75366c40bee0d8ec537db3361ad32b0339eec9554d300547088482f56f1e06f9536cc9ba46
+  data.tar.gz: 0f6700a31e0a14f325c12a6ad73b6cc43407c9204060ced25b199f98e909a37e16528d35b6c69d75601f39f6039816f062352acfae28efa661dc62d7e59bdb28

data/lib/lucie/app.rb

@@ -1,34 +1,75 @@
-
-
 module Lucie
-  # App responsible for configuring and launch the application
-  # based on Lucie application framework.
+
+  #
+  # Lucie::App represents the application context. When a lucie application starts,
+  # it requires information about its environment, like root path, env, command. App
+  # also responsible for loading the right controller and to execute the process how the
+  # input will be parsed and the business logic is executed.
   #
   class App
 
     class << self
+      #
+      # Let the exception leave the application when any occur.
+      #
+      # Normally the application doesn't raise any exception, just stops quietly.
+      # When the application is under debugging, developer needs more, detailed description
+      # about the problem. Suggested to turn this attribute on during developing.
+      #
+      #  App.raise_exception = true
+      #
       attr_accessor :raise_exception
+
+      # Sets the log level of the application.
+      #
       attr_accessor :log_level
+
+      #
+      # Root directory of the source of application.
+      #
+      # Template and other source paths are calculated relatively to this directory.
+      #
       attr_accessor :root
+
       @raise_exception = false
       @log_level = :info
     end
 
+    # Command line input that is being executed. Usually it equals with ARGV.
+    #
     attr_reader :command
+
+    # Root of the application. Same as App.root, it's a reference for that.
+    #
     attr_reader :root
+
+    # The directory where from the application has been executed.
+    #
     attr_reader :pwd
 
+    # Initializes and starts the applicaiton. Shortcut for self.init && self.start
+    #
     def self.run(command = ARGV, root = nil, pwd = nil)
       root ||= File.expand_path("..", File.dirname(Kernel.caller[0]))
       instance = self.init(command, root, pwd)
       self.start(instance)
     end
 
+    # Initializes the application.
+    #
+    # @param command [Array or String]
+    # @param root [String] Path of the root of the app. [default: current application's path]
+    # @param pwd [String] Path of the terminal position.
+    #
     def self.init(command = ARGV, root = nil, pwd = nil)
       root ||= File.expand_path("..", File.dirname(Kernel.caller[0]))
       self.new(command, root, pwd)
     end
 
+    # Starts the application instance and returns its exit status.
+    #
+    # @param instance [App] Application instance
+    #
     def self.start(instance)
       instance.start
       instance.exit_value
@@ -36,21 +77,24 @@ module Lucie
 
     def initialize(command, root, pwd = nil)
       @root = root
-      @command = CommandLineParser.new(command)
+      @command = Core::CommandLineParser.new(command)
       @exit_value ||= 0
       @task = nil
       @pwd = pwd || ENV["PWD"]
       Dir.chdir(@pwd)
     end
 
+    # Starts the application.
     def start
       help? ? call_help : call_method_invoking_process
     end
 
+    # Exit status of the application
     def exit_value
       @exit_value
     end
 
+    # Environment of the application. Contains the ENV of the terminal.
     def env
       ENV
     end

data/lib/lucie/command_line_parser.rb

@@ -1,87 +1,128 @@
 require "lucie/command_line_slicer"
 
-class CommandLineParser
+module Lucie
 
-  attr_reader :options
+  module Core
 
-  def initialize(parameters)
-    @params_str = parameters.class == Array ? parameters.join(" ") : parameters
-    @options = {}
-    @options[:args] = []
-    @latest_option = nil
+    # Command line parser extracts the controller name and action from the
+    # application input and prepares the params hash for the controller.
+    #
+    class CommandLineParser
 
-    parse_options()
-  end
+      attr_reader :options
 
-  def [](name)
-    @options[name]
-  end
+      # Initializes a CommandLineParser
+      #
+      # @param parameters [String|Array] Input that needs to be processed
+      #
+      def initialize(parameters)
+        @params_str = parameters.class == Array ? parameters.join(" ") : parameters
+        @options = {}
+        @options[:args] = []
+        @latest_option = nil
 
-  def shift
-    @options[:args].shift
-  end
+        parse_options()
+      end
 
-  def pair(short, long)
-    short_p = remove_dashes(short).to_sym
-    long_p = remove_dashes(long).to_sym
+      # Gets the value of an option
+      #
+      # For "--option value" the self[:option] returns "value"
+      #
+      # @param name [Symbol] Name of the option
+      def [](name)
+        @options[name]
+      end
 
-    if @options[short_p].class == String
-      @options[long_p] = @options[short_p]
-    else
-      @options[short_p] = @options[long_p]
-    end
-  end
+      # Shift the parameter list. Useful for removing the controller's name
+      # from the beginning.
+      #
+      def shift
+        @options[:args].shift
+      end
 
-  def has_option?(option)
-    @options[remove_dashes(option).to_sym] || false
-  end
+      # Pairs short and long options.
+      #
+      # When -o is a shortened version of --option, then params[:o] must return
+      # the same value as params[:option]. This method pairs these options.
+      #
+      # @param short [Symbol] Short version of the option
+      # @param long  [Symbol] Long version of the option
+      #
+      def pair(short, long)
+        short_p = remove_dashes(short).to_sym
+        long_p = remove_dashes(long).to_sym
+
+        if @options[short_p].class == String
+          @options[long_p] = @options[short_p]
+        else
+          @options[short_p] = @options[long_p]
+        end
+      end
 
-  def has_arg?(option)
-    @options[:args].include?(option)
-  end
+      # Is the option defined?
+      #
+      # @param option [Symbol] Name of the option
+      def has_option?(option)
+        @options[remove_dashes(option).to_sym] || false
+      end
 
-  def args
-    @options[:args].dup
-  end
+      # Get the values which has no options.
+      #
+      # Arguments are values without any option or tag. When the option
+      # name is undefined, the value gets placed in args.
+      #
+      def args
+        @options[:args].dup
+      end
 
-private
+      # Checks whether the value is in the args.
+      #
+      # @param option [String] Name of the argument.
+      #
+      def has_arg?(option)
+        @options[:args].include?(option)
+      end
 
-  def parse_options
-    array_of_options.each do |option|
-      if is_option?(option)
-        save_option(option)
-      else
-        save_parameter(option)
+    private
+
+      def parse_options
+        array_of_options.each do |option|
+          if is_option?(option)
+            save_option(option)
+          else
+            save_parameter(option)
+          end
+        end
       end
-    end
-  end
 
-  def is_option?(option)
-    option =~ /^-/
-  end
+      def is_option?(option)
+        option =~ /^-/
+      end
 
-  def remove_dashes(option)
-    option.gsub(/^-+/, "")
-  end
+      def remove_dashes(option)
+        option.gsub(/^-+/, "")
+      end
 
-  def save_option(option)
-    without_dashes = remove_dashes(option)
-    @options[without_dashes.to_sym] = true
-    @latest_option = without_dashes.to_sym
-  end
+      def save_option(option)
+        without_dashes = remove_dashes(option)
+        @options[without_dashes.to_sym] = true
+        @latest_option = without_dashes.to_sym
+      end
 
-  def save_parameter(option)
-    if @options[@latest_option].class == String
-      @options[@latest_option] += [" ", option].join
-    elsif !@latest_option
-      @options[:args] ||= []
-      @options[:args] << option
-    else
-      @options[@latest_option] = option
-    end
-  end
+      def save_parameter(option)
+        if @options[@latest_option].class == String
+          @options[@latest_option] += [" ", option].join
+        elsif !@latest_option
+          @options[:args] ||= []
+          @options[:args] << option
+        else
+          @options[@latest_option] = option
+        end
+      end
 
-  def array_of_options
-    CommandLineSlicer.new(@params_str).to_a
+      def array_of_options
+        Core::CommandLineSlicer.new(@params_str).to_a
+      end
+    end
   end
 end

data/lib/lucie/command_line_slicer.rb

@@ -1,77 +1,90 @@
-class CommandLineSlicer
-  def initialize(line)
-    @line = line.split("")
-    @parts = []
-    @neutral_status = false
-    @quotation_open = false
-    @scanned = ""
-  end
+module Lucie
+
+  module Core
+    # Command Line Slicer can split the input string to words.
+    #
+    class CommandLineSlicer
+
+      # Initializes a CommandLineSlicer object with the input.
+      #
+      # @param line [String] The input that need to be sliced
+      def initialize(line)
+        @line = line.split("")
+        @parts = []
+        @neutral_status = false
+        @quotation_open = false
+        @scanned = ""
+      end
 
-  def to_a
-    each_char do |char|
-      if boundary? char
+      # Returns the words of the input in an array.
+      #
+      def to_a
+        each_char do |char|
+          if boundary? char
+            save_chunk
+          elsif in_quoatation? char
+            toggle_quotation_state
+          elsif neutral? char
+            neutral :on
+          else
+            neutral :off
+            append char
+          end
+        end
         save_chunk
-      elsif in_quoatation? char
-        toggle_quotation_state
-      elsif neutral? char
-        neutral :on
-      else
-        neutral :off
-        append char
       end
-    end
-    save_chunk
-  end
 
-private
+    private
 
-  def append(char)
-    @scanned += char
-  end
+      def append(char)
+        @scanned += char
+      end
 
-  def each_char(&blk)
-    while @line.size > 0
-      yield(@line.shift)
-    end
-  end
+      def each_char(&blk)
+        while @line.size > 0
+          yield(@line.shift)
+        end
+      end
 
-  def toggle_quotation_state
-    @quotation_open = !@quotation_open
-  end
+      def toggle_quotation_state
+        @quotation_open = !@quotation_open
+      end
 
-  def save_chunk
-    @parts << @scanned if @scanned != ""
-    @scanned = ""
-    @parts
-  end
+      def save_chunk
+        @parts << @scanned if @scanned != ""
+        @scanned = ""
+        @parts
+      end
 
-  def neutral(sym)
-    @neutral_status = (sym == :on)
-  end
+      def neutral(sym)
+        @neutral_status = (sym == :on)
+      end
 
-private
+    private
 
-  def neutral_chars
-    ["\\"]
-  end
+      def neutral_chars
+        ["\\"]
+      end
 
-  def boundary_chars
-    [" "]
-  end
+      def boundary_chars
+        [" "]
+      end
 
-  def quotation_chars
-    ["\"", "'"]
-  end
+      def quotation_chars
+        ["\"", "'"]
+      end
 
-  def boundary?(char)
-    boundary_chars.include?(char) && !@neutral_status && !@quotation_open
-  end
+      def boundary?(char)
+        boundary_chars.include?(char) && !@neutral_status && !@quotation_open
+      end
 
-  def in_quoatation?(char)
-    quotation_chars.include?(char) && !@neutral_status
-  end
+      def in_quoatation?(char)
+        quotation_chars.include?(char) && !@neutral_status
+      end
 
-  def neutral?(char)
-    neutral_chars.include?(char) && !@neutral_status
+      def neutral?(char)
+        neutral_chars.include?(char) && !@neutral_status
+      end
+    end
   end
 end

data/lib/lucie/controller/base.rb

@@ -9,7 +9,7 @@ module Lucie
 
       class << self
         @validators = []
-        @params = CommandLineParser.new("")
+        @params = Core::CommandLineParser.new("")
       protected
         @before_filter_args = []
         attr_accessor :before_filter_args

data/lib/lucie/exceptions.rb

@@ -1,27 +1,28 @@
 module Lucie
-  class RequestError < StandardError
-    def initialize(validator)
-      super "#{validator.description} (#{validator.short_option}) is mandatory parameter"
+  module Exceptions
+    class RequestError < StandardError
+      def initialize(validator)
+        super "#{validator.description} (#{validator.short_option}) is mandatory parameter"
+      end
     end
-  end
 
-  class ControllerNotFound < StandardError
-    def initialize(controller_name)
-      super "Controller is not found for #{controller_name}."
+    class ControllerNotFound < StandardError
+      def initialize(controller_name)
+        super "Controller is not found for #{controller_name}."
+      end
     end
-  end
 
-  class ActionNotFound < StandardError
-    def initialize(action, controller)
-      super "#{action} is not found in #{controller}."
+    class ActionNotFound < StandardError
+      def initialize(action, controller)
+        super "#{action} is not found in #{controller}."
+      end
     end
-  end
 
-  class ExitRequest < Exception
-    attr_reader :exit
-    def initialize(exit)
-      @exit = exit
+    class ExitRequest < Exception
+      attr_reader :exit
+      def initialize(exit)
+        @exit = exit
+      end
     end
   end
-
 end

data/lib/lucie/validators/base.rb

@@ -1,4 +1,11 @@
 module Lucie
+  #
+  # Validators are useful to verify input data. Example for validator:
+  #
+  #   class Controller
+  #     optional "-h", "--help", "This is the help"
+  #   end
+  #
   module Validators
     class Base
       def initialize(*args)

data/lib/lucie/validators/mandatory_option.rb

@@ -1,5 +1,8 @@
 module Lucie
   module Validators
+    #
+    # Mandatory option is able to force out an option or input for the application.
+    #
     module MandatoryOption
 
       class Validator < Base

data/lib/lucie/version.rb

@@ -1,3 +1,3 @@
 module Lucie
-  VERSION = "0.0.19"
+  VERSION = "0.0.20"
 end

data/lib/lucie.rb

@@ -1,10 +1,42 @@
+# The MIT License (MIT)
+
+# Copyright (c) 2014 Laszlo Papp, <laszlo.papp@bteam.hu>
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
 $LOAD_PATH << File.expand_path("..", __FILE__)
 
 require "lucie/version"
 require "lucie/exceptions"
 
+
+# Lucie is a modular MVC terminal application framework. With Lucie easy to create
+# command line application using controllers to describe the process, models to store
+# additional data permanently, and views to generate configuration files for applications.
+#
+# Lucie-lib is a glue for these MVC components and provide additional helper methods to
+# support faster and easier developing.
+#
 module Lucie
 
+  include ::Lucie::Exceptions
+
   module Controller
     autoload :ExitRequest, "lucie/controller/exit_request"
   end

data/test/unit/command_line_parser_test.rb

@@ -2,6 +2,8 @@ require "test_helper"
 
 class CommandLineParserTest < MiniTest::Spec
 
+  include Core
+
   should "parse empty string" do
     parser = CommandLineParser.new ""
     hash = {:args => []}

data/test/unit/command_line_slicer_test.rb

@@ -2,6 +2,8 @@ require "test_helper"
 
 class CommandLineSlicerTest < MiniTest::Unit::TestCase
 
+  include Lucie::Core
+
   def test_empty
     assert_equal [], CommandLineSlicer.new("").to_a
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lucie-lib
 version: !ruby/object:Gem::Version
-  version: 0.0.19
+  version: 0.0.20
 platform: ruby
 authors:
 - Nucc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-10 00:00:00.000000000 Z
+date: 2014-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake