cfa 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 462483ae4713b64048bae7313e741675c32e14ce
-  data.tar.gz: 3ae2dffb60221cf96ba4e7d09d22c558dbbf7ab9
+  metadata.gz: 2a5ddfd0e34f669de02849ae3fcbc4ca3dafb664
+  data.tar.gz: b4d6d350b7a072b7168a9250454115c206630e53
 SHA512:
-  metadata.gz: 566cd667bcca679f1ce4e95105f8293f042822f9da63ad10063b2e717a6dca90dc57e20796f43332b9eadb27a4c3566ae4f412cf1203fd0bb0e3c0e92c6759d7
-  data.tar.gz: 26207c7926c12a48f003ca46366e5a3f58931852b872b01bf2620fcbb47c6546ce4534cc33f3db0af3edf7725772eac15f5f4517fbee60af34fe0b554224b2b3
+  metadata.gz: 265417fcbac259f04e42331f29918ebf4e575bc5e8f58d564af944355d12fc4dfd271bae09acb8213fa9cf6b5782189090d1e5f672d39d4b3687d025de9d43d1
+  data.tar.gz: 6862d7929f54bdf1673dd6f3721481fe7953a7a960b00ddc905254bd5dec4d608eec94ac36f388c959228e13fbe4876267eda2b5df3f661da7fb546262aca120

data/lib/cfa/augeas_parser.rb

@@ -3,6 +3,25 @@ require "forwardable"
 require "cfa/placer"
 
 module CFA
+  # A building block for {AugeasTree}.
+  #
+  # Intuitively the tree is made of hashes where keys may be duplicated,
+  # so it is implemented as a sequence of hashes with two keys, :key and :value.
+  #
+  # A `:key` is a String.
+  # The key may have a collection suffix "[]". Note that in contrast
+  # with the underlying {::Augeas} library, an integer index is not present
+  # (which should make it easier to modify collections of elements).
+  #
+  # A `:value` is either a String, or an {AugeasTree},
+  # or an {AugeasTreeValue} (which combines both).
+  #
+  # @return [Hash{Symbol => String, AugeasTree}]
+  #
+  # @todo Unify naming: entry, element
+  class AugeasElement < Hash
+  end
+
   # Represents list of same config options in augeas.
   # For example comments are often stored in collections.
   class AugeasCollection
@@ -19,6 +38,7 @@ module CFA
       element = placer.new_element(@tree)
       element[:key] = augeas_name
       element[:value] = value
+      # FIXME: load_collection missing here
     end
 
     def delete(value)
@@ -47,12 +67,12 @@ module CFA
     end
   end
 
-  # Represents node that contain value and also subtree below it
-  # For easier traversing it pass #[] to subtree
+  # Represents a node that contains both a value and a subtree below it.
+  # For easier traversal it forwards `#[]` to the subtree.
   class AugeasTreeValue
-    # value in node
+    # @return [String] the value in the node
     attr_accessor :value
-    # subtree below node
+    # @return [AugeasTree] the subtree below the node
     attr_accessor :tree
 
     def initialize(tree, value)
@@ -60,32 +80,58 @@ module CFA
       @value = value
     end
 
-    def [](value)
-      tree[value]
+    # (see AugeasTree#[])
+    def [](key)
+      tree[key]
+    end
+
+    def ==(other)
+      [:class, :value, :tree].all? do |a|
+        public_send(a) == other.public_send(a)
+      end
     end
+
+    # For objects of class Object, eql? is synonymous with ==:
+    # http://ruby-doc.org/core-2.3.3/Object.html#method-i-eql-3F
+    alias_method :eql?, :==
   end
 
-  # Represent parsed augeas config tree with user friendly methods
+  # Represents a parsed Augeas config tree with user friendly methods
   class AugeasTree
-    # low level access to augeas structure
+    # Low level access to Augeas structure
+    #
+    # An ordered mapping, represented by an Array of Hashes
+    # with the keys :key and :value.
+    #
+    # @see AugeasElement
+    #
+    # @return [Array<Hash{Symbol => String, AugeasTree}>]
     attr_reader :data
 
     def initialize
       @data = []
     end
 
+    # @return [AugeasCollection] collection for *key*
     def collection(key)
       AugeasCollection.new(self, key)
     end
 
-    def delete(key)
-      @data.reject! { |entry| entry[:key] == key }
+    # @param [String, Matcher]
+    def delete(matcher)
+      unless matcher.is_a?(CFA::Matcher)
+        matcher = CFA::Matcher.new(key: matcher)
+      end
+      @data.reject!(&matcher)
     end
 
-    # adds the given value for the key in tree.
-    # @param value can be value of node, {AugeasTree}
-    #   attached to key or its combination as {AugeasTreeValue}
-    # @param placer object determining where to insert value in tree.
+    # Adds the given *value* for *key* in the tree.
+    #
+    # By default an AppendPlacer is used which produces duplicate keys
+    # but ReplacePlacer can be used to replace the *first* duplicate.
+    # @param key [String]
+    # @param value [String,AugeasTree,AugeasTreeValue]
+    # @param placer [Placer] determines where to insert value in tree.
     #   Useful e.g. to specify order of keys or placing comment above of given
     #   key.
     def add(key, value, placer = AppendPlacer.new)
@@ -94,10 +140,10 @@ module CFA
       element[:value] = value
     end
 
-    # finds given value in tree.
-    # @return It can return value of node, {AugeasTree}
-    #   attached to key or its combination as {AugeasTreeValue}.
-    #   Also nil can be returned if key not found.
+    # Finds given *key* in tree.
+    # @param key [String]
+    # @return [String,AugeasTree,AugeasTreeValue,nil] the first value for *key*,
+    #   or `nil` if not found
     def [](key)
       entry = @data.find { |d| d[:key] == key }
       return entry[:value] if entry
@@ -105,8 +151,10 @@ module CFA
       nil
     end
 
-    # Sets the given value for the key in tree. It can be value of node,
-    # {AugeasTree} attached to key or its combination as {AugeasTreeValue}
+    # Replace the first value for *key* with *value*.
+    # Append a new element if *key* did not exist.
+    # @param key [String]
+    # @param value [String, AugeasTree, AugeasTreeValue]
     def []=(key, value)
       entry = @data.find { |d| d[:key] == key }
       if entry
@@ -119,12 +167,20 @@ module CFA
       end
     end
 
+    # @param matcher [Matcher]
+    # @return [Array<AugeasElement>] matching elements
     def select(matcher)
       @data.select(&matcher)
     end
 
     # @note for internal usage only
-    # @private
+    # @api private
+    #
+    # Initializes {#data} from *prefix* in *aug*.
+    # @param aug [::Augeas]
+    # @param prefix [String] Augeas path prefix
+    # @param keys_cache [AugeasKeysCache]
+    # @return [void]
     def load_from_augeas(aug, prefix, keys_cache)
       @data = keys_cache.keys_for_prefix(prefix).map do |key|
         aug_key = prefix + "/" + key
@@ -136,7 +192,12 @@ module CFA
     end
 
     # @note for internal usage only
-    # @private
+    # @api private
+    #
+    # Saves {#data} to *prefix* in *aug*.
+    # @param aug [::Augeas]
+    # @param prefix [String] Augeas path prefix
+    # @return [void]
     def save_to_augeas(aug, prefix)
       arrays = {}
 
@@ -145,6 +206,14 @@ module CFA
       end
     end
 
+    def ==(other)
+      [:class, :data].all? { |a| public_send(a) == other.public_send(a) }
+    end
+
+    # For objects of class Object, eql? is synonymous with ==:
+    # http://ruby-doc.org/core-2.3.3/Object.html#method-i-eql-3F
+    alias_method :eql?, :==
+
   private
 
     def save_entry(key, value, arrays, aug, prefix)
@@ -199,20 +268,22 @@ module CFA
   end
 
   # @example read, print, modify and serialize again
-  #    require "config_files/augeas_parser"
+  #    require "cfa/augeas_parser"
   #
-  #    parser = CFA::AugeasParser.new("sysconfig.lns")
+  #    parser = CFA::AugeasParser.new("Sysconfig.lns")
   #    data = parser.parse(File.read("/etc/default/grub"))
   #
   #    puts data["GRUB_DISABLE_OS_PROBER"]
   #    data["GRUB_DISABLE_OS_PROBER"] = "true"
   #    puts parser.serialize(data)
   class AugeasParser
+    # @param lens [String] a lens name, like "Sysconfig.lns"
     def initialize(lens)
       @lens = lens
     end
 
-    # parses given string and returns AugeasTree instance
+    # @param raw_string [String] a string to be parsed
+    # @return [AugeasTree] the parsed data
     def parse(raw_string)
       @old_content = raw_string
 
@@ -232,7 +303,8 @@ module CFA
       end
     end
 
-    # Serializes AugeasTree instance into returned string
+    # @param data [AugeasTree] the data to be serialized
+    # @return [String] a string to be written
     def serialize(data)
       # open augeas without any autoloading and it should not touch disk and
       # load lenses as needed only
@@ -248,13 +320,15 @@ module CFA
       end
     end
 
-    # Returns empty tree that can be filled for future serialization
+    # @return [AugeasTree] an empty tree that can be filled
+    #   for future serialization
     def empty
       AugeasTree.new
     end
 
   private
 
+    # @param aug [::Augeas]
     def report_error(aug)
       error = aug.error
       # zero is no error, so problem in lense
@@ -267,53 +341,44 @@ module CFA
       raise "Augeas parsing/serializing error: #{msg} at #{location}"
     end
   end
-end
 
-# Cache that holds all avaiable keys in augeas tree. It is used to
-# prevent too many aug.match calls which are expensive.
-class AugeasKeysCache
-  STORE_PREFIX = "/store".freeze
-  STORE_LEN = STORE_PREFIX.size
-  STORE_LEN_1 = STORE_LEN + 1
+  # Cache that holds all avaiable keys in augeas tree. It is used to
+  # prevent too many aug.match calls which are expensive.
+  class AugeasKeysCache
+    STORE_PREFIX = "/store".freeze
 
-  # initialize cache from passed augeas object
-  def initialize(aug)
-    fill_cache(aug)
-  end
-
-  # returns list of keys available on given prefix
-  def keys_for_prefix(prefix)
-    cut = prefix.length > STORE_LEN ? STORE_LEN_1 : STORE_LEN
-    path = prefix[cut..-1]
-    path = path.split("/")
-    matches = path.reduce(@cache) { |a, e| a[e] }
+    # initialize cache from passed augeas object
+    def initialize(aug)
+      fill_cache(aug)
+    end
 
-    matches.keys
-  end
+    # returns list of keys available on given prefix
+    def keys_for_prefix(prefix)
+      @cache[prefix] || []
+    end
 
-private
+  private
 
-  def fill_cache(aug)
-    @cache = {}
-    search_path = "#{STORE_PREFIX}/*"
-    loop do
-      matches = aug.match(search_path)
-      break if matches.empty?
-      assign_matches(matches, @cache)
+    def fill_cache(aug)
+      @cache = {}
+      search_path = "#{STORE_PREFIX}/*"
+      loop do
+        matches = aug.match(search_path)
+        break if matches.empty?
+        assign_matches(matches, @cache)
 
-      search_path += "/*"
+        search_path += "/*"
+      end
     end
-  end
 
-  def assign_matches(matches, cache)
-    matches.each do |match|
-      path = match[STORE_LEN_1..-1].split("/")
-      leap = path.pop
-      target = path.reduce(cache) do |acc, p|
-        acc[p]
+    def assign_matches(matches, cache)
+      matches.each do |match|
+        split_index = match.rindex("/")
+        prefix = match[0..(split_index - 1)]
+        key = match[(split_index + 1)..-1]
+        cache[prefix] ||= []
+        cache[prefix] << key
       end
-
-      target[leap] = {}
     end
   end
 end

data/lib/cfa/base_model.rb

@@ -22,11 +22,28 @@ module CFA
       self.data = parser.empty
     end
 
+    # Serializes *data* using *parser*
+    # and writes the resulting String using *file_handler*.
+    # @return [void]
+    # @raise a *file_handler* specific error if *file_path* cannot be written
+    #   e.g. due to missing permissions or living on a read only device.
+    # @raise a *parser* specific error. If *data* contain invalid values
+    #   then *parser* may raise an error.
+    #   A properly written BaseModel subclass should prevent that by preventing
+    #   insertion of such values in the first place.
     def save(changes_only: false)
       merge_changes if changes_only
       @file_handler.write(@file_path, @parser.serialize(data))
     end
 
+    # Reads a String using *file_handler*
+    # and parses it with *parser*, storing the result in *data*.
+    # @return [void]
+    # @raise a *file_handler* specific error. If *file_path* does not exist
+    #   or permission is not sufficient it may raise an error
+    #   depending on the used file handler.
+    # @raise a *parser* specific error. If the parsed String is malformed, then
+    #   depending on the used parser it may raise an error.
     def load
       self.data = @parser.parse(@file_handler.read(@file_path))
       @loaded = true
@@ -65,21 +82,31 @@ module CFA
       @default_file_handler = value
     end
 
-  protected
-
-    # generates accessors for trivial key-value attributes
+    # Generates accessors for trivial key-value attributes
+    # @param attrs [Hash{Symbol => String}] mapping of methods to file keys
+    #
+    # @example Usage
+    #   class FooModel < CFA::BaseModel
+    #     attributes(
+    #       server:        "server",
+    #       read_timeout:  "ReadTimeout",
+    #       write_timeout: "WriteTimeout"
+    #     )
+    #     ...
+    #   end
     def self.attributes(attrs)
-      attrs.each_pair do |key, value|
-        define_method(key) do
-          generic_get(value)
+      attrs.each_pair do |method_name, key|
+        define_method(method_name) do
+          generic_get(key)
         end
 
-        define_method(:"#{key.to_s}=") do |target|
-          generic_set(value, target)
+        define_method(:"#{method_name.to_s}=") do |value|
+          generic_set(key, value)
         end
       end
     end
-    private_class_method :attributes
+
+  protected
 
     attr_accessor :data
 
@@ -90,6 +117,9 @@ module CFA
       data.merge(new_data)
     end
 
+    # Modify an **existing** entry and return `true`,
+    # or do nothing and return `false`.
+    # @return [Boolean]
     def modify(key, value)
       # if already set, just change value
       return false unless data[key]
@@ -98,14 +128,20 @@ module CFA
       true
     end
 
+    # Replace a commented out entry and return `true`,
+    # or do nothing and return `false`.
+    # @return [Boolean]
     def uncomment(key, value)
       # Try to find if it is commented out, so we can replace line
       matcher = Matcher.new(
         collection:    "#comment",
+        # FIXME: this assumes a specific "=" syntax, bypassing the lens
+        # FIXME: this will match also "# If you set FOO=bar then..."
         value_matcher: /(\s|^)#{key}\s*=/
       )
       return false unless  data.data.any?(&matcher)
 
+      # FIXME: this assumes that *data* is an AugeasTree
       data.add(key, value, ReplacePlacer.new(matcher))
       true
     end

data/lib/cfa/matcher.rb

@@ -1,9 +1,42 @@
 module CFA
-  # Class used to create matcher, that allows to find specific option in augeas
-  # tree or subtree
-  # TODO: examples of usage
+  # The Matcher is used as a predicate on {AugeasElement}.
+  #
+  # Being a predicate, it is passed  to methods such as Enumerable#select
+  # or Array#index, returning a Boolean meaning whether a match was found.
+  #
+  # Acting on {AugeasElement} means it expects a Hash `e`
+  # containing `e[:key]` and `e[:value]`.
+  #
+  # It is used with the `&` syntax which makes the matcher
+  # act like a block/lambda/Proc (via {Matcher#to_proc}).
+  #
+  # @note The coupling to {AugeasTree}, {AugeasElement} is not a goal.
+  #   Once we have more parsers it will go away.
+  #
+  # @example
+  #    elements = [
+  #                {key: "#comment[]", value: "\"magical\" mostly works"},
+  #                {key: "DRIVE",      value: "magical"},
+  #                {key: "#comment[]", value: "'years' or 'centuries'"},
+  #                {key: "PRECISION",  value: "years"}
+  #               ]
+  #    drive_matcher = Matcher.new(key: "DRIVE")
+  #    i = elements.index(&drive_matcher)        # => 1
   class Matcher
-    # @block_yield matcher based on block. block gets two params, key and value
+    # The constructor arguments are constraints to match on an element.
+    # All constraints are optional.
+    # All supplied constraints must match, so it is a conjunction.
+    # @param key           [Object,nil] if non-nil,
+    #   constrain to elements with the name "*key*"
+    # @param collection    [Object,nil] if non-nil,
+    #   constrain to elements with the name "*collection*[]"
+    # @param value_matcher [Object,Regexp,nil] if non-nil,
+    #   constrain to elements whose value is Object or matches Regexp
+    # @yieldparam blk_key   [Object]
+    # @yieldparam blk_value [Object]
+    # @yieldreturn      [Boolean] if the block is present,
+    #   constrain to elements for which the block(*blk_key*, *blk_value*)
+    #   returns true
     def initialize(key: nil, collection: nil, value_matcher: nil, &block)
       @matcher = lambda do |element|
         return false unless key_match?(element, key)
@@ -14,10 +47,13 @@ module CFA
       end
     end
 
+    # @return [Proc{AugeasElement=>Boolean}]
     def to_proc
       @matcher
     end
 
+  private
+
     def key_match?(element, key)
       return true unless key
 

data/lib/cfa/placer.rb

@@ -1,6 +1,21 @@
 module CFA
-  # allows to place element at the end of configuration. Default one.
-  class AppendPlacer
+  # Places a new {AugeasElement} into an {AugeasTree}.
+  # @abstract Subclasses implement different ways **where**
+  #   to place the entry by overriding {#new_element}.
+  class Placer
+    # @param  [AugeasTree] tree
+    # @return [AugeasElement,Hash] the new element; it is empty!
+    #   Note that the return value is actually a Hash; {AugeasElement}
+    #   documents its structure.
+    def new_element(_tree)
+      raise NotImplementedError,
+        "Subclasses of #{Module.nesting.first} must override #{__method__}"
+    end
+  end
+
+  # Places the new element at the end of the tree.
+  class AppendPlacer < Placer
+    # (see Placer#new_element)
     def new_element(tree)
       res = {}
       tree.data << res
@@ -9,14 +24,18 @@ module CFA
     end
   end
 
-  # Specialized placer, that allows to place config value before found one.
-  # If noone is found, then append to the end
-  # Useful, when config option should be inserted to specific location.
-  class BeforePlacer
+  # Finds a specific element using a {Matcher} and places the new element
+  # **before** it. Appends at the end if a match is not found.
+  #
+  # Useful when a config option should be inserted to a specific location,
+  # or when assigning a comment to an option.
+  class BeforePlacer < Placer
+    # @param [Matcher] matcher
     def initialize(matcher)
       @matcher = matcher
     end
 
+    # (see Placer#new_element)
     def new_element(tree)
       index = tree.data.index(&@matcher)
 
@@ -30,14 +49,17 @@ module CFA
     end
   end
 
-  # Specialized placer, that allows to place config value after found one.
-  # If noone is found, then append to the end
-  # Useful, when config option should be inserted to specific location.
-  class AfterPlacer
+  # Finds a specific element using a {Matcher} and places the new element
+  # **after** it.  Appends at the end if a match is not found.
+  #
+  # Useful when a config option should be inserted to a specific location.
+  class AfterPlacer < Placer
+    # @param [Matcher] matcher
     def initialize(matcher)
       @matcher = matcher
     end
 
+    # (see Placer#new_element)
     def new_element(tree)
       index = tree.data.index(&@matcher)
 
@@ -51,15 +73,18 @@ module CFA
     end
   end
 
-  # Specialized placer, that allows to place config value instead of found one.
-  # If noone is found, then append to the end
-  # Useful, when value already exists and detected by matcher. Then easy add
-  # with this placer replace it carefully to correct location.
-  class ReplacePlacer
+  # Finds a specific element using a {Matcher} and **replaces** it
+  # with the new element.  Appends at the end if a match is not found.
+  #
+  # Useful in key-value configuration files where a specific key
+  # needs to be assigned.
+  class ReplacePlacer < Placer
+    # @param [Matcher] matcher
     def initialize(matcher)
       @matcher = matcher
     end
 
+    # (see Placer#new_element)
     def new_element(tree)
       index = tree.data.index(&@matcher)
       res = {}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cfa
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Josef Reidinger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-10-12 00:00:00.000000000 Z
+date: 2016-11-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-augeas