fun_with_files 0.0.15 → 0.0.18

data/lib/fun_with/files/file_path.rb

@@ -2,10 +2,10 @@ module FunWith
   module Files
     class FilePath < Pathname
       SUCC_DIGIT_COUNT = 6
-      DEFAULT_TIMESTAMP_FORMAT = "%Y%m%d%H%M%S%L"
 
-      def initialize( *args )
-        super( File.join( *args ) )
+      def initialize( *args, &block )
+        super( File.join( *(args.map(&:to_s) ) ) )
+        _yield_and_return( self, &block )
       end
 
       attr_accessor :path
@@ -40,30 +40,29 @@ module FunWith
 
       def join( *args, &block )
         joined_path = self.class.new( super( *(args.map(&:to_s) ) ) )
-        yield joined_path if block_given?
-        joined_path
+        _yield_and_return( joined_path, &block )
       end
       
       def join!( *args, &block )
         @path = self.join( *args, &block ).to_str
-        self
+        _yield_and_return( self, &block )
       end
       
-      def / arg
-        self.join( arg )
+      def /( arg, &block )
+        _yield_and_return( self.join( arg ), &block )
       end
       
-      def [] *args
-        self.join(*args)
+      def []( *args, &block )
+        _yield_and_return( self.join(*args), &block )
       end
       
       
-      def doesnt_exist?
-        self.exist? == false
+      def doesnt_exist?( &block )
+        _yield_self_on_success( self.exist? == false, &block )
       end
       
-      def not_a_file?
-        ! self.file?
+      def not_a_file?( &block )
+        _yield_self_on_success( ! self.file?, &block )
       end
 
       alias :absent? :doesnt_exist?
@@ -193,8 +192,16 @@ module FunWith
         end
       end
 
-      def entries
-        self.glob( :recurse => false )
+      def entries( &block )
+        rval = self.glob( :recurse => false )
+        
+        if block_given?
+          for entry in rval
+            yield entry
+          end
+        end
+        
+        rval
       end
 
       def expand
@@ -207,7 +214,7 @@ module FunWith
       #
       # Takes an options hash as the last argument, allowing same options as FileUtils.touch
       def touch( *args, &block )
-        args, opts = extract_opts_from_args( args )
+        args, opts = Utils::Opts.extract_opts_from_args( args )
 
         raise "Cannot create subdirectory to a file" if self.file? && args.length > 0
         touched = self.join(*args)
@@ -222,7 +229,7 @@ module FunWith
           end
 
         self.touch_dir( dir_for_touched_file, opts ) unless dir_for_touched_file.directory?
-        FileUtils.touch( touched, narrow_options( opts, FileUtils::OPT_TABLE["touch"] ) )
+        FileUtils.touch( touched, ** Utils::Opts.narrow_file_utils_options( opts, :touch ) )
 
         yield touched if block_given?
         return touched
@@ -231,13 +238,13 @@ module FunWith
       # Takes the options of both FileUtils.touch and FileUtils.mkdir_p
       # mkdir_p options will only matter if the directory is being created.
       def touch_dir( *args, &block )
-        args, opts = extract_opts_from_args( args )
+        args, opts = Utils::Opts.extract_opts_from_args( args )
 
         touched = self.join(*args)
         if touched.directory?
-          FileUtils.touch( touched, narrow_options( opts, FileUtils::OPT_TABLE["touch"] ) )    # update access time
+          FileUtils.touch( touched, ** Utils::Opts.narrow_file_utils_options( opts, :touch ) )    # update access time
         else
-          FileUtils.mkdir_p( touched, narrow_options( opts, FileUtils::OPT_TABLE["mkdir_p"] ) )  # create directory (and any needed parents)
+          FileUtils.mkdir_p( touched, ** Utils::Opts.narrow_file_utils_options( opts, :mkdir_p ) )  # create directory (and any needed parents)
         end
 
         yield touched if block_given?
@@ -245,7 +252,7 @@ module FunWith
       end
 
       def write( *args, &block )
-        args, opts = extract_opts_from_args( args )
+        args, opts = Utils::Opts.extract_opts_from_args( args )
 
         content = args.first
 
@@ -305,14 +312,16 @@ module FunWith
       # empty? has different meanings depending on whether you're talking about a file
       # or a directory.  A directory must not have any files or subdirectories.  A file
       # must not have any data in it.
-      def empty?
+      def empty?( &block )
         raise Exceptions::FileDoesNotExist unless self.exist?
-
+        
         if self.file?
-          File.size( self ) == 0
+          is_empty = File.size( self ) == 0
         elsif self.directory?
-          self.glob( :all ).fwf_blank?
+          is_empty = Dir.entries( self ).length <= 2   # Dir.entries returns ".." and "." even when nothing else is there
         end
+        
+        _yield_self_on_success( is_empty, &block )
       end
 
       # Does not return a filepath
@@ -321,6 +330,22 @@ module FunWith
       def basename_no_ext
         self.basename.to_s.split(".")[0..-2].join(".")
       end
+      
+      # 
+      def size( units = :B )
+        sz = self.stat.size
+        
+        case units
+        when :B
+          sz
+        when :K
+          (sz / 1024.0).round(1)
+        when :M
+          (sz / 1048576.0).round(1)
+        when :G
+          (sz / 1073741824.0).round(1)
+        end
+      end
 
       # Returns the path, stripped of the final extension (.ARG).
       # The result cannot destroy a dotfile or leave an empty
@@ -396,10 +421,13 @@ module FunWith
         # self.class.new( new_path )
       end
 
-      # Two separate modes.  With no arguments given, returns the current extension as a string (not a filepath)
-      # With an argument, returns the path with a .(arg) tacked onto the end.  The leading period is wholly optional.
-      # Does not return a filepath.
-      # Does not include leading period
+      # Two separate modes.  
+      #
+      # With no arguments given, returns the current extension as a string (not a filepath). No leading period.
+      # 
+      # With an argument, returns the path with a .(arg) tacked onto the end.  Result is the same whether a leading
+      # period is given or not.  Multiple extensions can be given, and any object can be used so long as it responds
+      # sensibly to .to_s() (use at your own risk).  Integers work, for example.  
       def ext( *args )
         if args.length == 0
           split_basename = self.basename.to_s.split(".")
@@ -415,6 +443,21 @@ module FunWith
           self.class.new( "#{@path}#{appended_to_path}" )
         end
       end
+      
+      # asks if the .XXX at the end of the path matches one of the extensions given
+      # as an argument.  If a block is given, the block will be run if the extension
+      # matches, ignored if no match is detected.
+      def ext?( *extensions, &block )
+        # Why is .to_str used here instead of to_s?
+        acceptable_extensions = extensions.map do |e|
+          ext = e.is_a?( Pathname ) ? e.to_str : e.to_s
+          ext.gsub(/^\./,'')
+        end
+        
+        ext_matches = acceptable_extensions.include?( self.ext )  
+        
+        _yield_self_on_success( ext_matches, &block )
+      end
 
       # base, ext =  @path.basename_and_ext
       def basename_and_ext
@@ -438,8 +481,8 @@ module FunWith
         self.directory? ? self : self.dirname
       end
 
-      def original?
-        !self.symlink?
+      def original?(&block)
+        _yield_self_on_success( !self.symlink?, &block )
       end
 
       def original
@@ -452,78 +495,58 @@ module FunWith
         self.class.new( dir )
       end
 
-      def fwf_filepath
+      def fwf_filepath( &block )
+        yield self if block_given?
         self
       end
-
-      # Gives a sequence of files.  Examples:
-      # file.dat --> file.000000.dat
-      # file_without_ext --> file_without_ext.000000
-      # If it sees a six-digit number at or near the end of the
-      # filename, it increments it.
-      #
-      # You can change the length of the sequence string by passing
-      # in an argument, but it should always be the same value for
-      # a given set of files.
+      
+      # Making this stricter, and failing when the formatting doesn't meet expectations, rather than 
+      # guessing wildly about what to do on corner cases.
+      # 
+      # This file is part of a sequence of files (file.000001.txt, file.000002.txt, file.000003.txt, etc.)
+      # `succ()` gives you the next file in the sequence.  If no counter is present, a counter is 
+      # added (file.dat --> file.000000.dat)
       #
-      # TODO: Need to get this relying on the specifier() method.
-      def succ( opts = { digit_count: SUCC_DIGIT_COUNT, timestamp: false } )
-        if timestamp = opts[:timestamp]
-          timestamp_format = timestamp.is_a?(String) ? timestamp : DEFAULT_TIMESTAMP_FORMAT
-          timestamp = Time.now.strftime( timestamp_format )
-          digit_count = timestamp.length
-        else
-          timestamp = false
-          digit_count = opts[:digit_count]
+      # You can change the length of the sequence string by passing in the `digit_count` argument.
+      # Changing the length for a given sequence will lead to the function not recognizing the existing
+      # counter, and installing a new one after it.
+      def succ( digit_count: SUCC_DIGIT_COUNT )
+        directory_pieces = self.split
+        succession_basename = Utils::Succession.get_successor_name( directory_pieces.pop, digit_count )
+        
+        return FilePath.new( * directory_pieces ) / succession_basename
+      end
+      
+      
+      def timestamp( format: :default, time: Time.now, splitter: ".", &block )
+        timestamped_basename = Utils::Timestamp.timestamp( self.basename, format: format, time: time, splitter: splitter )
+        
+        directory_path = self.split[0..-2]
+        
+        # sigh....
+        if directory_path.first.path == "." && self.path[0..1] != ".#{File::SEPARATOR}"
+          directory_path.shift
         end
-
-        chunks = self.basename.to_s.split(".")
-        # not yet sequence stamped, no file extension.
-        if chunks.length == 1
-          if timestamp
-            chunks.push( timestamp )
-          else
-            chunks.push( "0" * digit_count )
-          end
-        # sequence stamp before file extension
-        elsif match_data = chunks[-2].match( /^(\d{#{digit_count}})$/ )
-          if timestamp
-            chunks[-2] = timestamp
-          else
-            i = match_data[1].to_i + 1
-            chunks[-2] = sprintf("%0#{digit_count}i", i)
-          end
-        # try to match sequence stamp to end of filename
-        elsif match_data = chunks[-1].match( /^(\d{#{digit_count}})$/ )
-          if timestamp
-            chunks[-1] = timestamp
-          else
-            i = match_data[1].to_i + 1
-            chunks[-1] = sprintf("%0#{digit_count}i", i)
-          end
-        # not yet sequence_stamped, has file extension
+        
+        if directory_path.length == 0
+          timestamped_file = timestamped_basename.fwf_filepath
         else
-          chunks = [chunks[0..-2], (timestamp ? timestamp : "0" * digit_count), chunks[-1]].flatten
+          timestamped_file = FilePath.new( * self.split[0..-2], timestamped_basename ) 
         end
-
-        self.up.join( chunks.join(".") )
-      end
-
-
-      def timestamp( format = true, &block )
-        nxt = self.succ( :timestamp => format )
-        yield nxt if block_given?
-        nxt
+        
+        _yield_and_return( timestamped_file, &block )
       end
-
+      
       # puts a string between the main part of the basename and the extension
       # or after the basename if there is no extension.  Used to describe some
       # file variant.
+      # 
       # Example "/home/docs/my_awesome_screenplay.txt".fwf_filepath.specifier("final_draft")
       #  => FunWith::Files::FilePath:/home/docs/my_awesome_screenplay.final_draft.txt
       #
-      # Oh hush.  *I* find it useful.
-      def specifier( str )
+      # For the purposes of this method, anything after the last period in the filename
+      # is considered the extension.
+      def specifier( str, &block )
         str = str.to_s
         chunks = self.to_s.split(".")
 
@@ -533,9 +556,13 @@ module FunWith
           chunks = chunks[0..-2] + [str] + [chunks[-1]]
         end
 
-        chunks.join(".").fwf_filepath
+        f = chunks.join(".").fwf_filepath
+        _yield_and_return( f, &block )
       end
-
+      
+      # Returns the "wildcarded" version of the filename, suitable for finding related files
+      # with similar timestamps.  
+      #
       # TODO: succession : enumerates a sequence of files that get passed
       # to a block in order.
       def succession( opts = { digit_count: SUCC_DIGIT_COUNT, timestamp: false } )
@@ -593,45 +620,11 @@ module FunWith
       # the failed requirement in order to try it later.  Doesn't fail until it goes through
       # a full loop where none of the required files were successful.
       def requir
-        if self.directory?
-          requirements = self.glob( :recursive => true, :ext => "rb" )
-          successfully_required = 1337  # need to break into initial loop
-          failed_requirements = []
-          error_messages = []
-
-          while requirements.length > 0 && successfully_required > 0
-            successfully_required = 0
-            failed_requirements = []
-            error_messages = []
-
-            for requirement in requirements
-              begin
-                requirement.requir
-                successfully_required += 1
-              rescue Exception => e
-                failed_requirements << requirement
-                error_messages << "Error while requiring #{requirement} : #{e.message} (#{e.class})"
-              end
-            end
-
-            requirements = failed_requirements
-          end
-
-          if failed_requirements.length > 0
-            msg = "requiring directory #{self} failed:\n"
-            for message in error_messages
-              msg << "\n\terror message: #{message}"
-            end
-
-            raise NameError.new(msg)
-          end
-        else
-          require self.expand.gsub( /\.rb$/, '' )
-        end
+        FunWith::Files::Requirements::Manager.require_files( self )
       end
-
-      def root?
-        self == self.up
+      
+      def root?(&block)
+        _yield_self_on_success( self == self.up, &block)
       end
 
       def descend( &block )
@@ -676,43 +669,47 @@ module FunWith
 
       protected
       # TODO: Need a separate API for user to call
-      def _must_be_a_file
+      def must_be_file
         unless self.file?
           calling_method = caller[0][/`.*'/][1..-2]
-          raise Errno::EACCESS.new( "Can only call FunWith::Files::FilePath##{calling_method}() on an existing file.")
+          raise Errno::EACCES.new( "Can only call FunWith::Files::FilePath##{calling_method}() on an existing file.")
         end
       end
 
-      def _must_be_a_directory
+      def must_be_directory
         unless self.directory?
           calling_method = caller[0][/`.*'/][1..-2]
-          raise Errno::EACCESS.new( "Can only call FunWith::Files::FilePath##{calling_method}() on an existing directory.")
+          raise Errno::EACCES.new( "Can only call FunWith::Files::FilePath##{calling_method}() on an existing directory." )
         end
       end
 
-      def _must_be_writable
+      def must_be_writable
         unless self.writable?
           calling_method = caller[0][/`.*'/][1..-2]
-          raise Errno::EACCESS.new( "Error in FunWith::Files::FilePath##{calling_method}(): #{@path} not writable.")
+          raise Errno::EACCES.new( "Error in FunWith::Files::FilePath##{calling_method}(): #{@path} not writable." )
         end
       end
-
-      def narrow_options( opts, keys )
-        opts.keep_if{ |k,v| keys.include?( k ) }
+      
+      # Simplifies some of the block-formed methods
+      def _yield_and_return( obj = self, &block )
+        yield obj if block_given?
+        obj
       end
-
-      def extract_opts_from_args( args )
-        if args.last.is_a?( Hash )
-          [args[0..-2], args.last ]
+      
+      # There are a bunch of methods that interrogate the path, and I want them all to respond to the
+      # same block form.  @file.exists?, run the block.  @file.writable?, run the block.  In all cases,
+      # the path is yielded as an argument
+      def _yield_self_on_success( success, &block )
+        if block_given?
+          if success
+            yield self
+          else
+            false
+          end
         else
-          [args, {}]
+          success
         end
       end
-
-      def yield_and_return( obj, &block )
-        yield obj if block_given?
-        obj
-      end
     end
   end
 end

data/lib/fun_with/files/file_path_class_methods.rb

@@ -15,11 +15,32 @@ module FunWith
       end
       
       def config_dir( *args )
-        XDG['CONFIG'].fwf_filepath.join( *args )
+        xdg_get('CONFIG').fwf_filepath.join( *args )
       end
       
       def data_dir( *args )
-        XDG['DATA'].fwf_filepath.join( *args )
+        xdg_get('DATA').fwf_filepath.join( *args )
+      end
+      
+      def cache_dir( *args )
+        xdg_get('CACHE_HOME').fwf_filepath.join( *args )
+      end
+      
+      def xdg_get( str )
+        if XDG.respond_to?( :"[]" )
+          XDG[str]
+        else
+          case str
+          when "CONFIG"
+            XDG::Environment.new.config_home
+          when "DATA"
+            XDG::Environment.new.data_home
+          when "CACHE_HOME"
+            XDG::Environment.new.cache_home
+          else
+            raise "Not sure what to do with XDG:#{str}"
+          end
+        end
       end
       
       # Honestly this is a token attempt at Windows compatibility.

data/lib/fun_with/files/file_permission_methods.rb

@@ -2,20 +2,31 @@ module FunWith
   module Files
     # view and change file permissions
     module FilePermissionMethods
-      def readable?
-        File.readable?( self )
+      def readable?( &block )
+        _yield_self_on_success( File.readable?( self ), &block )
       end
       
-      def writable?
-        File.writable?( self )
+      def writable?( &block )
+        _yield_self_on_success( File.writable?( self ), &block )
       end
       
-      def executable?
-        File.executable?( self )
+      def executable?( &block )
+        _yield_self_on_success( File.executable?( self ), &block )
       end
       
+      # options:  :noop, :verbose
       def chmod( mode, opts = {} )
-        FileUtils.chmod( mode, self, narrow_options( opts, FileUtils::OPT_TABLE["chmod"] ) )
+        FileUtils.chmod( mode, self, ** Utils::Opts.narrow_file_utils_options( opts, :chmod ) )
+      end 
+      
+      # options:  :noop, :verbose
+      def chown( user, opts = {} )
+        FileUtils.chown( user, self, ** Utils::Opts.narrow_file_utils_options( opts, :chown ) )
+      end
+      
+      def owner
+        uid = File.stat( self ).uid
+        Etc.getpwuid( uid ).name
       end
     end
   end

data/lib/fun_with/files/file_requirements.rb

@@ -1,22 +1,78 @@
 module FunWith
   module Files
     module FileRequirements
-      def _raise_error_if_not test, msg, error_class
-        if test
-          raise error_class.new( msg + "(file: #{self})" )
-        end
+      def needs_to_exist error_msg = "Path does not exist"
+        _raise_error_if_not self.exist?, error_msg, Errno::ENOENT
       end
       
       def needs_to_be_a_file error_msg = "Path is not a file"
+        self.needs_to_exist( error_msg + " (does not exist)" )
         _raise_error_if_not self.file?, error_msg, Errno::ENOENT
       end
       
+      def needs_to_be_readable error_msg = "Path is not readable"
+        self.needs_to_exist( error_msg + " (does not exist)" )
+        _raise_error_if_not self.writable?, error_msg, Errno::EPERM
+      end
+      
       def needs_to_be_writable error_msg = "Path is not writable"
-        _raise_error_if_not self.writable?, error_msg, Errno::ENOENT
+        self.needs_to_exist( error_msg + " (does not exist)" )
+        _raise_error_if_not self.writable?, error_msg, Errno::EPERM
       end
       
-      def needs_to_be_empty error_msg = "Path needs to point to"
-        _raise_error_if_not self.empty?, error_msg, Errno::ENOENT
+      def needs_to_be_executable error_msg = "Path is not executable"
+        self.needs_to_exist( error_msg + " (does not exist)" )
+        _raise_error_if_not self.executable?, error_msg, Errno::ENOEXEC
+      end
+      
+      # returns a different code depending on whether the path is a file
+      # or a directory.
+      def needs_to_be_empty error_msg = "Path needs to be empty"
+        self.needs_to_exist( error_msg + " (does not exist)" )
+        error_class = Errno::EOWNERDEAD                         # it's as good a code as any
+        error_class = Errno::ENOTEMPTY       if self.directory?
+        error_class = Errors::FileNotEmpty   if self.file?      # there's no libc error for "file oughta be empty"
+        
+        _raise_error_if_not self.empty?, error_msg, error_class
+      end
+      
+      def needs_to_be_a_directory error_msg = "Path is not a directory"
+        self.needs_to_exist( error_msg + " (does not exist)" )
+        _raise_error_if_not self.directory?, error_msg, Errno::ENOTDIR
+      end
+      
+      def needs_to_be( *requirements )
+        for requirement in requirements
+          case requirement
+          when :exist
+            self.needs_to_exist
+          when :readable
+            self.needs_to_be_readable
+          when :writable
+            self.needs_to_be_writable
+          when :executable
+            self.needs_to_be_executable
+          when :empty
+            self.needs_to_be_empty
+          when :directory
+            self.needs_to_be_a_directory
+          when :file
+            self.needs_to_be_a_file
+          else
+            warn "Did not understand file.needs_to_be constraint: #{arg}"
+          end
+        end
+      end
+      
+      protected
+      def _raise_error_if test, msg, error_class
+        if test
+          raise error_class.new( msg + "(file: #{self})" )
+        end
+      end
+      
+      def _raise_error_if_not test, msg, error_class
+        _raise_error_if !test, msg, error_class
       end
     end
   end