readme.md in vfs-0.4.0 vs readme.md in vfs-0.4.1
- old
+ new
@@ -1,112 +1,119 @@
-# Vfs - Virtual File System
+Virtual File System provides **clean, simple and unified API over different storage systems** (Local File System, AWS S3, SFTP, Hadoop DFS, LDAP, Document Oriented DBs, In-Memory, ...).
+It is possible to provide such unified API because although those storages have different API the core concept are almost the same.
-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 FS, SFTP, S3.
-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, ...).
+- small codebase, easy to extend and understand.
+- driver implementation should be simple, is should be easy to create new drivers.
-**Performance**:
+## Example:
-- 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.
+The script below runs on local file system, to see this script running on S3 and SFTP please take a look at the examples folder, there are also samples for S3 backup and deployment over SSH/SFTP.
-## Installation
+``` ruby
+require 'vfs'
-``` bash
-$ gem install vfs
-$ gem install vos
-```
+# Preparing temporary dir for sample and cleaning it before starting.
+sandbox = '/tmp/vfs_sandbox'.to_dir.destroy
-## Code samples:
+# Let's create simple Hello World project.
+project = sandbox['hello_world'] # Our Hello World project.
-``` ruby
-require 'vfs' # Virtual File System
-require 'vos' # Virtual Operating System
+project['readme.txt'].write 'My shiny App' # Writing readme file, note that parent dirs
+ # where created automatically.
-# Connections, let's deploy our 'cool_app' project from our local box to remote server
+# File operations.
+readme = project['readme.txt']
-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
+# Checking that it's all ok with our readme.
+p readme.name # => readme.txt
+p readme.path # => /.../readme.txt
+p readme.exist? # => true
+p readme.file? # => true
+p readme.dir? # => false
+p readme.size # => 12
+p readme.created_at # => 2011-09-09 13:20:43 +0400
+p readme.updated_at # => 2011-09-09 13:20:43 +0400
-deploy_dir = server['apps/cool_app']
-projects = me['projects']
+# Reading.
+p readme.read # => "My shiny App"
+readme.read{|chunk| p chunk} # => "My shiny App"
-# Working with dirs, copying dir from any source to any destination (local/remote/custom_storage_type)
+# Writing.
+readme.append "2 + 2 = 4"
+p readme.size # => 21
-projects['cool_app'].copy_to deploy_dir
+readme.write "My shiny App v2" # Writing new version of readme.
+p readme.read # => "My shiny App v2"
-# Working with files
+readme.write{|s| s.write "My shiny App v3"} # Writing another new version of readme.
+p readme.read # => "My shiny App v3"
-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
+# Copying & Moving.
+readme.copy_to project['docs/readme.txt'] # Copying to ./docs folder.
+p project['docs/readme.txt'].exist? # => true
+p readme.exist? # => true
-dbc.update do |content| # and add host info
- content + "\nhost: cool_app.com "
-end
+readme.move_to project['docs/readme.txt'] # Moving to ./docs folder.
+p project['docs/readme.txt'].exist? # => true
+p readme.exist? # => false
-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
+# Dir operations.
+project.file('Rakefile').create # Creating empty Rakefile.
-# Checks
+# Checking our project exists and not empty.
+p project.exist? # => true
+p project.empty? # => false
-``` ruby
-deploy_dir['config'].exist? # => true
-deploy_dir.dir('config').exist? # => true
-deploy_dir.file('config').exist? # => false
+# Listing dir content.
+p project.entries # => [/.../docs, .../Rakefile]
+p project.files # => [/.../Rakefile]
+p project.dirs # => [/.../docs]
+project.entries do |entry| # => ["docs", false]
+ p [entry.name, entry.file?] # => ["Rakefile", true]
+end
+p project.include?('Rakefile') # => true
-deploy_dir['config'].dir? # => true
-deploy_dir['config'].file? # => false
+# Copying & Moving, let's create another project by cloning our hello_world.
+project.copy_to sandbox['another_project']
+p sandbox['another_project'].entries # => [/.../docs, .../Rakefile]
+
+# Cleaning sandbox.
+sandbox.destroy
```
-# Navigation
+API is the same for all storage types (Local, S3, SFTP, ...). Also API are the same for transfers (copy_to, move_to, ...) between any storage types.
+So, for example backup from S3 looks exactly the same as if files are located on the local folder.
-``` ruby
-config = deploy_dir['config']
-config.parent # => </apps/cool_app>
-config['../..'] # => </>
-config['../..'].dir? # => true
+## Installation
-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
+``` bash
+$ gem install vfs
+
+# For S3 and SFTP support install also vos
+$ gem install vos
```
-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'
-```
+Vfs can be used toghether with the Virtual Operating System Tool, and while the Vfs covers all the I/O operations the Vos provides support for remote command execution.
+You can use this combination to fully control remote machines, for example - I'm using it to manage my production servers (setup, administration, deployment, migration, ...).
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].
+You can also take look at the actual configuration I'm using to control my 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.
+To easy my work: with local FS, remote FS, 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.
+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
\ No newline at end of file