io 0.0.1

data/lib/vfs/vfs.rb

@@ -0,0 +1,38 @@
+module Vfs
+  class << self
+    def default_driver
+      ::Vfs::Drivers::Local.new
+    end
+
+    def to_entry
+      '/'.to_entry
+    end
+
+    def to_file
+      to_entry.file
+    end
+
+    def to_dir
+      to_entry.dir
+    end
+
+    # def [] path
+    #   to_entry[path]
+    # end
+    # alias_method :/, :[]
+
+    %w(
+      entry dir file
+      entries dirs files
+      [] /
+      tmp
+    ).each do |m|
+      script = <<-RUBY
+        def #{m} *a, &b
+          to_entry.#{m} *a, &b
+        end
+      RUBY
+      eval script, binding, __FILE__, __LINE__
+    end
+  end
+end

data/readme.md

@@ -0,0 +1,119 @@
+# Vfs - Virtual File System
+
+Handy and simple abstraction over any storage that can represent concept of File and Directory (or at least part of it).
+The Vfs for File System is kinda the same as ActiveRecord is for Relational Databases.
+
+Currently, there are following implementations available:
+
+- local file system
+- remote file system (over ssh)
+
+## Goals
+
+- **handy, simple and clean** API.
+- same API for different storages (Local FS, SSH, Hadoop, or any other , ...).
+- should work **simultaneously with different storages**.
+- small codebase, easy to extend by others.
+- simple storage-driver implementation, easy add new storage types (Hadoop DFS, LDAP, Document Oriented DB, In-Memory, ...).
+
+**Performance**:
+
+- sometimes there's extra call to check if file or dir exist before overriding it
+- copy: right now it doesn't use FileUtils.cp_r, it walks on the directory tree and copy each entry individually, so it's probably a little slover.
+- right now :move and :rename implemented ASAP by copy & destroy, will be fixed as soon as I'll have time to do it.
+
+## Installation
+
+``` bash
+$ gem install vfs
+$ gem install vos
+```
+
+## Code samples:
+
+``` ruby
+require 'vfs'                                    # Virtual File System
+require 'vos'                                    # Virtual Operating System
+
+# Connections, let's deploy our 'cool_app' project from our local box to remote server
+
+server = Box.new('cool_app.com')             # it will use id_rsa, or You can add {user: 'me', password: 'secret'}
+me = '~'.to_dir                              # handy shortcut for local FS
+
+deploy_dir = server['apps/cool_app']
+projects = me['projects']
+
+# Working with dirs, copying dir from any source to any destination (local/remote/custom_storage_type)
+
+projects['cool_app'].copy_to deploy_dir
+
+# Working with files
+
+dbc = deploy_dir.file('config/database.yml') # <= the 'config' dir not exist yet
+dbc.write("user: root\npassword: secret")    # <= now the 'database.yml' and parent 'config' has been created
+dbc.read =~ /database/                       # => false, we forgot to add the database
+dbc.append("\ndatabase: mysql")              # let's do it
+
+dbc.update do |content|                      # and add host info
+  content + "\nhost: cool_app.com "
+end
+
+projects['cool_app/config/database.yml'].    # or just overwrite it with our local dev version
+  copy_to! dbc
+```
+
+There are also streaming support (read/write/append) with &block, please go to specs for details
+
+# Checks
+
+``` ruby
+deploy_dir['config'].exist?                  # => true
+deploy_dir.dir('config').exist?              # => true
+deploy_dir.file('config').exist?             # => false
+
+deploy_dir['config'].dir?                    # => true
+deploy_dir['config'].file?                   # => false
+```
+
+# Navigation
+
+``` ruby
+config = deploy_dir['config']
+config.parent                                # => </apps/cool_app>
+config['../..']                              # => </>
+config['../..'].dir?                         # => true
+
+deploy_dir.entries                           # => list of dirs and files, also support &block
+deploy_dir.files                             # => list of files, also support &block
+deploy_dir.dirs                              # => list of dirs, also support &block
+```
+
+For more please go to specs (create/update/move/copy/destroy/...)
+
+## Integration with [Vos][vos] (Virtual Operating System)
+
+```ruby
+server['apps/cool_app'].bash 'rails production'
+```
+
+For more details please go to [Vos][vos] project page.
+Or checkout configuration I use to control my production servers [My Cluster][my_cluster] in conjunction with small
+configuration tool [Cluster Management][cluster_management].
+
+# Why?
+
+To easy my work: with local FS, remote FS (cluster management, deployment automation), and some specific systems like Hadoop DFS.
+
+Because the API of standard File/Dir/FileUtils classes are just terrible. And there's the reason for it - the goal of thouse tools
+is to provide 1-to-1 clone of underlying OS API, instead of provididing handy tool.
+
+And if you want to use remote FS - things are getting even worse and more complicated (Net::SSH & Net::SFTP use a little
+different API than local FS, and you has to remember all thouse little quirks).
+
+## License
+
+Copyright (c) Alexey Petrushin http://petrush.in, released under the MIT license.
+
+[vos]: http://github.com/alexeypetrushin/vos
+[cluster_management]: http://github.com/alexeypetrushin/cluster_management
+[my_cluster]: http://github.com/alexeypetrushin/my_cluster

data/spec/container_spec.rb

@@ -0,0 +1,31 @@
+require 'spec_helper'
+
+describe 'Container' do
+  with_test_dir
+
+  it "should threat paths as UniversalEntry except it ends with '/'" do
+    test_dir.should_receive(:entry).with('tmp/a/b')
+    test_dir['tmp/a/b']
+
+    test_dir.should_receive(:dir).with('tmp/a/b')
+    test_dir['tmp/a/b/']
+  end
+
+  it '/' do
+    test_dir[:some_path].should == test_dir / :some_path
+    test_dir[:some_path][:another_path].should == test_dir / :some_path / :another_path
+  end
+
+  it "UniversalEntry should be wrapped inside of proxy, Dir and File should not" do
+    -> {test_dir.dir.proxy?}.should raise_error(NoMethodError)
+    -> {test_dir.file.proxy?}.should raise_error(NoMethodError)
+    test_dir.entry.proxy?.should be_true
+  end
+
+  it "sometimes it also should inexplicitly guess that path is a Dir instead of UniversalEntry (but still wrap it inside of Proxy)" do
+
+    dir = test_dir['tmp/a/..']
+    dir.proxy?.should be_true
+    dir.should be_a(Vfs::Dir)
+  end
+end

data/spec/dir_spec.rb

@@ -0,0 +1,249 @@
+require 'spec_helper'
+
+describe 'Dir' do
+  with_test_dir
+
+  before do
+    @path = test_dir['a/b/c']
+  end
+
+  describe 'existence' do
+    it "should check only dirs" do
+      @path.should_not exist
+      @path.file.create
+      @path.should be_file
+      @path.dir.should_not exist
+      @path.dir.create
+      @path.should be_dir
+      @path.dir.should exist
+    end
+  end
+
+  it "should not respond to read and write methods" do
+    -> {@path.dir.read}.should raise_error(NoMethodError)
+    -> {@path.dir.write}.should raise_error(NoMethodError)
+  end
+
+  describe 'create' do
+    it 'should be chainable' do
+      @path.dir.create.should == @path
+    end
+
+    it 'should create parent dirs if not exists' do
+      @path.parent.should_not exist
+      @path.dir.create
+      @path.should be_dir
+    end
+
+    it 'should silently exit if dir already exist' do
+      @path.dir.create
+      @path.dir.create
+    end
+
+    it 'should override existing file' do
+      @path.file.create
+      @path.should be_file
+      @path.dir.create
+      @path.should be_dir
+    end
+
+    it 'should not override existing dir with content' do
+      dir = @path.dir
+      dir.create
+      file = dir.file :file
+      file.create
+      file.should exist
+
+      dir.create
+      file.should exist
+    end
+  end
+
+  describe 'destroying' do
+    it "should destroy a file" do
+      @path.file.create
+      @path.dir.destroy
+      @path.entry.should_not exist
+    end
+
+    it "shouldn't raise if dir not exist" do
+      @path.dir.destroy
+    end
+
+    it 'should destroy recursivelly' do
+      dir = @path.dir
+      dir.create
+      dir.file(:file).write 'something'
+      dir.dir(:dir).create.tap do |dir|
+        dir.file(:file2).write 'something2'
+      end
+
+      dir.destroy
+      dir.should_not exist
+    end
+
+    it 'should be chainable' do
+      @path.dir.destroy.should == @path
+    end
+  end
+
+  describe 'entries, files, dirs' do
+    before do
+      @path.dir('dir').create
+      @path.dir('dir/another_dir').create
+      @path.file('file').create
+    end
+
+    it 'entries' do
+      -> {@path['non_existing'].entries}.should raise_error(Vfs::Error, /not exist/)
+      @path['non_existing'].entries(bang: false).should == []
+      @path.entries.to_set.should be_eql([@path.entry('dir'), @path.entry('file')].to_set)
+      list = []
+      @path.entries{|e| list << e}
+      list.to_set.should be_eql([@path.entry('dir'), @path.entry('file')].to_set)
+    end
+
+    it 'entries with type' do
+      @path.entries(type: true).to_set.should be_eql([@path.dir('dir'), @path.file('file')].to_set)
+    end
+
+    it "glob search support" do
+      @path.dir('dir_a').create
+      @path.file('file_a').create
+      @path.dir('dir_b').create
+      @path.entries('*_a').collect(&:name).sort.should == %w(dir_a file_a)
+    end
+
+    it 'should raise error if trying :entries on file' do
+      @path.file('some_file').create
+      -> {@path.dir('some_file').entries}.should raise_error(/File/)
+    end
+
+    it 'files' do
+      @path.files.should be_eql([@path.file('file')])
+    end
+
+    it 'dirs' do
+      @path.dirs.should be_eql([@path.dir('dir')])
+    end
+
+    it 'has? & include?' do
+      @path.include?('dir').should be_true
+      @path.include?('dir/another_dir').should be_true
+      @path.include?('file').should be_true
+      @path.include?('non_existing').should be_false
+    end
+
+    it 'empty?' do
+      @path.empty?.should be_false
+      @path.dir('empty_dir').create.empty?.should be_true
+    end
+  end
+
+  describe 'copying' do
+    before do
+      @from = @path.dir
+      @from.create
+      @from.file('file').write 'something'
+      @from.dir('dir').create.tap do |dir|
+        dir.file('file2').write 'something2'
+      end
+    end
+
+    it 'should not copy to itself' do
+      -> {@from.copy_to @from}.should raise_error(Vfs::Error, /itself/)
+    end
+
+    shared_examples_for 'copy_to behavior' do
+      it 'should copy to file and overwrite it' do
+        @from.copy_to @to.file
+        @to['file'].read.should == 'something'
+      end
+
+      it 'should override files' do
+        @from.copy_to @to
+
+        @from['dir/file2'].write 'another'
+        @from.copy_to @to
+        @to['dir/file2'].read.should == 'another'
+      end
+
+      it 'should copy to UniversalEntry (and overwrite)' do
+        @from.copy_to @to.entry
+
+        @from.copy_to @to.entry
+        @to['file'].read.should == 'something'
+      end
+
+      it "shouldn't delete existing content of directory" do
+        @to.dir.create
+        @to.file('existing_file').write 'existing_content'
+        @to.dir('existing_dir').create
+        @to.file('dir/existing_file2').write 'existing_content2'
+
+        @from.copy_to @to
+        # copied files
+        @to['file'].read.should == 'something'
+        @to['dir/file2'].read.should == 'something2'
+        # shouldn't delete already existing files
+        @to.file('existing_file').read.should == 'existing_content'
+        @to.dir('existing_dir').should exist
+        @to.file('dir/existing_file2').read.should == 'existing_content2'
+      end
+
+      it 'should be chainable' do
+        @from.copy_to(@to).should == @to
+      end
+
+      it "should override without deleting other files" do
+        @from.copy_to(@to).should == @to
+        @to.file('other_file').write 'other'
+
+        @from.copy_to(@to).should == @to
+        @to.file('other_file').read.should == 'other'
+      end
+
+      it "should raise error if try to copy file as dir" do
+        dir = @from.dir 'file'
+        dir.file?.should be_true
+        -> {dir.copy_to @to}.should raise_error(Vfs::Error)
+      end
+    end
+
+    describe 'general copy' do
+      it_should_behave_like 'copy_to behavior'
+
+      before do
+        # prevenging usage of :efficient_dir_copy
+        # Vfs::Dir.dont_use_efficient_dir_copy = true
+
+        @to = test_dir['to']
+      end
+      # after do
+      #   Vfs::Dir.dont_use_efficient_dir_copy = false
+      # end
+    end
+
+    # describe 'effective copy' do
+    #   it_should_behave_like 'copy_to behavior'
+    #
+    #   before do
+    #     @to = test_dir['to']
+    #   end
+    # end
+  end
+
+  describe 'moving' do
+    it 'move_to' do
+      from, to = @path.file('from'), @path.file('to')
+      from.should_receive(:copy_to).with(to)
+      from.should_receive(:destroy).with()
+      from.move_to to
+    end
+
+    it 'should be chainable' do
+      from, to = @path.dir('from').create, @path.dir('to')
+      from.move_to(to).should == to
+    end
+  end
+end

data/spec/entry_spec.rb

@@ -0,0 +1,42 @@
+require 'spec_helper'
+
+describe 'Entry' do
+  with_test_dir
+
+  before do
+    @path = test_dir['a/b/c']
+  end
+
+  it "name" do
+    @path.name.should == 'c'
+  end
+
+  it "string integration" do
+    '/'.to_entry.path.should == '/'
+    'a'.to_entry.path.should == "./a"
+  end
+
+  it 'tmp' do
+    tmp = test_dir.tmp
+    tmp.should be_dir
+    tmp.destroy
+
+    tmp = nil
+    test_dir.tmp do |path|
+      tmp = path
+      tmp.should be_dir
+    end
+    tmp.should_not exist
+  end
+
+  it 'should respond to local?' do
+    test_dir.should respond_to(:local?)
+  end
+
+  it 'created_at, updated_at, size' do
+    file = test_dir.file('file').write 'data'
+    file.created_at.class.should == Time
+    file.updated_at.class.should == Time
+    file.size.should == 4
+  end
+end