nemuiDoc: libvfs-ruby

ruby をより魅力的にするために。

libvfs-ruby作業メモ

ダウンロード

リリース版はまだありません。

RAA に登録しました。

snapshot tarball のディレクトリを覗くと幾つかあります。

VFS for ruby - これは何か？

ファイルとディレクトリの抽象化を行う為のクラスです。大きな目的は目的は以下の２つ。

組み込み File, Dir クラスとは違うアプローチで OOP として使いやすく書きやすい物をめざす
パスとして URL を扱えるようにし、ネットワークやアーカイブなどを透過的にアクセス可能に

例えば以下のようなコードを書けるようになることが目標です。

  f = VFS::File.new("/var/tmp/moge")
  # インスタンスの作成時には何もしません。
  p f.ctime                # => Fri Nov 21 13:25:21 JST 2003
  p f.size                 # => 300
  f.mtime = 300
  f.uid = 1000
  f.oepn { |io|            # open すると IO が返る
   puts io.read(20)
  }
  f.open("w") { |io|
   io << "moge"
  }
  f.rename("/tmp/moge")   # 自分の参照するファイルも変更される
  f.unlink                # "/tmp/moge" が消える

  f = VFS::File.new("http://serv/path/to/file.html")
  p f.mtime  # Last-Modified ヘッダなどから Time クラスを生成して返す

現状について

インターフェースをまだ模索中です。後述する互換レイヤはほぼ動くようになりましたのでそちらを使ってみて下さい。

サポートしている URL/スキーム

file: ローカルファイル

スキームが指定されなかった場合はローカルファイルと見なされます。

以下のような形式のが使えます。

"./foo"(スキーム無しの相対URL)
"file:/dir/file"(スキーム付き絶対パス指定)
"c:\path\file"(Windowsスタイル)
"file:///path/to/file"(RFC準拠の完全なURL)
"file:///c%7c/path/file"(Windowスタイル)

http:

サーバが対応していれば、WebDAV 拡張が使えます。 PROPFIND などのプロトコルにより、VFS::File#mtime 等が正しく動きますし、書き込みを行うこともできます。ただし、現状ではロックはサポートしていません。

また現在、相手が WebDAV のプロトコルをサポートしていない場合は、ディレクトリの扱いにかなり制限があります。具体的には VFS::File#file? は常に true を、 VFS::File#direcotry? は常に false を返します。

（VirtualHost単位の）１つのサーバに対して１つのコネクションを持ちます。

https:

openssl ライブラリが必要です。後は http と同じです。

ftp:

(特になし)

zip:

rubyzip ライブラリが必要です。

恐らくまだバグがかなり残っています。また、rubyzip ライブラリ側に依存した制限が幾つかあります。例えば、open で帰ってくるIO は幾つかのメソッドが足りません。

URL は

  zip:(アーカイブパス)(アーカイブの中のパス)

の様に記述します。URL 中に ! を見つけると、そこまでを zip アーカイブのパスとみなします。

zip:/home/sugi/zip_whthout_ext!/dir_in_zip/bbb → /home/sugi/zip_whiout_exe という zip ファイル内の /dir_in_zip/bbb

また、アーカイブのパスそのままもう一度 VFS::File.new に渡されるので、ネストした URL を書くことも出来ます。例えば、

  zip:http://serv/dir/archcive.zip!dir_in_zip/memo.txt

は http(WebDAV)サーバ上のzipファイルの中のディレクトリの更に中の memo.txt を示します。

組み込みクラス互換レイヤ (VFS::CompatLayer)

URL を使ったネットワーク/アーカイブ透過だけを手軽に実現するための物です。

VFS::CompatLayer::File, VFS::CompatLayer::Dir, VFS::CompatLayer::Stat が用意されていて、それぞれ組み込みクラスと同じインターフェースを持ちます。

vfs.rb を require すると、組み込みクラスが互換レイヤで上書きされ、引数に URL が渡せるようになります。

これにより、既存のライブラリを変更無しでネットワーク透過にすることが出来ます。

現状の制限事項

VFS クラスを直接呼び出すより遅い
Dir#chdir は URL を取る事は出来ません
Dir#chroot は URL を取る事は出来ません

コード例

http://sugi.nemui.org/pub/ruby/vfs/ の 24時間以内に更新されたファイルを表示

  require 'vfs'
  dir = "http://sugi.nemui.org/pub/ruby/vfs/"
  p Dir.new(dir) { |d|
    d.each { |fname|
      if Time.now - File.mtime(dir + fname) < 24 * 60 * 60
        puts %["#{fname}" has been updated in 24 hours.]
      end
    }
  }

コード例（既存のライブラリを使う）

WebDAV サーバ上に Tempfile を作る（作ってもあんまり意味ありませんが……）。

  require 'vfs'
  require 'tempfile'

  Tempfile.new("tempfiletest", "http://davserv/dir/moge") { |temp|
    # いろいろ....
  }

HTTP サーバから再帰的にカレントディレクトリへダウンロード。

 require 'fileutils'
 require 'vfs'
 
 FileUtils.cp_r("http://sugi.nemui.org/pub/perl/", ".")

un.rb を使って FTP サーバにディレクトリを再帰アップロード。

  % ruby -r vfs -run cp -- -r ~/works/myweb ftp://user:pass@myserver/home/myid/public_html/

VFS クラスリファレンス

まだ模索中のため、大幅に変更される可能性があります。

組み込みクラスからの変更点サマリ

new は IO を返さない。
- IO が欲しいときは open を呼んで下さい
utime, chmod, lchmod, chown, lchown は self に結びつけられたファイルだけを変更し、ファイル名を引数に取りません。
- VFS::File.new("file_to_touch").utime(Time.now - 86400, Time.now)

VFS::File

クラスメソッド

new(path): path は文字列か URL クラスのインスタンスである必要があります。適切なスキームハンドラを検索し、そのインスタンスを生成して返します。

インスタンスメソッド

<< (*args): そのファイルに追記します。引数は to_s で文字列に変更されます。 obj.open("a") { |io| << args.tos_s; obj }; と同じです。 self を返します。
atime
atime=
basename
blksize
blockdev?
blocks
chardev?
chmod
chown
ctime
delete
dev
directory?
dirname
each
escape
executable?
executable_real?
exist?
exists?
extname
file?
foreach
ftype
gid
gid=
grpowned?
ino
join
kind_of?
lgid=
link
lstat
luid=
mode
mtime: mtime 示す Time オブジェクトを返します
mtime=(aTime): mtime を変更します
nlink: ファイルのハードリンク数を返します. 対応していない（スキームの）場合は nil を返します。
open (flag = "r") { |io| }: 対象ファイルをオープンし, IO を返します。ブロックを与えた場合は自動的に close されます
owned?
path: (この挙動は恐らく近い将来変更されます) 現在の操作対象のパス(URL)を文字列で返します。大抵 new に渡した物と同じ物が帰りますが、rename をおこなった場合は変更されていることに注意して下さい。
pipe?
rdev
rdev_major
rdev_minor
readable?
readable_real?
readlink
rename
scheme
setgid?
setuid?
size
size?
socket?
split
stat
sticky?
symlink
symlink?
to_dir
truncate
uid
uid=
unescape
unlink
uri
utime
writable?
writable_real?
zero?

VFS::Dir

現状では組み込み Dir と同じですが、 Dir クラスのインターフェースは大きく変更予定です。まだ直接使わないで下さい。

VFS::Path

yet.