file_permissions 0.1.0

data/Rakefile

@@ -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
+
+require 'bundler/gem_tasks'
+require 'rake'
+require 'pathname'
+require 'yard'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new
+
+YARD::Rake::YardocTask.new('doc')
+
+desc "Removes temporary project files"
+task :clean do
+  %w{doc/api coverage pkg .yardoc .rbx Gemfile.lock}.map{|name| Pathname.new(name) }.each do |path|
+    path.rmtree if path.exist?
+  end
+
+  Pathname.glob('*.gem').each &:delete
+  Pathname.glob('**/*.rbc').each &:delete
+end
+
+desc "Opens an interactive console with the project code loaded"
+task :console do
+  Bundler.setup
+  require 'pry'
+  require 'file_permissions'
+  Pry.start(GodObject::FilePermissions)
+end
+
+task default: :spec

data/file_permissions.gemspec

@@ -0,0 +1,67 @@
+# 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
+
+require File.expand_path('../lib/god_object/file_permissions/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name    = "file_permissions"
+  gem.version = GodObject::FilePermissions::VERSION.dup
+  gem.authors = ["Oliver Feldt", "Alexander E. Fischer", "Axel Sorge", "Andreas Wurm"]
+  gem.email   = ["of@godobject.net", "aef@godobject.net", "as@godobject.net", "aw@godobject.net"]
+  gem.description = <<-DESCRIPTION
+FilePermissions is a Ruby library providing an object representation of the
+file permission bits in POSIX systems.
+
+It can handle the generic read, write and execute permissions, as well as
+the setuid, setgid and sticky flags. Permission sets can be read from file
+system objects, parsed from typical string representations or simply
+defined by their numeric representation. They can then be manipulated
+through binary logic operators and written back to file system objects.
+  DESCRIPTION
+  gem.summary  = "Representation and manipulation of POSIX system file permissions in Ruby."
+  gem.homepage = "https://www.godobject.net/"
+  gem.license  = "ISC"
+  gem.has_rdoc = "yard"
+  gem.extra_rdoc_files  = ["HISTORY.md", "LICENSE.md"]
+  gem.rubyforge_project = nil
+
+  `git ls-files 2> /dev/null`
+
+  if $?.success?
+    gem.files         = `git ls-files`.split($\)
+  else
+    gem.files         = `ls -1`.split($\)
+  end
+
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.required_ruby_version = '>= 1.9.3'
+
+  gem.add_dependency('bit_set')
+
+  gem.add_development_dependency('rake')
+  gem.add_development_dependency('bundler')
+  gem.add_development_dependency('rspec')
+  gem.add_development_dependency('simplecov')
+  gem.add_development_dependency('pry')
+  gem.add_development_dependency('yard')
+  gem.add_development_dependency('kramdown')
+end

data/lib/file_permissions.rb

@@ -0,0 +1,22 @@
+# 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
+
+# Helper file to allow loading by gem name.
+
+require 'god_object/file_permissions'

data/lib/god_object/file_permissions.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
+
+require 'set'
+require 'forwardable'
+require 'bit_set'
+
+# Namespace for projects of the GodObject team <dev@godobject.net>.
+#
+# If you want to be able to simply type Example instead of GodObject::Example
+# to address classes in this namespace simply write the following before using
+# the classes.
+#
+# @example Including the namespace
+#   include GodObject
+# @see https://www.godobject.net/
+module GodObject
+
+  # Namespace for components of the "file_permissions" library
+  module FilePermissions
+
+  end
+
+end
+
+require 'god_object/file_permissions/helper_mixin'
+require 'god_object/file_permissions/version'
+require 'god_object/file_permissions/exceptions'
+require 'god_object/file_permissions/mode_mixin'
+require 'god_object/file_permissions/mode'
+require 'god_object/file_permissions/special_mode'
+require 'god_object/file_permissions/complex_mode'

data/lib/god_object/file_permissions/complex_mode.rb

@@ -0,0 +1,259 @@
+# 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
+
+    # An aggregate of Mode and SpecialMode to represent normal file
+    # permissions in a POSIX environment.
+    class ComplexMode
+
+      # @return [GodObject::FilePermissions::Mode] permissions for the owner
+      attr_accessor :user
+
+      # @return [GodObject::FilePermissions::Mode] permissions for the owning
+      #   group
+      attr_accessor :group
+
+      # @return [GodObject::FilePermissions::Mode] permissions for everyone
+      #   else
+      attr_accessor :other
+
+      # @return [GodObject::FilePermissions::SpecialMode] special file flags
+      attr_accessor :special
+
+      extend Forwardable
+      include HelperMixin
+
+      class << self
+        include HelperMixin
+
+        # @overload build(complex_mode)
+        #   Returns an existing instance of
+        #     GodObject::FilePermissions::ComplexMode
+        #   @param [GodObject::FilePermissions::ComplexMode] complex_mode an
+        #     already existing ComplexMode
+        #   @return [GodObject::FilePermissions::ComplexMode] the same
+        #     ComplexMode object
+        #
+        # @overload build(numeric)
+        #   Returns a new ComplexMode object with the given numeric
+        #   representation.
+        #   @param [Integer] numeric a numeric representation
+        #   @return [GodObject::FilePermissions::ComplexMode] a new ComplexMode
+        #     object
+        #
+        # @overload build(enabled_digits)
+        #   Returns a new ComplexMode object with the given enabled digits
+        #   @param [Array<:user_read, :user_write, :user_execute,
+        #     :group_read, :group_write, :group_execute, :other_read,
+        #     :other_write, :other_execute, :setuid, :setgid, :sticky>]
+        #     enabled_digits a list of enabled digits
+        #   @return [GodObject::FilePermissions::ComplexMode] a new ComplexMode
+        #     object
+        def build(mode)
+          if mode.kind_of?(self)
+            mode
+          else
+            new(mode)
+          end
+        end
+
+        # Creates a new complex mode from filesystem object given by path.
+        #
+        # @param [Pathname, String] path path of the source filesystem object
+        # @param [:resolve_symlinks, :target_symlinks] symlink_handling if set
+        #   to :target_symlinks and the target is a symlink, the symlink will
+        #   not be resolved but is itself used as source. By default, the
+        #   symlink will be resolved
+        def from_file(path, symlink_handling = :resolve_symlinks)
+          file = to_pathname(path)
+
+          case symlink_handling
+          when :resolve_symlinks
+            new(file.stat.mode)
+          when :target_symlinks
+            new(file.lstat.mode)
+          else
+            raise ArgumentError, "Invalid symlink handling: #{symlink_handling.inspect}"
+          end
+        end
+      end
+
+      # @overload initialize(numeric)
+      #   Returns a new ComplexMode object with the given numeric
+      #   representation.
+      #   @param [Integer] numeric a numeric representation
+      #   @return [GodObject::FilePermissions::ComplexMode] a new ComplexMode
+      #     object
+      #
+      # @overload initialize(enabled_digits)
+      #   Returns a new ComplexMode object with the given enabled digits
+      #   @param [Array<:user_read, :user_write, :user_execute, :group_read,
+      #     :group_write, :group_execute, :other_read, :other_write,
+      #     :other_execute, :setuid, :setgid, :sticky>] enabled_digits a list
+      #     of enabled digits
+      #   @return [GodObject::FilePermissions::ComplexMode] a new ComplexMode
+      #     object
+      def initialize(*mode_components)
+        sub_mode_components = Hash.new{|hash, key| hash[key] = Set.new }
+
+        if mode_components.size == 1 && mode_components.first.respond_to?(:to_int)
+          integer = mode_components.first
+
+          [:other, :group, :user, :special].each do |mode|
+            sub_mode_components[mode] = integer & 0b111
+            integer = integer >> 3 unless mode == :special
+          end
+        else
+          if mode_components.size == 1 && mode_components.first.is_a?(Enumerable)
+            mode_components = mode_components.first
+          end
+
+          mode_components.flatten.each do |digit|
+            case digit
+            when /^user_(.*)$/
+              sub_mode_components[:user] << $1.to_sym
+            when /^group_(.*)$/
+              sub_mode_components[:group] << $1.to_sym
+            when /^other_(.*)$/
+              sub_mode_components[:other] << $1.to_sym
+            else
+              sub_mode_components[:special] << digit
+            end
+          end
+        end
+
+        @user    = Mode.new(sub_mode_components[:user])
+        @group   = Mode.new(sub_mode_components[:group])
+        @other   = Mode.new(sub_mode_components[:other])
+        @special = SpecialMode.new(sub_mode_components[:special])
+      end
+
+      # Assigns the mode to a filesystem object given by path.
+      #
+      # @param [Pathname, String] path path of the target filesystem object
+      # @param [:resolve_symlinks, :target_symlinks] symlink_handling if set to
+      #   :target_symlinks and the target is a symlink, the symlink will not be
+      #   resolved but is itself used as target. By default, the symlink will
+      #   be resolved
+      def assign_to_file(path, symlink_handling = :resolve_symlinks)
+        file = to_pathname(path)
+
+        case symlink_handling
+        when :resolve_symlinks
+          file.chmod(to_i)
+        when :target_symlinks
+          begin
+            file.lchmod(to_i)
+          rescue ::NotImplementedError, Errno::ENOSYS
+            raise NotImplementedError, "lchmod function is not available in current OS or Ruby environment"
+          end
+        else
+          raise ArgumentError, "Invalid symlink handling: #{symlink_handling.inspect}"
+        end
+      end
+
+      # Represents the ComplexMode as String for debugging.
+      #
+      # @return [String] a String representation for debugging
+      def inspect
+        "#<#{self.class}: #{to_s.inspect}>"
+      end
+
+      # Represents the ComplexMode as String.
+      #
+      # Uses the format used by the `ls` utility.
+      #
+      # @return [String] a String representation
+      def to_s
+        string = ''
+
+        string << case [@special.setuid?, @user.execute?]
+                  when [true, true]
+                    @user.to_s[0..1] << 's'
+                  when [true, false]
+                    @user.to_s[0..1] << 'S'
+                  else
+                    @user.to_s
+                  end
+
+        string << case [@special.setgid?, @group.execute?]
+                  when [true, true]
+                    @group.to_s[0..1] << 's'
+                  when [true, false]
+                    @group.to_s[0..1] << 'S'
+                  else
+                    @group.to_s
+                  end
+
+        string << case [@special.sticky?, @other.execute?]
+                  when [true, true]
+                    @other.to_s[0..1] << 't'
+                  when [true, false]
+                    @other.to_s[0..1] << 'T'
+                  else
+                    @other.to_s
+                  end
+
+        string
+      end
+
+      # Converts the ComplexMode to a four-digit octal representation
+      #
+      # @return [Integer] four-digit octal representation
+      def to_i
+        result = 0
+
+        [@special, @user, @group, @other].each do |mode|
+          result = (result << 3) | mode.to_i
+        end
+
+        result
+      end
+
+      # @!method setuid
+      #   @attribute setuid [readonly]
+      #   @return (see GodObject::FilePermissions::SpecialMode#setuid)
+      #
+      # @!method setuid?
+      #   @attribute setuid? [readonly]
+      #   @return (see GodObject::FilePermissions::SpecialMode#setuid?)
+      #
+      # @!method setgid
+      #   @attribute setgid [readonly]
+      #   @return (see GodObject::FilePermissions::SpecialMode#setgid)
+      #
+      # @!method setgid?
+      #   @attribute setgid? [readonly]
+      #   @return (see GodObject::FilePermissions::SpecialMode#setgid?)
+      #
+      # @!method sticky
+      #   @attribute sticky [readonly]
+      #   @return (see GodObject::FilePermissions::SpecialMode#sticky)
+      #
+      # @!method sticky?
+      #   @attribute sticky? [readonly]
+      #   @return (see GodObject::FilePermissions::SpecialMode#sticky?)
+      def_delegators :@special, :setuid?, :setgid?, :sticky?
+
+    end
+
+  end
+end

data/lib/god_object/file_permissions/exceptions.rb

@@ -0,0 +1,33 @@
+# 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
+
+    # Base class for exceptions specific to GodObject::FilePermissions.
+    class Error < StandardError; end
+
+    # An error while parsing a String representation.
+    class ParserError < Error; end
+
+    # An error which is raised in situations where lchmod is unavailable.
+    class NotImplementedError < Error; end
+
+  end
+end