UFS - Universal File System¶ ↑

Or anything that is FileSystem Like… Including a Posix FileSystem, Amazon S3, & .tgz files or combinations of each one.

Notice¶ ↑

This project is under development. Your welcome to use it but it is NOT complete and the API is subject to change. The filesystem (UFS::FS) should be fairly stable.

Description¶ ↑

The goal of this gem is to make using your file system (or other data storage that can work like a file system) accessible in a friendly and universal way. This gem has been tested & documented from the ground up so the testing and documentation should be pretty comprehensive.

To begin with, I intend to support “the local FileSystem”, “Amazon S3”, or “compressed files (.tgz)” as FileSystems. Of course the compressed .tgz can reside on S3 or on your local file system interchangeably. I would love to further the adapter types to include options like ssh connections, webdev, git repositories, etc.

Mini-API¶ ↑

You should be able to use the standard read & write methods regardless of the adapter chosen. For example, you should be able to UFS.touch(‘path/to/location.txt’) when using the FS, S3 or TGZ adapters interchangeably. The adapters, however will have to be configured before use which may consist of at least a declaration of the default_adapter type as well as possibly providing authentication, location or other communication data.

Adapter standard methods should include:

• Common to all UFS objects

  • :exists? #=> true/false

  • :destroy! #=> true/false

  • :type # returns the class name

  • :proprieties # returns a hash of properties, with keys: (:name, :group, :permissions, etc)

  • :name # returns the file or directory name, ie: a path of “/tmp/deleteme.txt” will give you “deleteme.txt”

  • :move(new_path) # moves file or directory to new location and returns self

  • The following methods for setting, reading & writing: permissions, group & owner

    • :permissions, permissions?, & permissions!

    • :owner, :owner?, & :owner!

    • :group, :group?, & :group!

• file objects (An object that contains singular content, binary, text, etc.)

  • :touch(path_string) #=> file object (or equivalent)

  • :concat!(data) #=> appends or creates a file with the given content. Returns a file object (or equivalent)

  • :concat(data), :<<(data) #=> appends. Returns a file object (or equivalent) or UFS::WriteError if file doesn’t exist.

  • :writeln(data) #=> appends the file with a line of text, it is assured to be on its own line without extra newline characters

  • :read #=> content of file

  • :readln(number) #=> returns the line requested form the file or nil if the line doesn’t exist

  • :readln(range) #=> returns an array of lines as requested ie: file.readln(0..9)

  • :read_by_bytes(start, continue) #=> reads from the first byte requested through the number of continue bytes

  • Object should proxy the methods of the real object where possible… The ::UFS::FS::File object proxies to ::File

    • For example file.executable? should answer with the ::File.executable?(path). In this example, the path variable is taken from the file instance of ::UFS::FS::File

• directory objects (An object that contains file objects)

  • :mkdir(path_string) #=> directory object (or equivalent) or raise UFS::WriteError if the directory cannot be created

  • :mkdir!(path_string) #=> directory object (or equivalent) will attempt to make intermediate directories

  • :to_a #=> returns an array of the objects contained in the directory

  • :<<(file_object) #=> moves the given file_object to the directory

  • Object should proxy the methods of the real object where possible… The ::UFS::FS::File object proxies to ::File

    • For example UFS::FS::Dir.pwd will return the working directory through proxying to ::Dir.pwd().

Example 1¶ ↑

# Touching on directories & text files using the FileSystem adapter:
UFS.default_adapter = UFS::FS
dir = UFS.mkdir '/tmp/testing_deleteme'
f = UFS.touch "#{dir}/deleteme"
f.to_s                      #=> "/tmp/testing_deleteme/deleteme"
f << "Hello"
f.read                      #=> "Hello"
f << " world"
f.writeln 'another line'
f.writeln 'more stuff'
f.read                      #=> "Hello world\nanother line\nmore stuff\n"
f.readln 0                  #=> "Hello world"
f.readln 0..1               #=> ["Hello world", "another line"]
dir.destroy!                # lets see what happens if we delete the folder that contains the file...
f.read                      #=> UFS_Errors::ReadError: UFS_Errors::ReadError
f.exists?                   #=> false
dir.exists?                 #=> false

Installation¶ ↑

When things are finished up a bit I’ll be releasing this as a gem. For now you can check this project out in your projects ./lib folder then be sure to include ./lib/ufs/lib/ufs.rb. Assuming your lib is in your gem path you would do: require(‘ufs/lib/ufs’) but I’ll leave that one up to you to figure out. Enjoy and don’t be afraid to contact me if you have any questions.

Note on Patches/Pull Requests¶ ↑

• Fork the project.

• Make your feature addition or bug fix.

• Add tests for it. This is important so I don’t break it in a future version unintentionally.

• Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but

  bump version in a commit by itself I can ignore when I pull)

• Send me a pull request. Bonus points for topic branches.

Contributions¶ ↑

Bell          - None (SR: 0)
Peperoncini   - Mild (SR: 500)
Anaheim       - Low (SR: 5,000)
Jalapeño      - Medium (SR: 8,000)
Serrano       - Hot (SR: 50,000)
Habanero      - Exceptionally Hot (SR: 350,000
Red Savina    - Crazy Hot (SR: 580,000)
Naga Jolokia  - Hottest (SR: 1,041,427)
** SR = Scoville Rating

If you find that this project is a Jalapeño or better, please consider sending me a paypal donation…

Copyright¶ ↑

Copyright © 2009 “Joshaven Potter” <yourtech@gmail.com>. See LICENSE for details.