file_mode 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e7111de3e1b1269c364ec2b68c7337f75686cc17
+  data.tar.gz: 2287af1a240cce77f7b370a4987271259f72e057
+SHA512:
+  metadata.gz: 6516cac2615f49fb57edd9964a5b9cc1cf128e3a1bebcfc98dafb76feb14343b7351e1bb786302d92cb41b25de39ad4a9ba60f871810c6cdd77f5d7b537f7a15
+  data.tar.gz: f593a5c60f92342ed114aacd8edda386f9d60231bf237cb5cc946b80a9b4b71d6e93df91e3b2db8112af59e17d80a3dfd581eedebaf70d16caf27f2fe1dc8b76

data/LICENSE

@@ -0,0 +1,26 @@
+Copyright 2014 Martin Carpenter. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are
+permitted provided that the following conditions are met:
+
+   1. Redistributions of source code must retain the above copyright notice, this list of
+      conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright notice, this list
+      of conditions and the following disclaimer in the documentation and/or other materials
+      provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY Martin Carpenter ``AS IS'' AND ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL Martin Carpenter OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The views and conclusions contained in the software and documentation are those of the
+authors and should not be interpreted as representing official policies, either expressed
+or implied, of Martin Carpenter.
+

data/README.rdoc

@@ -0,0 +1,87 @@
+
+= file_mode
+
+Author:: Martin Carpenter
+Email:: mcarpenter@free.fr
+Copyright:: Copyright (c) Martin Carpenter 2014
+
+== About
+
+The file_mode gem assists with manipulation of four-octal-digit UNIX
+file modes by providing readable method names rather than error-prone
+bit twiddles. It also provides methods to convert to and from standard
+ls(1)-style long listing formats. The class methods can be used standalone
+or this module can be mixed in to a class that has an integer :mode
+attribute.
+
+== Examples
+
+=== Class method use
+
+    require 'file_mode'
+
+    FileMode.user_readable?(0o644)
+    => true
+    FileMode.setuid?(0o4755)
+    => true
+    FileMode.int_to_listing(0o644)
+    => "rw-r--r--"
+    FileMode.listing_to_str('rwsr-xr-x')
+    => "4755"
+
+=== Mixin use
+
+    require 'file_mode'
+
+    class FileLikeThing
+      include FileMode
+      attr_accessor :mode
+    end
+
+    flt = FileLikeThing.new
+    flt.mode = 0o0644
+    flt.user_readable?
+    => true
+    flt.setuid?
+    => false
+
+== Mode formats
+
+The module offers three forms of mode representation:
+
+* integer (eg 0o0644 or 420 decimal)
+* string ('0644')
+* listing ('rw-r--r--')
+
+Listing formats are not necessarily identical across UNIX-like operating
+systems, or even across applications on the same operating system. A
+case in point is Solaris which shows mandatory file lock permission as
+'l' with standard ls(1) and 'L' with XPG-compatible ls(1).
+
+This module aims to take any standard format as input
+(listing_to_... methods) and targets Linux/GNU coreutils for
+output(..._to_listing methods).
+
+=== Some conversion gotchas
+
+Beware the following standard ruby gotchas when making conversions using
+#to_i and a solitary leading zero to specify octal mode:
+
+    644.to_i
+    => 644       # ok
+    '644'.to_i
+    => 644       # ok
+    0644.to_i
+    => 420       # ok
+    '0644'.to_i
+    => 644       # ! leading zero is ignored
+    '0o644'.to_i
+    => 0         # ! parsing stops at 'o'
+
+== Unit tests
+
+Unit tests are provided particularly for the conversion between the
+ls(1)-style long-listing format and integer representations. Since
+the long-listing format can vary between systems a script
+bin/create_listing_test.rb is provided to generate unit test files.
+

data/Rakefile

@@ -0,0 +1,34 @@
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rdoc/task'
+require 'rubygems/package_task'
+
+desc 'Default task (package)'
+task :default => [:package]
+
+desc 'Create listing unit test'
+task :create_listing_test do
+  $:.unshift(File.join(File.dirname(__FILE__), 'lib'))
+  load File.join('bin', 'create_listing_test.rb')
+end
+
+Rake::TestTask.new( 'test' )
+
+SPECFILE = 'file_mode.gemspec'
+if File.exist?(SPECFILE)
+  spec = eval(File.read(SPECFILE))
+  Gem::PackageTask.new(spec).define
+end
+
+RDoc::Task.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = 'file_mode'
+  rdoc.options << '--charset' << 'utf-8'
+  rdoc.options << '--main' << 'README.rdoc'
+  rdoc.options << '--all'
+  rdoc.rdoc_files.include('README.rdoc' )
+  rdoc.rdoc_files.include(FileList['lib/**/*.rb'])
+  rdoc.rdoc_files.include(FileList['test/*.rb' ])
+end
+

data/lib/file_mode.rb

@@ -0,0 +1,150 @@
+
+# Module for UNIX octal file modes. Classes that mixin this module
+# must have a mode attribute that is the integer representation
+# of the mode.
+module FileMode
+
+  # Class methods. These are both extended into the FileMode
+  # class and mixed-in as instance methods on classes that
+  # "include FileMode" when the class Fixnum attribute :mode
+  # is used in place of the argument of the same name.
+  module ClassMethods
+
+    # Return true if the mode is readable by user, false otherwise.
+    def user_readable?(mode)
+      mode & 00400 == 00400
+    end
+
+    # Return true if the mode is readable by group, false otherwise.
+    def group_readable?(mode)
+      mode & 00040 == 00040
+    end
+
+    # Return true if the mode is readable by other, false otherwise.
+    def other_readable?(mode)
+      mode & 00004 == 00004
+    end
+
+    # Return true if the mode is writable by user, false otherwise.
+    def user_writable?(mode)
+      mode & 00200 == 00200
+    end
+
+    # Return true if the mode is writable by group, false otherwise.
+    def group_writable?(mode)
+      mode & 00020 == 00020
+    end
+
+    # Return true if the mode is writable by other, false otherwise.
+    def other_writable?(mode)
+      mode & 00002 == 00002
+    end
+
+    # Return true if the mode is executable by user, false otherwise.
+    def user_executable?(mode)
+      mode & 00100 == 00100
+    end
+
+    # Return true if the mode is executable by group, false otherwise.
+    def group_executable?(mode)
+      mode & 00010 == 00010
+    end
+
+    # Return true if the mode is executable by other, false otherwise.
+    def other_executable?(mode)
+      mode & 00001 == 00001
+    end
+
+    # Return true if mode has the setuid bit set, false otherwise.
+    def setuid?(mode)
+      mode & 04000 == 04000
+    end
+
+    # Return true if mode has the setgid bit set, false otherwise.
+    def setgid?(mode)
+      mode & 02000 == 02000
+    end
+
+    # Return true if mode has the sticky bit set, false otherwise.
+    def sticky?(mode)
+      mode & 01000 == 01000
+    end
+
+  end # ClassMethods
+
+  extend ClassMethods
+
+  # Convert an integer mode to a 4 digit octal string.
+  def self.int_to_str(int)
+    int.to_s(8).rjust(4, '0')
+  end
+
+  # Convert an octal string to an integer.
+  def self.str_to_int(str)
+    str.to_i(8)
+  end
+
+  # Convert a permissions listing string to its integer equivalent.
+  def self.listing_to_int(listing)
+    int = listing.chars.map do |c|
+      # l/L are for mandatory file locking on Solaris.
+      %w{ - S T l L }.include?(c) ? 0 : 1
+    end.join.to_i(2)
+    int += 04000 if %w{ s S }.include?(listing[2]) # setuid
+    int += 02000 if %w{ s S l L }.include?(listing[5]) # setgid
+    int += 01000 if %w{ t T }.include?(listing[8]) # sticky
+    int
+  end
+
+  # Convert permissions listing string to a string of its octal representation.
+  def self.listing_to_str(listing)
+    int_to_str(listing_to_int(listing))
+  end
+
+  # Mapping between a single octal digit and its permissions listing.
+  OCTAL_DIGIT_TO_LISTING = {
+    0 => '---',
+    1 => '--x',
+    2 => '-w-',
+    3 => '-wx',
+    4 => 'r--',
+    5 => 'r-x',
+    6 => 'rw-',
+    7 => 'rwx'
+  }
+
+  # Convert an integer into its permissions listing string. Listing strings
+  # may vary between operating systems (and even between applications on the
+  # same operating system). The listing output here matches the ouput from
+  # Linux/GNU coreutils ls(1).
+  def self.int_to_listing(int)
+    perms = [ [6, 00700], [3, 00070], [0, 00007] ].map do |bitshift, mask|
+      OCTAL_DIGIT_TO_LISTING[(int & mask) >> bitshift]
+    end.join
+    if 0 != int & 04000 # setuid
+      perms[2] = perms[2] == 'x' ? 's' : 'S'
+    end
+    if 0 != int & 02000 # setgid
+      perms[5] = perms[5] == 'x' ? 's' : 'S'
+    end
+    if 0 != int & 01000 # sticky
+      perms[8] = perms[8] == 'x' ? 't' : 'T'
+    end
+    perms
+  end
+
+  # Convert an octal string into its permissions listing string.
+  def self.str_to_listing(str)
+    int_to_listing(str.to_i(8))
+  end
+
+  # Create instance methods on FileMode that forward to the
+  # corresponding class method with an implicit self.mode argument.
+  ClassMethods.instance_methods(false).each do |mixin_method|
+    define_method(mixin_method) do |*args|
+      FileMode.send(mixin_method, *(args.dup.unshift(self.mode)))
+    end
+  end
+
+end # FileMode
+