file_permissions 0.1.0

data/lib/god_object/file_permissions/helper_mixin.rb

@@ -0,0 +1,48 @@
+# encoding: UTF-8
+=begin
+Copyright GodObject Team <dev@godobject.net>, 2012-2016
+
+This file is part of FilePermissions.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+=end
+
+module GodObject
+  module FilePermissions
+
+    # Mixin containing helper methods
+    #
+    # @private
+    module HelperMixin
+
+      # @return [Array<Symbol>] possible output String formats
+      STRING_FORMAT = Set[:long, :short].freeze
+
+      protected
+
+      # Ensures that input is Pathname
+      #
+      # @param [Pathname, String] path a path
+      # @param [:forbid_nil, :allow_nil] nil_handling if set to :allow_nil,
+      #   a nil path will be passed-through. Raises an exception otherwise
+      # @return [Pathname] the path as Pathname object
+      def to_pathname(path, nil_handling = :forbid_nil)
+        return nil if path.nil? if nil_handling == :allow_nil
+
+        path.is_a?(Pathname) ? path : Pathname.new(path)
+      end
+
+    end
+
+  end
+end

data/lib/god_object/file_permissions/mode.rb

@@ -0,0 +1,156 @@
+# encoding: UTF-8
+=begin
+Copyright GodObject Team <dev@godobject.net>, 2012-2016
+
+This file is part of FilePermissions.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+=end
+
+module GodObject
+  module FilePermissions
+
+    # Represents one component of the normal file mode in POSIX environments.
+    #
+    # The Mode is basically an immutable bit set consisting of the digits
+    # :read, :write and :execute.
+    class Mode
+      include BitSet
+
+      octal_mode = /(?<octal_mode>[0-7])/
+      digit_mode = /(?<digit_mode>(?:-|r|w|x){1,3})/
+      blank      = /\p{Blank}*?/
+
+      # Regular expression for parsing a Mode from a String representation.
+      PATTERN = /^#{blank}(?:#{digit_mode}|#{octal_mode})#{blank}$/
+
+      # Configuration for the GodObject:::BitSet object which is used to handle
+      # the state internally.
+      BIT_SET_CONFIGURATION = Configuration.new(
+        read:    'r',
+        write:   'w',
+        execute: 'x'
+      )
+
+      extend Forwardable
+      include ModeMixin
+      include Comparable
+
+      class << self
+        # @!parse include ModeMixin::ClassMethods
+
+        # Creates a new Mode object by parsing a String representation.
+        #
+        # @param [String] string a String containing a mode
+        # @return [GodObject::FilePermissions::Mode] a new Mode object
+        def parse(string)
+          result = string.match(PATTERN)
+          
+          case 
+          when !result
+            raise ParserError, 'Invalid format'
+          when result[:octal_mode] 
+            new(result[:octal_mode].to_i)
+          else
+            mode_components = []
+
+            result[:digit_mode].scan(/r|w|x/).each do |digit|
+              mode_components << :read    if digit == 'r'
+              mode_components << :write   if digit == 'w'
+              mode_components << :execute if digit == 'x'
+            end
+            
+            if mode_components.uniq!
+              raise ParserError,
+                "Duplicate digit in: #{string.inspect}"
+            end
+
+            new(mode_components)
+          end
+        end
+      end
+
+      # Initializes a new Mode
+      #
+      # @return [void]
+      #
+      # @overload initialize(numeric)
+      #   @param [Integer] numeric a numeric representation
+      #
+      # @overload initialize(enabled_digits)
+      #   @param [Array<:read, :write, :execute>] enabled_digits a list of
+      #     enabled digits
+      def initialize(*mode_components)
+        @bit_set = BIT_SET_CONFIGURATION.new(*mode_components)
+      end
+
+      # @!method enabled_digits
+      #   @!attribute [r] enabled_digits
+      #   @return [Set<:read, :write, :execute>] a list of all digits which are
+      #     enabled
+      #
+      # @!method disabled_digits
+      #   @!attribute [r] disabled_digits
+      #   @return [Set<:read, :write, :execute>] a list of all digits which are
+      #     disabled
+      #
+      # @!method state
+      #   @!attribute [r] state
+      #   @return [{(:read, :write, :execute) => true, false}] a table of all
+      #     digits and their states
+      #
+      # @!parse alias attributes state
+      #
+      # @!method read?
+      #   @!attribute [r] read?
+      #   @return [true, false] the current state of the read digit
+      #
+      # @!parse alias read read?
+      #
+      # @!method write?
+      #   @!attribute [r] write?
+      #   @return [true, false] the current state of the write digit
+      #
+      # @!parse alias write write?
+      #
+      # @!method execute?
+      #   @!attribute [r] execute?
+      #   @return [true, false] the current state of the execute digit
+      #
+      # @!parse alias execute execute?
+      #
+      # @!method [](digit)
+      #   @param [:read, :write, :execute, Integer] digit name or index of a
+      #     digit
+      #   @return [true, false] current state of the given digit
+      #
+      # @!method to_i
+      #   Represents a Mode as a binary Integer.
+      #   @return [Integer] an Integer representation
+      #
+      # @!method to_s(format)
+      #   Represents a Mode as String.
+      #   @param [:long, :short] format the String format
+      #   @return [String] a String representation
+      #
+      # @!method hash
+      #   @return (see Object#hash) identity hash for hash table usage
+      def_delegators :@bit_set,
+        :attributes, :state, :[], :enabled_digits, :disabled_digits,
+        :read?, :read, :write?, :write, :execute?, :execute,
+        :to_i, :to_s, :hash
+
+    end
+
+  end
+end

data/lib/god_object/file_permissions/mode_mixin.rb

@@ -0,0 +1,163 @@
+# encoding: UTF-8
+=begin
+Copyright GodObject Team <dev@godobject.net>, 2012-2016
+
+This file is part of FilePermissions.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+=end
+
+module GodObject
+  module FilePermissions
+
+    # Common functionality of both Mode and SpecialMode
+    module ModeMixin
+
+      # Hook for automatic inclusion of the ClassMethods mixin
+      # @private
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      # Class mixin for Mode and SpecialMode
+      module ClassMethods
+
+        # Either passes through or generates a new Mode object
+        #
+        # @return [GodObject::FilePermissions::ModeMixin]
+        #
+        # @overload build(mode)
+        #   @param [GodObject::FilePermissions::ModeMixin] mode an already
+        #     existing Mode
+        #
+        # @overload build(string)
+        #   @param [String] string a String representation
+        #
+        # @overload build(numeric)
+        #   @param [Integer] numeric a numeric representation
+        #
+        # @overload build(enabled_digits)
+        #   @param [Array<Symbol>] enabled_digits a list of enabled digits
+        def build(mode)
+          case
+          when mode.kind_of?(self)
+            mode
+          when mode.respond_to?(:to_str)
+            parse(mode)
+          else
+            new(mode)
+          end
+        end
+
+      end
+
+      # @return [GodObject::FilePermissions::ModeMixin] a new Mode with all
+      #   digit states inverted
+      def invert
+        self.class.new(disabled_digits)
+      end
+
+      # @param [GodObject::FilePermissions::ModeMixin, Array<Symbol>] other
+      #   another Mode
+      # @return [GodObject::FilePermissions::ModeMixin] a new Mode with the
+      #   enabled digits of the current and other
+      def +(other)
+        other = other.enabled_digits if other.respond_to?(:enabled_digits)
+
+        self.class.new(enabled_digits + other)
+      end
+
+      # @param [GodObject::FilePermissions::ModeMixin, Integer] other another
+      #   Mode
+      # @return [GodObject::FilePermissions::ModeMixin] a new Mode with the
+      #   enabled digits of the current and other
+      def union(other)
+        other = other.to_i if other.respond_to?(:to_i)
+
+        self.class.new(to_i | other)
+      end
+
+      alias | union
+
+      # @param [GodObject::FilePermissions::ModeMixin, Array<Symbol>] other
+      #   another Mode
+      # @return [GodObject::FilePermissions::ModeMixin] a new Mode with the
+      #   enabled digits of the current without the enabled digits of other
+      def difference(other)
+        other = other.enabled_digits if other.respond_to?(:enabled_digits)
+
+        self.class.new(enabled_digits - other)
+      end
+
+      alias - difference
+
+      # @param [GodObject::FilePermissions::ModeMixin, Integer] other another
+      #   Mode
+      # @return [GodObject::FilePermissions::ModeMixin] a new Mode with only
+      #   those digits enabled which are enabled in both the current and other
+      def intersection(other)
+        other = other.to_i if other.respond_to?(:to_i)
+
+        self.class.new(to_i & other)
+      end
+
+      alias & intersection
+
+      # @param [GodObject::FilePermissions::ModeMixin, Integer] other another
+      #   Mode
+      # @return [GodObject::FilePermissions::ModeMixin] a new Mode with the
+      #   enabled digits which are enabled in only one of current and other
+      def symmetric_difference(other)
+        other = other.to_i if other.respond_to?(:to_i)
+
+        self.class.new(to_i ^ other)
+      end
+
+      alias ^ symmetric_difference
+
+      # Compares the Mode to another to determine its relative position.
+      #
+      # Relative position is defined by comparing the Integer representation.
+      #
+      # @note Only other Modes or Integer-likes are considered comparable.
+      #
+      # @param [Object] other other Object to be compared
+      #   object
+      # @return [-1, 0, 1, nil] -1 if other is greater, 0 if other is equal and
+      #   1 if other is lesser than self, nil if comparison is impossible
+      def <=>(other)
+        to_i <=> other.to_i
+      rescue NoMethodError
+        nil
+      end
+
+      # Answers if another object is equal and of the same type family.
+      #
+      # @see GodObject::FilePermissions::ModeMixin#<=>
+      # @param [Object] other an object to be checked for equality
+      # @return [true, false] true if the object is considered equal and of the
+      #   same type family, false otherwise
+      def eql?(other)
+        self == other && other.kind_of?(self.class)
+      end
+
+      # Represents a Mode as String for debugging.
+      #
+      # @return [String] a String representation for debugging
+      def inspect
+        "#<#{self.class}: #{to_s.inspect}>"
+      end
+    end
+
+  end
+end

data/lib/god_object/file_permissions/special_mode.rb

@@ -0,0 +1,149 @@
+# encoding: UTF-8
+=begin
+Copyright GodObject Team <dev@godobject.net>, 2012-2016
+
+This file is part of FilePermissions.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+=end
+
+module GodObject
+  module FilePermissions
+
+    # Represents one component of the normal file mode in POSIX environments.
+    #
+    # The SpecialMode is basically an immutable bit set consisting of the
+    # digits :setuid, :setgid and :sticky.
+    class SpecialMode
+      include BitSet
+
+      octal_mode = /(?<octal_mode>[0-7])/
+      digit_mode = /(?<digit_mode>(?:-|s){2}(?:-|t))/
+      blank      = /\p{Blank}*?/
+
+      # Regular expression for parsing a SpecialMode from a String
+      # representation.
+      PATTERN = /^#{blank}(?:#{digit_mode}|#{octal_mode})#{blank}$/
+
+      # Configuration for the GodObject:::BitSet object which is used to handle
+      # the state internally.
+      BIT_SET_CONFIGURATION = Configuration.new(
+        setuid: 's',
+        setgid: 's',
+        sticky: 't'
+      )
+
+      extend Forwardable
+      include ModeMixin
+      include Comparable
+
+      class << self
+        # @!parse include ModeMixin::ClassMethods
+
+        # Creates a new SpecialMode object by parsing a String representation.
+        #
+        # @param [String] string a String containing a mode
+        # @return [GodObject::FilePermissions::SpecialMode] a new SpecialMode
+        #   object
+        def parse(string)
+          result = string.match(PATTERN)
+
+          case
+          when !result
+            raise ParserError, 'Invalid format'
+          when result[:octal_mode]
+            new(result[:octal_mode].to_i)
+          else
+            mode_components = []
+
+            mode_components << :setuid if result[:digit_mode][0] == 's'
+            mode_components << :setgid if result[:digit_mode][1] == 's'
+            mode_components << :sticky if result[:digit_mode][2] == 't'
+
+            new(mode_components)
+          end
+        end
+      end
+
+      # Initializes a new SpecialMode
+      #
+      # @return [void]
+      #
+      # @overload initialize(numeric)
+      #   @param [Integer] numeric a numeric representation
+      #
+      # @overload initialize(enabled_digits)
+      #   @param [Array<:setuid, :setgid, :sticky>] enabled_digits a list of
+      #     enabled digits
+      def initialize(*mode_components)
+        @bit_set = BIT_SET_CONFIGURATION.new(*mode_components)
+      end
+
+      # @!method enabled_digits
+      #   @!attribute [r] enabled_digits
+      #   @return [Set<:setuid, :setgid, :sticky>] a list of all digits which
+      #     are enabled
+      #
+      # @!method disabled_digits
+      #   @!attribute [r] disabled_digits
+      #   @return [Set<:setuid, :setgid, :sticky>] a list of all digits which
+      #     are disabled
+      #
+      # @!method state
+      #   @!attribute [r] state
+      #   @return [{(:read, :write, :execute) => true, false}] a table of all
+      #     digits and their states
+      #
+      # @!method setuid?
+      #   @!attribute [r] setuid?
+      #   @return [true, false] the current state of the setuid digit
+      #
+      # @!parse alias setuid setuid?
+      #
+      # @!method setgid?
+      #   @!attribute [r] setgid?
+      #   @return [true, false] the current state of the setgid digit
+      #
+      # @!parse alias setgid setgid?
+      #
+      # @!method sticky?
+      #   @attribute [r] sticky?
+      #   @return [true, false] the current state of the sticky digit
+      #
+      # @!parse alias sticky sticky?
+      #
+      # @!method [](digit)
+      #   @param [:setuid, :setgid, :sticky, Integer] digit name or index of a
+      #     digit
+      #   @return [true, false] current state of the given digit
+      #
+      # @!method to_i
+      #   Represents a SpecialMode as a binary Integer.
+      #   @return [Integer] an Integer representation
+      #
+      # @!method to_s(format)
+      #   Represents a SpecialMode as String.
+      #   @param [:long, :short] format the String format
+      #   @return [String] a String representation
+      #
+      # @!method hash
+      #   @return (see Object#hash) identity hash for hash table usage
+      def_delegators :@bit_set,
+        :attributes, :state, :[], :enabled_digits, :disabled_digits,
+        :setuid?, :setuid, :setgid?, :setgid, :sticky?, :sticky,
+        :to_i, :to_s, :hash
+
+    end
+
+  end
+end