net-ftp-list 0.3

data/README.txt

@@ -0,0 +1,77 @@
+= Net::Ftp::List
+
+== DESCRIPTION
+
+Ruby lib to parse FTP LIST responses.
+
+According to the FTP RFC the LIST command "information on a file may vary widely from system to system, this
+information may be hard to use automatically in a program, but may be quite useful to a human user".
+Unfortunately the NLST command "intended to return information that can be used by a program to further process
+the files automatically" only returns the filename and no other information. If you want to know to know even
+simple things like 'is the NLST entry a directory or file' you are left with the choice of attempting to CWD to
+(and back from) each entry or parsing the LIST command. This extension is an attempt at parsing the LIST command
+and as such is subject to all the variability that results from such an undertaking, take responses with a grain
+of salt and expect failures.
+
+See the RFC for more guff on LIST and NLST: http://www.ietf.org/rfc/rfc0959.txt
+
+== TODO & PROBLEMS
+
+* I'm new to Ruby, I'm sure some exist :)
+* The factory and abstract base class for parsers are one and the same. OO geeks will cry.
+* More OS's and server types. Only servers that return Unix like LIST responses will work at the moment.
+* Calling <tt>if entry.file? or entry.dir?</tt> is hard work when you really mean <tt>unless entry.unknown?</tt>
+* I'm not sure about overwriting Net::FTP's +list+, +ls+ and +dir+. It's a base lib after all and people will be
+  expecting String. Perhaps I'd be better to <tt>class Parser < String</tt> for the abstract parser.
+* The block handling for +list+, +ls+ and +dir+ has a nasty +map+ that's essentially building up an unused Array.
+
+== SYNOPSIS
+
+By requiring Net::FTP::List instances are created by calling any of Net::FTP's <tt>list</tt>, <tt>ls</tt> or
+<tt>dir</tt> metods. The <tt>to_s</tt> method still returns the raw line so for the most part this should be
+transparent.
+
+  require 'net/ftp' # Not really required but I like to list dependencies sometimes.
+  require 'net/ftp/list'
+
+  ftp = Net::FTP.open('somehost.com', 'user', 'pass')
+  ftp.list('/some/path') do |entry|
+    # Ignore everything that's not a file (so symlinks, directories and devices etc.)
+    next unless entry.file?
+
+    # If entry isn't a kind_of Net::FTP::List::Unknown then there is a bug in Net::FTP::List if this isn't the
+    # same name as ftp.nlist('/some/path') would have returned.
+    puts entry.basename
+  end
+
+== CREDITS
+
+  * ASF, Commons. http://commons.apache.org/
+  * The good people at Stateless Systems who let me write Ruby and give it away.
+
+== LICENSE
+
+(The MIT License, go nuts)
+
+Copyright (c) 2007 Shane Hanna
+Stateless Systems
+http://statelesssystems.com
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,51 @@
+# -*- ruby -*-
+require 'rake'
+require 'rake/clean'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+
+NAME = 'net-ftp-list'
+VERS = '0.3'
+
+CLEAN.include ['**/*.log', '*.gem']
+CLOBBER.include ['**/*.log']
+
+spec = Gem::Specification.new do |s|
+  s.name             = NAME
+  s.version          = VERS
+  s.platform         = Gem::Platform::RUBY
+  s.has_rdoc         = true
+  s.extra_rdoc_files = ["README.txt"]
+  s.summary          = 'Parse FTP LIST command output.'
+  s.description      = s.summary
+  s.author           = 'Shane Hanna'
+  s.email            = 'shane@statelesssystems.com'
+  s.homepage         = 'http://statelesssystems.com'
+
+  s.files            = FileList['Rakefile', '**/*.{rb,txt}'].to_a
+  s.test_files       = FileList['tests/*.rb'].to_a
+end
+
+desc 'Default: Run unit tests.'
+task :default => :test
+
+Rake::GemPackageTask.new(spec) do |p|
+    p.need_tar = true
+    p.gem_spec = spec
+end
+
+desc 'Run the unit tests.'
+Rake::TestTask.new do |t|
+  t.verbose = true
+end
+
+desc 'Package and install as gem.'
+task :install do
+  sh %{rake package}
+  sh %{sudo gem install pkg/net-ftp-list-#{VERS}}
+end
+
+desc 'Uninstall the gem.'
+task :uninstall => [:clean] do
+  sh %{sudo gem uninstall #{NAME}}
+end

data/lib/net/ftp/list.rb

@@ -0,0 +1,67 @@
+require 'net/ftp'
+require 'net/ftp/list/parser'
+
+# The order here is important for the time being. Corse grained parsers should appear before specializations because
+# the whole thing is searched in reverse order.
+require 'net/ftp/list/unix'
+
+module Net #:nodoc:
+  class FTP #:nodoc:
+
+    alias_method :raw_list, :list
+    def list(*args, &block)
+      # TODO: Map in void context when you pass a block.
+      raw_list(*args).map do |raw|
+        entry = Net::FTP::List.parse(raw)
+        block ? yield(entry) : entry
+      end
+    end
+
+    # Parse FTP LIST responses.
+    #
+    # Simply require the library and each entry from Net::FTP +list+, +ls+ or +dir+ methods will
+    # be parsed by the LIST parse as best it can.
+    #
+    # == Creation
+    #
+    # By requiring Net::FTP::List instances are created by calling any of Net::FTP's +list+, +ls+ or
+    # +dir+ metods. The +to_s+ method still returns the raw line so for the most part this should be
+    # transparent.
+    #
+    #   require 'net/ftp' # Not really required but I like to list dependencies sometimes.
+    #   require 'net/ftp/list'
+    #
+    #   ftp = Net::FTP.open('somehost.com', 'user', 'pass')
+    #   ftp.list('/some/path') do |entry|
+    #     # Ignore everything that's not a file (so symlinks, directories and devices etc.)
+    #     next unless entry.file?
+    #
+    #     # If entry isn't a kind_of Net::FTP::List::Unknown then there is a bug in Net::FTP::List if this isn't the
+    #     # same name as ftp.nlist('/some/path') would have returned.
+    #     puts entry.basename
+    #   end
+    #
+    # == Exceptions
+    #
+    # None at this time. At worst you'll end up with an Net::FTP::List::Unknown instance which won't have any extra
+    # useful information. Methods like <tt>dir?</tt>, <tt>file?</tt> and <tt>symlink?</tt> will all return +false+.
+    module List
+      class << self
+
+        # Parse a raw FTP LIST line.
+        #
+        #   Net::FTP::List.parse(raw_list_string) # => Net::FTP::List::Parser instance.
+        def parse(raw)
+          Parser.parse(raw)
+        end
+
+        # Parse a raw FTP LIST line.
+        #
+        # An alias for +parse+.
+        alias_method :new, :parse
+
+      end
+    end
+
+  end
+end

data/lib/net/ftp/list/parser.rb

@@ -0,0 +1,103 @@
+module Net
+  class FTP
+    module List
+
+      # ParserError
+      #
+      # Raw entry couldn't be parsed for some reason.
+      #
+      # == TODO
+      #
+      # Get more specific with error messages.
+      class ParserError < RuntimeError; end
+
+      # Abstract FTP LIST parser.
+      #
+      # It really just defines and documents the interface.
+      #
+      # == Exceptions
+      #
+      # +ParserError+ -- Raw entry could not be parsed.
+      class Parser
+        @@parsers = []
+
+        # The raw list entry string.
+        attr_reader :raw
+
+        # The items basename (filename).
+        attr_reader :basename
+
+        # Looks like a directory, try CWD.
+        def dir?
+          !!self.dir
+        end
+
+        # Looks like a file, try RETR.
+        def file?
+          self.file
+        end
+
+        # Looks like a symbolic link.
+        def symlink?
+          !!self.symlink
+        end
+
+        # Parse a raw FTP LIST line.
+        #
+        # By default just takes and set the raw list entry.
+        #
+        #   Net::FTP::List.parse(raw_list_string) # => Net::FTP::List::Parser instance.
+        def initialize(raw)
+          self.raw = raw
+        end
+
+        # Stringify.
+        def to_s
+          raw
+        end
+        alias_method :raw, :to_s
+
+        class << self
+
+          # Acts as a factory.
+          #
+          # TODO: Having a class be both factory and abstract implementation seems a little nutty to me. If it ends up
+          # too confusing or gives anyone the shits I'll move it.
+          def inherited(klass)
+            @@parsers << klass
+          end
+
+          # Factory method.
+          #
+          # Attempt to find and parse a list item with the a parser.
+          def parse(raw)
+            @@parsers.reverse.each do |parser|
+              begin
+                return parser.new(raw)
+              rescue ParserError
+                next
+              end
+            end
+          end
+        end
+
+        protected
+          # Protected boolean.
+          attr_accessor :file, :dir, :symlink
+
+          # Protected raw list entry string.
+          attr_writer :raw
+
+          # Protected item basename (filename).
+          attr_writer :basename
+      end
+
+      # Unknown parser.
+      #
+      # If all other attempts to parse the entry fail this class will be returned. Only the +raw+ and +to_s+
+      # methods will return anything useful.
+      class Unknown < Parser
+      end
+    end
+  end
+end

data/lib/net/ftp/list/unix.rb

@@ -0,0 +1,56 @@
+require 'net/ftp/list/parser'
+
+module Net
+  class FTP
+    module List
+      
+      # Parse Unix like FTP LIST entries.
+      #
+      # == MATCHES
+      # 
+      #   drwxr-xr-x   4 steve    group       4096 Dec 10 20:23 etc
+      #   -rw-r--r--   1 root     other        531 Jan 29 03:26 README.txt
+      #
+      # == SYNOPSIS
+      #
+      #   entry = Net::FTP::List::Unix.new('drwxr-xr-x   4 steve    group       4096 Dec 10 20:23 etc')
+      #   entry.dir?     # => true
+      #   entry.basename # => 'etc'
+      class Unix < Parser
+
+        # Stolen straight from the ASF's commons Java FTP LIST parser library.
+        # http://svn.apache.org/repos/asf/commons/proper/net/trunk/src/java/org/apache/commons/net/ftp/
+        REGEXP = %r{
+          ([bcdlfmpSs-])
+          (((r|-)(w|-)([xsStTL-]))((r|-)(w|-)([xsStTL-]))((r|-)(w|-)([xsStTL-])))\+?\s+
+          (\d+)\s+
+          (\S+)\s+
+          (?:(\S+(?:\s\S+)*)\s+)?
+          (\d+)\s+
+          ((?:\d+[-/]\d+[-/]\d+)|(?:\S+\s+\S+))\s+
+          (\d+(?::\d+)?)\s+
+          (\S*)(\s*.*)
+        }x
+
+        # Parse a Unix like FTP LIST entries.
+        def initialize(raw)
+          super(raw)
+          match = REGEXP.match(raw.strip) or raise ParserError
+
+          case match[1]
+            when /d/    then self.dir = true
+            when /l/    then self.symlink = true
+            when /[f-]/ then self.file = true
+            when /[bc]/ then # Do nothing with devices for now.
+            else ParserError 'Unknown LIST entry type.'
+          end
+
+          # TODO: Permissions, users, groups, date/time.
+
+          self.basename = match[21].match(/^(.+)(?:\s+\->.+)?$/)[0].strip
+        end
+      end
+
+    end
+  end
+end

data/test/test_net_ftp_list.rb

@@ -0,0 +1,32 @@
+require 'test/unit'
+require 'net/ftp/list'
+
+class TestNetFTPList < Test::Unit::TestCase
+
+  def setup
+    @dir  = Net::FTP::List.new('drwxr-xr-x   4 user     group       4096 Dec 10 20:23 etc')
+    @file = Net::FTP::List.new('-rw-r--r--   1 root     other        531 Jan 29 03:26 README')
+  end
+
+  def test_parse_new
+    assert_instance_of Net::FTP::List::Unix, @dir, 'LIST unixish directory'
+    assert_instance_of Net::FTP::List::Unix, @file, 'LIST unixish file'
+  end
+
+  def test_rubbish_lines
+    assert_instance_of Net::FTP::List::Unknown, Net::FTP::List.new("++ bah! ++")
+  end
+
+  def test_ruby_unix_like_dir
+    assert_equal 'etc', @dir.basename
+    assert @dir.dir?
+    assert !@dir.file?
+  end
+
+  def test_ruby_unix_like_file
+    assert_equal 'README', @file.basename
+    assert @file.file?
+    assert !@file.dir?
+  end
+
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.4
+specification_version: 1
+name: net-ftp-list
+version: !ruby/object:Gem::Version 
+  version: "0.3"
+date: 2008-01-13 00:00:00 +11:00
+summary: Parse FTP LIST command output.
+require_paths: 
+- lib
+email: shane@statelesssystems.com
+homepage: http://statelesssystems.com
+rubyforge_project: 
+description: Parse FTP LIST command output.
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Shane Hanna
+files: 
+- Rakefile
+- lib/net/ftp/list/parser.rb
+- lib/net/ftp/list/unix.rb
+- lib/net/ftp/list.rb
+- test/test_net_ftp_list.rb
+- README.txt
+test_files: []
+
+rdoc_options: []
+
+extra_rdoc_files: 
+- README.txt
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+