dirtravel 0.0.5 → 0.0.7

data/lib/dirtravel.rb

@@ -1,15 +1,15 @@
-# DirTravel is a library for getting information about files and
+# {DirTravel} is a library for getting information about files and
 # directories recursively to a tree structure. This library extends
 # the RubyTree classes to include directory and files info. Please
 # refer to RubyTree documentation for RubyTree related features.
 #
-# A proxy object "DirTravel::Travel" is used to gather the directory
+# A proxy object {DirTravel::Travel} is used to gather the directory
 # content. The "filetree" class method provides interface for getting
-# the content with few options (see: DirTravel::Travel.filetree for
+# the content with few options (see: {DirTravel::Travel.filetree} for
 # details).
 #
-# See the DirTravel::Entry methods doc for possibilities in examining
-# the directory hierachy.
+# See the {DirTravel::Entry} methods doc for possibilities in
+# examining the directory hierachy.
 #
 #
 # Examples:
@@ -28,24 +28,30 @@
 #     puts i.abspath
 #   end
 #
-#   # Get MP3 files and create a list of all album directories
-#   #   (assuming ".../<album>/<song>" hierarhcy).
+#   # Get MP3 files and create a list of all album directories.
+#   #   Assume: ".../<album>/<song>" hierarhcy
+#   #
 #   d = DirTravel::Travel.filetree( '.', { :suffix => '.mp3' } )
 #   albums = d.select_level( d.node_height - 1 )
 #
 
 module DirTravel
-    
+
     require 'rubytree'
 
 
+    # {DirTravel} error.
     class DirTravelError < RuntimeError; end
-    
+
 
     # Extend RubyTree base class with file and directory features.
     class Entry < Tree::TreeNode
+
+        # Node name.
         attr_accessor :name
 
+        # Set name for {Entry} (Dir/File).
+        # Initialize abspath.
         def initialize( name )
             super( name, nil )
             @abspath = nil
@@ -103,7 +109,7 @@ module DirTravel
 
 
         # Relative path of parenting directory.
-        # 
+        #
         # @param basedir [Entry] Starting level for the hierarchy.
         # @return [String] Containing directory.
         def dir( basedir = self )
@@ -114,7 +120,7 @@ module DirTravel
         # Select all siblings from given node depth.
         #
         # @param level [Integer] Selected level in hierachy. Level is
-        #                        number of steps down in hierarhcy.
+        #   number of steps down in hierarhcy.
         # @return [Array] Array of siblings in selected hierarchy.
         def select_level( level )
             select do |i| i.node_depth == level; end
@@ -127,23 +133,25 @@ module DirTravel
         end
 
 
-        # File.stat data for the Entry.
+        # File.stat data for the {Entry}.
         def stat
             File.stat( path )
         end
 
-        # Relative path Entry.
+
+        # Relative path {Entry}.
         def relative?
             @name[0] != '/'
         end
 
+
         # Rename node.
         #
-        # @param name [String] If name is abspath then Entry becomes
+        # @param name [String] If name is abspath then {Entry} becomes
         #                      abspath.
         def rename( name )
             @name = name
-            
+
             # Absolute or relative path?
             if name[0] == "/"
                 @abspath = name
@@ -153,15 +161,16 @@ module DirTravel
         end
 
     end
-    
+
 
     # Directory type entry.
     class DirEntry < Entry
 
-        # Instantiate.
+        # Set name and abspath if given.
         #
         # @param name [String] Directory name.
-        # @param abspath [String] Set abspath if given.
+        # @param abspath [String] Set abspath if given. Otherwise it
+        #                         is generated from pieces.
         def initialize( name, abspath = nil )
             super( name )
             if abspath
@@ -170,25 +179,33 @@ module DirTravel
         end
 
     end
-    
-    
+
+
     # File type entry.
     class FileEntry < Entry
         attr_reader :suffix, :basename
-        
+
+        # Set name, suffix, and basename.
+        #
+        # @param name [String] File name.
         def initialize( name )
             super( name )
             @suffix = File.extname( name )
             @basename = File.basename( name, @suffix )
         end
-        
+
     end
 
 
     # Create directory recursion tree (with
-    # Travel.filetree). Optionally filter with suffix and modify
+    # {Travel.filetree}). Optionally filter with suffix and modify
     # tree building with options Hash (see below).
-    # 
+    #
+    # If basedir is an absolute path, the root name is the search
+    # path. If basedir is a relative path, the current directory is
+    # changed to referenced directory before search and root name is
+    # the current directory, single level.
+    #
     # == Parameters:
     # sort::
     #   Sort directory entries (default: false).
@@ -204,65 +221,104 @@ module DirTravel
 
     class Travel
 
-        # Root DirEntry of Travel.
+        # Root {DirEntry} of {Travel}.
         attr_accessor :root
 
-        # Default options for Travel.
+        # Default options for {Travel}.
         attr_accessor :defaults
 
-        # Starting directory for Travel.
+        # Starting directory for {Travel}.
         attr_accessor :basedir
         attr_accessor :abspath
-        
-        # Create directory recursion tree.
+
+
+        # Create directory recursion tree and return root.
+        #
         # @param basedir [String] Starting directory (top).
-        # @param options [Hash] Hash optionally including keys: :sort, :suffix, :files.
-        # @return [DirEntry] Root item of the file system hierarchy.
+        # @param options [Hash] {Travel} options.
+        # @return [DirEntry] Root of the file travel hierarchy.
         def Travel.filetree( basedir = '.', options = {} )
 
+            # Non-nil if directory needs to be changed.
             pwd = nil
 
             if basedir[0] == '/'
+
+                # Absolue path.
                 t = Travel.new( basedir, basedir, options )
                 t.travel
+
             else
+
+                # Relative path.
+
+                # Store current directory before chdir.
                 pwd = Dir.pwd
+
+                # Generate target directory for chdir. One up from
+                # the reference.
                 full = File.absolute_path( basedir )
                 base = File.basename( full )
                 dir = File.dirname( full )
+
+                # Goto target.
                 Dir.chdir( dir )
+
                 t = Travel.new( base, full, options )
                 t.travel
             end
 
+
             if t.defaults[ :inclusive ]
+
+                # With inclusive the root is changed to one-up from
+                # target.
+
+                # One up from root.
                 uppath = File.dirname( t.root.abspath )
-                path = uppath
                 if t.root.relative?
                     path = File.basename( uppath )
+                else
+                    path = uppath
                 end
+
+                # Create the "one-up" root.
                 newRoot = DirEntry.new( path, uppath )
+
+                # Rename old root.
                 t.root.rename( t.root.tip )
+
+                # Add to one-up root.
                 newRoot.add( t.root )
+
+                # Set root to one-up root.
                 t.root = newRoot
             end
 
+            # Return back to start directory if dir changed.
             Dir.chdir( pwd ) if pwd
 
+            # Return root {DirEntry}.
             t.root
         end
 
 
+        # Create directory recursion object. Overlay options on top of
+        # defaults. Initialize root {DirEntry}.
+        #
+        # @param basedir [String] Starting directory (top).
+        # @param abspath [String] Absolute path for root.
+        # @param options [Hash] {Travel} options.
         def initialize( basedir, abspath, options = {} )
             @basedir = basedir
             @abspath = abspath
 
             @defaults = {
-                :suffix    => nil,   
-                :sort      => false, 
-                :files     => true,  
-                :inclusive => false,  
-            }                
+                :suffix    => nil,
+                :sort      => false,
+                :files     => true,
+                :inclusive => false,
+            }
 
             @defaults.merge!( options )
 
@@ -288,7 +344,7 @@ module DirTravel
             list.each do |i|
 
                 if File.file?( dir + '/' + i )
-                    
+
                     # File entry.
 
                     if ( !suffix || suffix == File.extname( i ) ) &&
@@ -325,5 +381,8 @@ module DirTravel
 
     end
 
-    
+
 end
+
+
+require_relative 'version'

data/lib/version.rb

@@ -0,0 +1,6 @@
+module DirTravel
+    VERSION = "0.0.7"
+    def DirTravel.version
+        DirTravel::VERSION
+    end
+end

data/test/test_dirtravel.rb

@@ -2,7 +2,7 @@ require 'test/unit'
 require 'dirtravel'
 
 class DirTravelTest < Test::Unit::TestCase
-    
+
     require 'fileutils'
 
     Dir.chdir 'test'
@@ -24,12 +24,12 @@ class DirTravelTest < Test::Unit::TestCase
         data = DirTravel::Travel.filetree( 'test' )
         assert_equal( 3, data.node_height )
     end
-    
+
     def test_suffix_selection
         data = DirTravel::Travel.filetree( 'test', { :suffix => ".txt" } )
-        data.files.each do |i| assert_match( i.name, /.txt$/ ) end
+        data.files.each do |i| assert_match( /.txt$/, i.name ) end
     end
-    
+
     def test_paths
         data = DirTravel::Travel.filetree( 'test' )
         2.times do
@@ -134,5 +134,5 @@ class DirTravelTest < Test::Unit::TestCase
         assert_equal( 'test_0', root.tip )
         assert_equal( 'test/test_0', root.path )
     end
-    
+
 end

metadata

@@ -1,32 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: dirtravel
 version: !ruby/object:Gem::Version
-  version: 0.0.5
-  prerelease: 
+  version: 0.0.7
 platform: ruby
 authors:
 - Tero Isannainen
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2014-01-23 00:00:00.000000000 Z
+date: 2024-06-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubytree
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.3
+        version: 2.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.3
+        version: 2.0.0
 description: DirTravel provides content of filesystem directories by recursively travelling
   the directory hierarchy. The content is organized in RubyTree structure and RubyTree
   classes are overloaded with directory entry methods for usability.
@@ -35,58 +32,56 @@ executables: []
 extensions: []
 extra_rdoc_files:
 - README.rdoc
+- CHANGELOG.rdoc
 files:
-- README.rdoc
 - CHANGELOG.rdoc
 - LICENSE
-- Rakefile
-- lib/dirtravel.rb
-- test/test_dirtravel.rb
-- doc/top-level-namespace.html
-- doc/js/full_list.js
-- doc/js/app.js
-- doc/js/jquery.js
-- doc/index.html
-- doc/css/common.css
-- doc/css/full_list.css
-- doc/css/style.css
-- doc/DirTravel/Travel.html
+- README.rdoc
+- doc/DirTravel.html
 - doc/DirTravel/DirEntry.html
 - doc/DirTravel/DirTravelError.html
 - doc/DirTravel/Entry.html
 - doc/DirTravel/FileEntry.html
-- doc/file.README.html
-- doc/method_list.html
-- doc/file_list.html
-- doc/DirTravel.html
-- doc/class_list.html
+- doc/DirTravel/Travel.html
 - doc/_index.html
+- doc/class_list.html
+- doc/css/common.css
+- doc/css/full_list.css
+- doc/css/style.css
 - doc/file.CHANGELOG.html
+- doc/file.README.html
+- doc/file_list.html
 - doc/frames.html
-homepage: 
+- doc/index.html
+- doc/js/app.js
+- doc/js/full_list.js
+- doc/js/jquery.js
+- doc/method_list.html
+- doc/top-level-namespace.html
+- lib/dirtravel.rb
+- lib/version.rb
+- test/test_dirtravel.rb
+homepage:
 licenses:
 - Ruby
+metadata: {}
 post_install_message: Check README...
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.9.3
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 1.8.23
-signing_key: 
-specification_version: 3
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
 summary: Small and simple library for accessing filesystem directories.
 test_files: []
-has_rdoc: 

data/Rakefile

@@ -1,28 +0,0 @@
-require 'rake/testtask'
-
-Rake::TestTask.new do |t|
-    t.libs << 'test'
-end
-
-desc "Run tests"
-task :default => :test
-
-task :cleanup_test do
-    sh "rm -rf test/test"
-end
-
-task :build => :doc do
-    sh "gem build dirtravel.gemspec"
-end
-
-task :doc do
-    sh "yardoc lib/* - README.rdoc CHANGELOG.rdoc"
-end
-
-task :publish do
-    if Dir.glob('dirtravel-*gem').length == 1
-        sh "gem push dirtravel*.gem"
-    else
-        raise "Multiple gems in the directory..."
-    end
-end