fast 0.1.3 → 0.1.4

data/.gitignore

@@ -1,3 +1,4 @@
 pkg/*
 *.gem
 .bundle
+.rbx

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - jruby-18mode
+  - jruby-19mode
+  - rbx-18mode
+  - rbx-19mode
+  - ree

data/Gemfile

@@ -2,3 +2,7 @@ source "http://rubygems.org"
 
 # Specify your gem's dependencies in fast.gemspec
 gemspec
+
+group :test do
+  gem "rake"
+end

data/Gemfile.lock

@@ -1,14 +1,16 @@
 PATH
   remote: .
   specs:
-    fast (0.1.2)
+    fast (0.1.4)
       metafun (>= 0.2.0)
+      sub-setter (>= 0.0.2)
 
 GEM
   remote: http://rubygems.org/
   specs:
     diff-lcs (1.1.3)
     metafun (0.2.0)
+    rake (0.9.2.2)
     rspec (2.8.0)
       rspec-core (~> 2.8.0)
       rspec-expectations (~> 2.8.0)
@@ -17,6 +19,7 @@ GEM
     rspec-expectations (2.8.0)
       diff-lcs (~> 1.1.2)
     rspec-mocks (2.8.0)
+    sub-setter (0.0.2)
     zucker (12.1)
 
 PLATFORMS
@@ -24,5 +27,6 @@ PLATFORMS
 
 DEPENDENCIES
   fast!
+  rake
   rspec
   zucker

data/README.md

@@ -0,0 +1,122 @@
+Fast
+==== 
+
+[![Build Status](https://secure.travis-ci.org/xaviervia/fast.png)](http://travis-ci.org/xaviervia/fast)
+
+Tired of having a hard time working with files? Take a look at Fast...
+
+    require "fast"
+    
+    lib_dir = dir! :lib # Creates a new dir "lib"
+    
+    lib_dir["demo.txt"] = "I love creating files from a Hash-like API"  
+      # Creates lib/demo.txt containing the text
+    
+    lib_dir.list  # => ['demo.txt']
+    
+    file! "lib/empty.txt" # New file lib/empty.txt
+    
+    lib_dir.files do |path|
+      puts path
+    end # => demo.txt
+        #    empty.txt
+  
+    lib_dir.destroy
+    
+    dir? :lib     # => false
+
+...and finally is **quite stable** so you can use it if you wish so.
+
+Fast is a DSL for file and dir handling focused in intuitivity and semantics. Fast is pure Ruby, don't relays on OS functions, so is a little slower but more portable.
+
+Installation
+------------
+
+    gem install fast
+
+Usage
+-----
+
+Fast declares two sets of methods in its DSL:
+
+### Dir methods
+
+    dir :lib                # The same as => Fast::Dir.new "lib"
+    dir.delete! "demo"      # The same as => Fast::Dir.new.delete! "demo"
+  
+    dir! :new_dir           # The same as => Fast::Dir.new.create! :new_dir
+    dir? :new_dir           # The same as => Fast::Dir.new.exist? :new_dir
+  
+### File methods
+
+    file "demo.txt"         # The same as => Fast::File.new "demo.txt"
+    file.copy "demo.txt", "new.txt"  # The same as =>
+                          # Fast::File.new.copy "demo.txt", "new.txt"
+                          
+    file! "demo.txt"        # The same as => Fast::File.new.create! "demo.txt"
+    file? "demo.txt"        # The same as => Fast::File.new.exist? "demo.txt"
+
+Philosophy
+----------
+
+*Fast* embraces the more straightforward view of files as strings of data and directories as arrays of files/directories. Why?
+
+* It is more realistic in everyday usage
+* It makes them more object-like (and thus, more friendly to OOP)
+* It is more semantic
+* Files as IOs are still accessible through the harder-to-use native Ruby API
+
+<tt>Fast::Dir</tt> is a subclass of <tt>Array</tt>, usable as a hash, and <tt>Fast::File</tt> if a subclass of String.
+
+Conflicts
+---------
+
+It is a known issue that the DSL of Fast conflicts with [Pry][pry-gem] and most notable with [Rake][rake-gem]; I am aware that is a bold move to reclaim `file` from the standard namespace for Fast to use.
+
+In order to workaround that, you can require fast in a not-so-much DSL way:
+
+    require "fast/fast"
+    
+    Fast.file "myfile.txt" # The same as `file "myfile.txt"`
+    
+    Fast.dir! :lib # etc...
+
+This is also the recommended form when using Fast in the context of a library. 
+
+> Also: try to avoid using Fast in a library, because Fast is mostly semantic sugar and you want to avoid adding loading time just for the sake of having a couple of convenience methods. Fast is more fun when used for code sketching and simple scripts.
+
+[pry-gem]: https://github.com/pry/pry
+[rake-gem]: http://rake.rubyforge.org/
+
+Quick notes (to self)
+---------------------
+
+* Rename FilesystemObject: Item, CommonMethods, AbstractFile, FastHelpers (think!)
+* Deliberate whether is a good idea to make Fast::Dir and Fast::File Multitons. (May be only when an absolute path is used)
+* The path can be setted indirectly by any method of Fast::File instances, and the same works for Dir. This is fine because allows for very quick calls, but once an instance gets a path setted it should be fixed and raise an exception in case some other method call is trying to change it.
+
+### Fast::File
+* Read bytes as binary ASCII-8BIT always and then try to perform an heuristic conversion, if there is any reasonable way to do it. Otherwise, leave it to the user. Google: "ruby string encode utf-8 ascii" for some good readings.
+
+### Fast::Dir
+* Calls to #dirs and #files should delegate to a SubSetter
+* Change the behaviour in the calls to #dirs and #files: return a new instance, with no @path setted.
+* Change the behaviour in the initialization: call #list always if there's a path an the path matches an existing directory
+* Allow for easy recursive calls (#list_all, #files_all, #dirs_all for example, think of better synonyms)
+* Deliberate whether "#<<" should be kept in Fast::Dir and if it should be used as alias for merge
+* An instance of Fast::Dir should be possible to be created from a Array. (pity I didn't specified an usage case) 
+* Add documentation to Patterns::Adapter::Fast::Dir
+
+Remote future
+-------------
+
+* Make Fast a REST client (well, use <tt>rest-client</tt>) in order to transparently use files and directories from a compliant REST server. 
+* Include REST methods: Dir#post, File#get, File#head, etc and equivalents for local files (prepare ground for Piano Rest)
+* Allow Files to behave as Dirs with the right method calls
+
+License
+-------
+
+GPL License. Why other?
+
+@ Xavier Via

data/fast.gemspec

@@ -15,7 +15,8 @@ Gem::Specification.new do |s|
   s.rubyforge_project = "fast"
   
   s.add_dependency "metafun", ">= 0.2.0"
-  
+  s.add_dependency "sub-setter", ">= 0.0.2"
+
   s.add_development_dependency "rspec"
   s.add_development_dependency "zucker"
 

data/lib/fast.rb

@@ -1,4 +1,5 @@
 require "metafun/delegator"
+require "sub-setter"
 
 require "fast/fast"
 

data/lib/fast/dir.rb

@@ -2,7 +2,13 @@ require "sub-setter/fast/dir"  # This call should be automated in the sub-setter
 
 module Fast
   # Directory handling class
+  #
+  # Inherits from Array in order to be usable as a Array
+  # Includes the module Fast::FilesystemObject for common
+  # functionality with Fast::File
   class Dir < Array
+    include FilesystemObject
+  
     def initialize path = nil
       super()
       @path = normalize path if path
@@ -55,8 +61,20 @@ module Fast
       if args.length > 0
         return_me = nil
         args.each do |path|
-          raise ArgumentError, "Dir '#{path}' already exists" if Dir.new.exist? path
-          return_me = do_create path
+          unless path.is_a? Hash
+            raise ArgumentError, "Dir '#{path}' already exists" if Dir.new.exist? path
+            return_me = do_create path
+          else
+            if @path
+              subdir = Dir.new.create! "#{@path}"
+            else
+              subdir = Dir.new "."
+            end
+            path.each do |item_name, item_content|
+              subdir[item_name] = item_content
+            end
+            return subdir          
+          end
         end
         return return_me
       else
@@ -72,7 +90,19 @@ module Fast
       if args.length > 0
         return_me = nil
         args.each do |path|
-          return_me = do_create path
+          unless path.is_a? Hash
+            return_me = do_create path
+          else
+            if @path
+              subdir = Dir.new.create! "#{@path}"
+            else
+              subdir = Dir.new "."
+            end
+            path.each do |item_name, item_content|
+              subdir[item_name] = item_content
+            end
+            return subdir          
+          end
         end
         return return_me
       else
@@ -125,15 +155,7 @@ module Fast
     alias :destroy! :delete!
     alias :del!     :delete!
     alias :unlink!  :delete!
-    
-    # Checks for existence. True if the directory exists, false otherwise
-    def exist? path = nil
-      @path = normalize path if path
-      ::File.directory? @path
-    end
-    
-    alias :exists? :exist?
-   
+       
     # Returns true if all passed dirs exist, false otherwise
     def exist_all? *args
       unless args.empty?
@@ -172,32 +194,17 @@ module Fast
 
       return existing_ones
     end
+    
+    # This will be ported to a pattern exactly like SubSetter
+    def to
+      Patterns::Adapter::Fast::Dir.new self
+    end
   
     # Returns a String brief of the dir
     def to_s
       return "#{@path}"
     end
-    
-    # Sends self to a SubSetter for Fast::Dir
-    def filter
-      SubSetter::Fast::Dir.new self
-    end
-    
-    alias :by :filter
 
-    # Expands the path to absolute is it is relative
-    def expand path = nil
-      @path = normalize path if path
-      ::File.expand_path @path
-    end
-    
-    alias :absolute :expand
-        
-    # Returns the path to the dir, if defined
-    def path
-      @path if @path
-    end    
-    
     # Renames this dir into the target path, unless the target path 
     # points to an existing dir.
     def rename *args
@@ -297,6 +304,37 @@ module Fast
         end
       end
     end
+
+    # Checks the given dirs should be merged if any conflict would arise.
+    #
+    # Returns true if any file in the target directory has the same 
+    # path (ie: the same name and subdirectory structure) as other file
+    # in the source directory.
+    def conflicts_with? *args
+      if args.length > 1
+        current, target = *args
+        @path = normalize current
+        target = Dir.new target
+      else
+        target = Dir.new args.first
+      end
+      
+      files do |file|
+        target.files do |target_file|
+          return true if file == target_file
+        end
+      end
+      
+      dirs do |dir|
+        target.dirs do |target_dir|
+          if dir == target_dir
+            return true if Fast::Dir.new.conflicts_with? "#{@path}/#{dir}", "#{target.path}/#{target_dir}" 
+          end
+        end
+      end
+      
+      false
+    end
     
     private
       def do_delete path = nil
@@ -345,9 +383,9 @@ module Fast
         
         target_dir
       end
-      
-      def normalize path
-        "#{path}"
+
+      def do_exist? path
+        ::File.directory? path
       end
   end
 end

data/lib/fast/exceptions.rb

@@ -0,0 +1,3 @@
+module Fast
+  class PathNotSettedException < ArgumentError; end
+end

data/lib/fast/fast.rb

@@ -1,5 +1,8 @@
+require "fast/filesystemobject"
 require "fast/file"
 require "fast/dir"
+require "fast/exceptions"
+require "patterns/adapter/fast/dir"
 
 module Fast
   # Returns a Dir with the file list already called (if a path is provided)

data/lib/fast/file.rb

@@ -2,7 +2,12 @@ require "sub-setter/fast/file"  # This call should be automated in the sub-sette
 
 module Fast
   # File handling class.
+  #
+  # Inherits from String in order to be usable as a String
+  # Includes the module Fast::FilesystemObject for common
+  # functionality with Fast::Dir
   class File < String
+    include FilesystemObject
   
     # Initializes the file
     def initialize source = nil
@@ -112,19 +117,17 @@ module Fast
     alias :create! :touch
     
     # Returns the contents of the file, all at once
-    def read path = nil
+    def read path = nil, &block
       @path = normalize path if path
-      ::File.read @path
+      unless block
+        ::File.read @path
+      else
+        ::File.open @path, "r" do |the_file|
+          block.call the_file
+        end
+      end
     end
 
-    # Returns true if file exists, false otherwise
-    def exist? path = nil
-      @path = normalize path if path
-      do_check_existence @path
-    end
-    
-    alias :exists? :exist?
-    
     def exist_all? *args
       unless args.empty?
         return_me = true
@@ -157,21 +160,6 @@ module Fast
       end
       return_list
     end
-    
-    # Sends self to a SubSetter for Fast::File
-    def filter
-      SubSetter::Fast::File.new self
-    end
-    
-    alias :by :filter
-    
-    # Expands the path if it's a relative path
-    def expand path = nil
-      @path = normalize path if path
-      ::File.expand_path @path
-    end
-    
-    alias :absolute :expand
         
     # Renames the file (by Fast::File own means, it does not call 
     # the underlying OS). Fails if the new path is an existent file
@@ -206,12 +194,7 @@ module Fast
     end
     
     alias :move! :rename!
-    
-    # Returns the path to the current file
-    def path
-      @path if @path
-    end
-    
+        
     # Appends the contents of the target file into self and erase the target
     def merge *args
       if args.length > 1
@@ -263,11 +246,7 @@ module Fast
       do_copy target
     end
     
-    private
-      def normalize path
-        "#{path}"
-      end
-      
+    private      
       def do_copy target
         target.write read
         target
@@ -291,7 +270,7 @@ module Fast
         self
       end
       
-      def do_check_existence path
+      def do_exist? path
         ::File.exist?(path) && !::File.directory?(path)
       end