libis-tools 0.9.20 → 0.9.21

data/lib/libis/tools/parameter.rb

@@ -1,33 +1,64 @@
 # encoding: utf-8
 require 'date'
 require 'libis/tools/extend/struct'
+require 'concurrent/hash'
 
 module Libis
   module Tools
 
+    # Exception that will be raised when a parameter value does not pass the validation checks.
     class ParameterValidationError < RuntimeError;
     end
+
+    # Exception that will be raised when an attempt is made to change the value of a frozen parameter.
     class ParameterFrozenError < RuntimeError;
     end
 
     # noinspection RubyConstantNamingConvention
-    Parameter = ::Struct.new(:name, :default, :datatype, :description, :constraint, :frozen, :options) do
 
+    # A {Parameter} is like a class instance attribute on steroids. Contrary to regular attributes, {Parameter}s are
+    # type-safe, can have a descriptive text explaining their use, a constraint that limits the values and any other
+    # properties for an application to use for their needs.
+    #
+    # Parameters are inherited from base classes and can be overwritten without affecting the parameters in the parent
+    # class. For instance, a regular parameter in the parent class can be given a fixed value in the child class by
+    # giving it a default value and setting it's frozen property to true. The same paremter in the parent class
+    # instances will still be modifieable. But the parameter in the child class instances will be frozen, even if
+    # accessed via the methods on parent class.
+    #
+    # Important: the parameter will exist both on the class level as on the instance level, but the parameter on the
+    # class level is the parameter definition as described in the {Parameter} class. On the instance level, there are
+    # merely some parameter methods that access the parameter instance values with the help of the parameter definitions
+    # on the class. The implementation of the parameter instances is dealt with by the {ParameterContainer} module.
+    class Parameter < Struct.new(:name, :default, :datatype, :description, :constraint, :frozen, :options)
+
+      # Create a Parameter instance.
+      # @param [Array] args The values for:
+      #     * name - Required. String for the name of the parameter. Any valid attribute name is acceptable.
+      #     * default value - Any value. Will be coverted to the given datatype if present. Default is nil.
+      #     * datatype - String. One of: bool, string, int, float, datetime, array, hash. If omitted it will be derived
+      #       from the default value or set to the default 'string'.
+      #     * description - String describing the parameter's use.
+      #     * constraint - Array, Range, RegEx or single value. Default is nil meaning no constraint.
+      #     * frozen - Boolean. Default is false; if true the parameter value cannot be changed from the default value.
+      #     * options - Any Hash. It's up to the applcation to interprete and use this info.
+      #    datatype can be omitted if the type can be derived from the
       def initialize(*args)
-        # noinspection RubySuperCallWithoutSuperclassInspection
         super(*args)
         self[:options] ||= {}
         self[:datatype] ||= guess_datatype
       end
 
+      # Duplicates the parameter
       def dup
-        # noinspection RubySuperCallWithoutSuperclassInspection
         new_obj = super
         # noinspection RubyResolve
         new_obj[:options] = Marshal.load(Marshal.dump(self[:options]))
         new_obj
       end
 
+      # Merges other parameter data into the current parameter
+      # @param [::Libis::Tools::Parameter] other parameter definition to copy properties from
       def merge!(other)
         other.each do |k,v|
           if k == :options
@@ -39,39 +70,58 @@ module Libis
         self
       end
 
+      # Retrieve a specific property of the parameter.
+      # If not found in the regular properties, the options Hash is scanned for the property.
+      # @param [Symbol] key name of the property
       def [](key)
-        # noinspection RubySuperCallWithoutSuperclassInspection
         return super(key) if members.include?(key)
         self[:options][key]
       end
 
+      # Set a property of the parameter.
+      # If the property is not one of the regular properties, the property will be set in the options Hash.
+      # @param (see #[])
+      # @param [Object] value value for the property. No type checking happens on this value
       def []=(key, value)
-        # noinspection RubySuperCallWithoutSuperclassInspection
         return super(key, value) if members.include?(key)
         self[:options][key] = value
       end
 
+      # Convience method to create a new {Parameter} from a Hash.
+      # @param [Hash] h Hash with parameter definition properties
       def self.from_hash(h)
         h.each { |k, v| self[k.to_s.to_sym] = v }
       end
 
+      # Dumps the parameter properties into a Hash.
+      # The options properties are merged into the hash. If you do not want that, use Struct#to_h instead.
+      #
+      # @return [Hash] parameter definition properties
       def to_h
-        # noinspection RubySuperCallWithoutSuperclassInspection
         super.inject({}) do |hash, key, value|
           key == :options ? value.each { |k, v| hash[k] = v } : hash[key] = value
           hash
         end
       end
 
+      # Valid input strings for boolean parameter value, all converted to 'true'
       TRUE_BOOL = %w'true yes t y 1'
+      # Valid input strings for boolean parameter value, all converted to 'false'
       FALSE_BOOL = %w'false no f n 0'
 
+      # Parse any value and try to convert to the correct datatype and check the constraints.
+      # Will throw an exception if not valid.
+      # @param [Object] value Any value to parse, strings are best supported.
+      # @return [Object] checked and converted value
       def parse(value = nil)
         result = value.nil? ? self[:default] : convert(value)
         check_constraint(result)
         result
       end
 
+      # Parse any value and try to convert to the correct datatype and check the constraints.
+      # Will return false if not valid, true otherwise.
+      # @param [Object] value Any value to check
       def valid_value?(value)
         begin
           parse(value)
@@ -80,7 +130,6 @@ module Libis
         end
         true
       end
-
       private
 
       def guess_datatype
@@ -105,14 +154,14 @@ module Libis
       end
 
       def convert(v)
-        case self[:datatype]
+        case self[:datatype].to_s.downcase
           when 'boolean', 'bool'
             return true if TRUE_BOOL.include?(v.to_s.downcase)
             return false if FALSE_BOOL.include?(v.to_s.downcase)
             raise ParameterValidationError, "No boolean information in '#{v.to_s}'. " +
                                               "Valid values are: '#{TRUE_BOOL.join('\', \'')}" +
                                               "' and '#{FALSE_BOOL.join('\', \'')}'."
-          when 'string', nil
+          when 'string', 'nil'
             return v.to_s
           when 'int'
             return Integer(v)
@@ -162,28 +211,88 @@ module Libis
 
     end # Parameter
 
+    # To use the parameters a class should include the ParameterContainer module and add parameter
+    # statements to the body of the class definition.
+    #
+    # Besides enabling the {::Libis::Tools::ParameterContainer::ClassMethods#parameter parameter} class method to
+    # define parameters, the module adds the class method
+    # {::Libis::Tools::ParameterContainer::ClassMethods#parameter_defs parameter_defs} that will return
+    # a Hash with parameter names as keys and their respective parameter definitions as values.
+    #
+    # On each class instance the {::Libis::Tools::ParameterContainer#parameter parameter} method is added and serves
+    # as both getter and setter for parameter values.
+    # The methods {::Libis::Tools::ParameterContainer#[] []} and {::Libis::Tools::ParameterContainer#[]= []=} serve as
+    # aliases for the getter and setter calls.
+    #
+    # Additionally two protected methods are available on the instance:
+    # * {::Libis::Tools::ParameterContainer#parameters parameters}: returns the Hash that keeps track of the current
+    #   parameter values for the instance.
+    # * {::Libis::Tools::ParameterContainer#get_parameter_definition get_parameter_defintion}: retrieves the parameter
+    #   definition from the instance's class for the given parameter name.
+    #
+    # Any class that derives from a class that included the ParameterContainer module will automatically inherit all
+    # parameter definitions from all of it's base classes and can override any of these parameter definitions e.g. to
+    # change the default values for the parameter.
+    #
     module ParameterContainer
 
+      # Methods created on class level.
       module ClassMethods
 
+        # Get a list of all parameter definitions.
+        # The list is initialized with duplicates of the parameter definitions of the parent class and
+        # each new parameter definition updates or appends the list.
+        # @return [Hash] with parameter names as keys and {Parameter} instance as value.
         def parameter_defs
           return @parameters if @parameters
-          @parameters = Hash.new
-          begin
-            self.superclass.parameter_defs.
-                each_with_object(@parameters) do |(name, param), hash|
-              if hash.has_key?(name)
-                hash[name].merge!(param)
-              else
-                hash[name] = param.dup
+            @parameters = ::Concurrent::Hash.new
+            begin
+              self.superclass.parameter_defs.
+                  each_with_object(@parameters) do |(name, param), hash|
+                  hash[name] = param.dup
               end
+            rescue NoMethodError
+              # ignored
             end
-          rescue NoMethodError
-            # ignored
-          end
-          @parameters
+            @parameters
         end
 
+        # DSL method that allows creating parameter definitions on the class level.
+        #
+        # It takes only one mandatory argument which is a Hash. The first entry is interpreted as '<name>: <default>'.
+        # The name for the parameter should be unique and the default value can be any value
+        # of type TrueClass, FalseClass, String, Integer, Float, Date, Time, DateTime, Array, Hash or nil.
+        #
+        # The second up to last Hash entries are optional properties for the parameter. These are:
+        # * datatype: the type of values the parameter will accept. Valid values are:
+        #   * 'bool' or 'boolean'
+        #   * 'string'
+        #   * 'int'
+        #   * 'float'
+        #   * 'datetime'
+        #   * 'array'
+        #   * 'hash'
+        #   Any other value will raise an Exception when the parameter is used. The value is case-insensitive and
+        #   if not present, the datatype will be derived from the default value with 'string' being the default for
+        #   NilClass. In any case the parameter will try its best to convert supplied values to the proper data type.
+        #   For instance, an Integer parameter will accept 3, 3.1415, '3' and Rational(10/3) as valid values and
+        #   store them as the integer value 3. Likewise DateTime parameters will try to interprete date and time strings.
+        # * description: any descriptive text you want to add to clarify what this parameter is used for.
+        #   Any tool can ask the class for its parameters and - for instance - can use this property to provide help
+        #   in a GUI when asking the user for input.
+        # * constraint: adds a validation condition to the parameter. The condition value can be:
+        #   * an array: only values that convert to a value in the list are considered valid.
+        #   * a range: only values that convert to a value in the given range are considered valid.
+        #   * a regular expression: only values that match the regular expression are considered valid.
+        #   * a string: only values that are '==' to the constraint are considered valid.
+        # * frozen: if set to true, prevents the class instance to set the parameter to any value other than
+        #   the default. Mostly useful when a derived class needs a parameter in the parent class to be set to a
+        #   specific value. Setting a value on a frozen parameter with the 'parameter(name,value)' method throws a
+        #   {::Libis::Tools::ParameterFrozenError}.
+        # * options: a hash with any additional properties that you want to associate to the parameter. Any key-value pair in this
+        #   hash is added to the retrievable properties of the parameter. Likewise any property defined, that is not in the list of
+        #   known properties is added to the options hash. In this aspect the ::Libis::Tools::Parameter class behaves much like an
+        #   OpenStruct even though it is implemented as a Struct.
         def parameter(options = {})
           return self.parameter_defs[options] unless options.is_a? Hash
           return nil if options.keys.empty?
@@ -198,12 +307,22 @@ module Libis
 
       end
 
+      # @!visibility private
       def self.included(base)
         base.extend(ClassMethods)
       end
 
+      # Special constant to indicate a parameter has no value set. Nil cannot be used as it is a valid value.
       NO_VALUE = '##NAV##'
 
+      # Getter/setter for parameter instances
+      # With only one argument (the parameter name) it returns the current value for the parameter, but the optional
+      # second argument will cause the method to set the parameter value. If the parameter is not available or
+      # the given value is not a valid value for the parameter, the method will return the special constant
+      # {::Libis::Tools::ParameterContainer::NO_VALUE NO_VALUE}.
+      #
+      # Setting a value on a frozen parameter with the 'parameter(name,value)' method throws a
+      # {::Libis::Tools::ParameterFrozenError} exception.
       def parameter(name, value = NO_VALUE)
         param_def = get_parameter_definition(name)
         return NO_VALUE unless param_def
@@ -219,10 +338,14 @@ module Libis
         end
       end
 
+      # Alias for the {#parameter} getter.
       def [](name)
         parameter(name)
       end
 
+      # Alias for the {#parameter} setter.
+      # The only difference is that in case of a frozen parameter, this method silently ignores the exception,
+      # but the default value still will not be changed.
       def []=(name, value)
         parameter name, value
       rescue ParameterFrozenError

data/lib/libis/tools/thread_safe.rb

@@ -0,0 +1,31 @@
+require 'monitor'
+
+module Libis
+  module Tools
+
+    # Module to safely create a mutex for creating thread safe classes.
+    #
+    # Usage: include this module in a class or extend a module with this one.
+    module ThreadSafe
+
+      # Access the instance mutex
+      def mutex
+        self.class.class_mutex.synchronize do
+          @mutex ||= Monitor.new
+        end
+      end
+
+      # @!visibility private
+      module MutexCreator
+        attr_accessor :class_mutex
+      end
+
+      # @!visibility private
+      def self.included(klass)
+        klass.extend(MutexCreator)
+        # noinspection RubyResolve
+        klass.class_mutex = Monitor.new
+      end
+    end
+  end
+end

data/lib/libis/tools/version.rb

@@ -1,5 +1,5 @@
 module Libis
   module Tools
-    VERSION = '0.9.20'
+    VERSION = '0.9.21'
   end
 end

data/lib/libis/tools/xml_document.rb

@@ -9,21 +9,19 @@ module Libis
 
     # noinspection RubyTooManyMethodsInspection
 
-
     # This class embodies most used features of Nokogiri, Nori and Gyoku in one convenience class. The Nokogiri document
     # is stored in the class variable 'document' and can be accessed and manipulated directly - if required.
     #
     # In the examples we assume the following XML code:
     #
-    #           <?xml version="1.0" encoding="utf-8"?>
-    #           <patron>
-    #               <name>Harry Potter</name>
-    #               <barcode library='Hogwarts Library'>1234567890</barcode>
-    #               <access_level>student</access_level>
-    #               <email>harry.potter@hogwarts.edu</email>
-    #               <email>hpotter@JKRowling.com</email>
-    #           </patron>
-
+    #     <?xml version="1.0" encoding="utf-8"?>
+    #     <patron>
+    #       <name>Harry Potter</name>
+    #       <barcode library='Hogwarts Library'>1234567890</barcode>
+    #       <access_level>student</access_level>
+    #       <email>harry.potter@hogwarts.edu</email>
+    #       <email>hpotter@JKRowling.com</email>
+    #     </patron>
     class XmlDocument
 
       attr_accessor :document
@@ -38,8 +36,9 @@ module Libis
         !invalid?
       end
 
-      # Create new XmlDocument instance. The object will contain a new and emtpy Nokogiri XML Document. The object will
-      # not be valid until a root node is added.
+      # Create new XmlDocument instance.
+      # The object will contain a new and emtpy Nokogiri XML Document.
+      # The object will not be valid until a root node is added.
       # @param [String] encoding character encoding for the XML content; default value is 'utf-8'
       # @return [XmlDocument] new instance
       def initialize(encoding = 'utf-8')
@@ -53,7 +52,6 @@ module Libis
       def self.open(file)
         doc = XmlDocument.new
         doc.document = Nokogiri::XML(File.open(file))
-        # doc.document = Nokogiri::XML(File.open(file), &:noblanks)
         doc
       end
 
@@ -63,7 +61,6 @@ module Libis
       def self.parse(xml)
         doc = XmlDocument.new
         doc.document = Nokogiri::XML.parse(xml)
-        # doc.document = Nokogiri::XML.parse(xml, &:noblanks)
         doc
       end
 
@@ -83,7 +80,6 @@ module Libis
       # @param [String] file name of the file to save to
       # @param [Integer] indent amount of space for indenting; default 2
       # @param [String] encoding character encoding; default 'utf-8'
-      # @return [nil]
       def save(file, indent = 2, encoding = 'utf-8')
         fd = File.open(file, 'w')
         @document.write_xml_to(fd, :indent => indent, :encoding => encoding)
@@ -92,7 +88,7 @@ module Libis
 
       # Export the XML Document to an XML string.
       # @param [Hash] options options passed to the underlying Nokogiri::XML::Document#to_xml; default is:
-      #  {indent: 2, encoding: 'utf-8'}
+      #     !{indent: 2, encoding: 'utf-8'}
       # @return [String] a string
       def to_xml(options = {})
         options = {indent: 2, encoding: 'utf-8', save_with: Nokogiri::XML::Node::SaveOptions::DEFAULT_XML}.merge(options)
@@ -102,7 +98,8 @@ module Libis
       # Export the XML Document to a Hash.
       #
       # @note The hash is generated using the Nori gem. The options passed to this call are used to configure Nori in
-      #       the constructor call. For content and syntax see the {Nori} documentation. Nori also uses an enhanced
+      #       the constructor call. For content and syntax see the
+      #       {http://www.rubydoc.info/gems/nori/2.6.0 Nori documentation}. Nori also uses an enhanced
       #       String class with an extra method #attributes that will return a Hash containing tag-value pairs for each
       #       attribute of the XML element.
       #
@@ -252,6 +249,7 @@ module Libis
       #               <book title="Quidditch Through the Ages" author="Kennilworthy Whisp" due_date="1992-4-23"/>
       #           </books>
       #           </patron>
+      #
       # @param [Code block] block Build instructions
       # @return [XmlDocument] the new XML Document
       def self.build(&block)
@@ -333,7 +331,7 @@ module Libis
       #
       # @param [Nokogiri::XML::Node] node node to add the attributes to
       # @param [Hash] attributes a Hash with tag - value pairs for each attribute
-      # @return [{Nokogiri::XML::Node}] the node
+      # @return [Nokogiri::XML::Node] the node
       def add_attributes(node, attributes)
         XmlDocument.add_attributes node, attributes
       end
@@ -373,10 +371,6 @@ module Libis
       # @param [Hash] namespaces a Hash with prefix - URI pairs for each namespace definition that should be added. The
       #     special key +:node_ns+ is reserved for specifying the prefix for the node itself. To set the default
       #     namespace, use the prefix +nil+
-      # Example:
-      #     node = xml_doc.create_text_node 'address', 'content'
-      #     xml_doc.add_namespaces node, node_ns: 'abc', abc: 'http://abc.org', xyz: 'http://xyz.org'
-      #     # node => <abc:sample abc="http://abc.org" xyz="http://xyz.org">content</abc:sample>
       def add_namespaces(node, namespaces)
         XmlDocument.add_namespaces node, namespaces
       end
@@ -565,7 +559,7 @@ module Libis
         node
       end
 
-      # Get the first node matching the tag. The node will be seached with XPath search term = "//#{tag}".
+      # Get the first node matching the tag. The node will be seached with XPath search term = "//#!{tag}".
       #
       # @param [String] tag XML tag to look for; XPath syntax is allowed
       # @param [Node] parent
@@ -573,7 +567,7 @@ module Libis
         get_nodes(tag, parent).first
       end
 
-      # Get all the nodes matching the tag. The node will be seached with XPath search term = "//#{tag}".
+      # Get all the nodes matching the tag. The node will be seached with XPath search term = "//#!{tag}".
       #
       # @param [String] tag XML tag to look for; XPath syntax is allowed
       # @param [Node] parent