ftpd 0.3.1 → 0.3.2

data/.yardopts

@@ -0,0 +1,6 @@
+-o doc-api
+--exclude '[~#]$'
+--readme README.md
+--files doc/*.md
+lib/**/*.rb
+examples/example.rb

data/Changelog.md

@@ -1,3 +1,9 @@
+### 0.3.2
+
+Enhancements
+
+* Improved driver and file-system documentation.
+
 ### 0.3.1
 
 API changes

data/README.md

@@ -5,6 +5,12 @@ explicit TLS, passive and active mode, and most of the commands
 specified in RFC 969.  It an be used as part of a test fixture or
 embedded in a program.
 
+## A note about this README
+
+This readme, and the other files, contains Yardoc markup, especially
+for links to the API docs.  You'll find a properly rendered version
+{http://rubydoc.info/gems/ftpd on rubydoc.info}
+
 ## HELLO WORLD
 
 This is examples/hello_world.rb, a bare minimum FTP server.  It allows
@@ -50,12 +56,15 @@ the authenticate method to decide who can log in.  Once someone is
 logged on, it calls the file_system method to obtain a file system
 driver for that user.
 
-There is no base class for a driver.  Any class with that signature
-will do.
+There is no base class for a driver.  Any object that quacks like a
+driver will do.  Here are the methods your driver needs:
+
+* {Example::Driver#authenticate authenticate}
+* {Example::Driver#file_system file_system}
 
 ## FILE SYSTEM
 
-The file system object that the driver supplies to Ftpd is Ftpds
+The file system object that the driver supplies to Ftpd is Ftpd's
 gateway to the logical file system.  Ftpd doesn't know or care whether
 it's serving files from disk, memory, or any other means.
 
@@ -66,7 +75,21 @@ not supported and causes a "502 Command not implemented" response to
 the client.
 
 The canonical and commented example of an Ftpd file system is
-Ftpd::DiskFileSystem.
+{Ftpd::DiskFileSystem}.  You can use it as a template for creating
+your own, and its comments are the official specification for an Ftpd
+file system.
+
+Here are the methods a file system may expose:
+
+* {Ftpd::DiskFileSystem::Accessors#accessible? accessible?}
+* {Ftpd::DiskFileSystem::Accessors#exists? exists?}
+* {Ftpd::DiskFileSystem::Accessors#directory? directory?}
+* {Ftpd::DiskFileSystem::Write#write write}
+* {Ftpd::DiskFileSystem::Mkdir#mkdir mkdir}
+* {Ftpd::DiskFileSystem::Rmdir#rmdir rmdir}
+* {Ftpd::DiskFileSystem::List#file_info file_info}
+* {Ftpd::DiskFileSystem::List#dir dir}
+* {Ftpd::DiskFileSystem::Rename#rename rename}
 
 ## DEBUGGING
 

data/VERSION

@@ -1 +1 @@
-0.3.1
+0.3.2

data/examples/example.rb

@@ -8,6 +8,9 @@ require 'ftpd'
 require 'optparse'
 
 module Example
+
+  # Command-line option parser
+
   class Arguments
 
     attr_reader :eplf
@@ -54,27 +57,31 @@ module Example
   # The FTP server requires and instance of a _driver_ which can
   # authenticate users and create a file system drivers for a given
   # user.  You can use this as a template for creating your own
-  # driver.  There's no need to use this class (or any other) as a
-  # base class.
+  # driver.
 
   class Driver
 
-    attr_reader :expected_user
-    attr_reader :expected_password
+    # Your driver's initialize method can be anything you need.  Ftpd
+    # does not create an instance of your driver.
 
-    def initialize(data_dir)
+    def initialize(user, password, data_dir)
+      @user = user
+      @password = password
       @data_dir = data_dir
-      @expected_user = ENV['LOGNAME']
-      @expected_password = ''
     end
 
-    # Return true if the user/password should be allowed to log in.
+    # Return true if the user should be allowed to log in.
+    # @param user [String]
+    # @param password [String]
+    # @return [Boolean]
 
     def authenticate(user, password)
-      user == @expected_user && password == @expected_password
+      user == @user && password == @password
     end
 
     # Return the file system to use for a user.
+    # @param user [String]
+    # @return A file system driver that quacks like {Ftpd::DiskFileSystem}
 
     def file_system(user)
       Ftpd::DiskFileSystem.new(@data_dir)
@@ -92,7 +99,7 @@ module Example
       @args = Arguments.new(argv)
       @data_dir = Ftpd::TempDir.make
       create_files
-      @driver = Driver.new(@data_dir)
+      @driver = Driver.new(user, password, @data_dir)
       @server = Ftpd::FtpServer.new(@driver)
       @server.interface = @args.interface
       @server.port = @args.port
@@ -131,8 +138,8 @@ module Example
     def display_connection_info
       puts "Interface: #{@server.interface}"
       puts "Port: #{@server.bound_port}"
-      puts "User: #{@driver.expected_user}"
-      puts "Pass: #{@driver.expected_password}"
+      puts "User: #{user}"
+      puts "Pass: #{password}"
       puts "TLS: #{@args.tls}"
       puts "Directory: #{@data_dir}"
       puts "URI: ftp://#{HOST}:#{@server.bound_port}"
@@ -158,6 +165,14 @@ module Example
       end
     end
 
+    def user
+      ENV['LOGNAME']
+    end
+
+    def password
+      ''
+    end
+
   end
 end
 

data/ftpd.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "ftpd"
-  s.version = "0.3.1"
+  s.version = "0.3.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Wayne Conrad"]
-  s.date = "2013-03-04"
+  s.date = "2013-03-05"
   s.description = "ftpd is a pure Ruby FTP server library.  It supports implicit and explicit TLS, passive and active mode, and most of the commands specified in RFC 969.  It an be used as part of a test fixture or embedded in a program."
   s.email = "wconrad@yagni.com"
   s.extra_rdoc_files = [
@@ -17,6 +17,7 @@ Gem::Specification.new do |s|
     "README.md"
   ]
   s.files = [
+    ".yardopts",
     "Changelog.md",
     "Gemfile",
     "Gemfile.lock",

data/lib/ftpd/disk_file_system.rb

@@ -38,6 +38,8 @@ module Ftpd
       # Return true if the path is accessible to the user.  This will be
       # called for put, get and directory lists, so the file or
       # directory named by the path may not exist.
+      # @param ftp_path [String] The virtual path
+      # @return [Boolean]
       #
       # Called for:
       # * STOR
@@ -55,6 +57,8 @@ module Ftpd
       end
 
       # Return true if the file or directory path exists.
+      # @param ftp_path [String] The virtual path
+      # @return [Boolean]
       #
       # Called for:
       # * STOR (with directory)
@@ -68,6 +72,8 @@ module Ftpd
       end
 
       # Return true if the path exists and is a directory.
+      # @param ftp_path [String] The virtual path
+      # @return [Boolean]
       #
       # Called for:
       # * CWD
@@ -89,6 +95,7 @@ module Ftpd
       include TranslateExceptions
 
       # Remove a file.
+      # @param ftp_path [String] The virtual path
       #
       # Called for:
       # * DELE
@@ -112,6 +119,7 @@ module Ftpd
       include TranslateExceptions
 
       # Read a file into memory.
+      # @param ftp_path [String] The virtual path
       #
       # Called for:
       # * RETR
@@ -135,6 +143,8 @@ module Ftpd
       include TranslateExceptions
 
       # Write a file to disk.
+      # @param ftp_path [String] The virtual path
+      # @contents [String] The file's contents
       #
       # Called for:
       # * STOR
@@ -161,6 +171,7 @@ module Ftpd
       include TranslateExceptions
 
       # Create a directory.
+      # @param ftp_path [String] The virtual path
       #
       # Called for:
       # * MKD
@@ -185,6 +196,7 @@ module Ftpd
       include TranslateExceptions
 
       # Remove a directory.
+      # @param ftp_path [String] The virtual path
       #
       # Called for:
       # * RMD
@@ -209,20 +221,20 @@ module Ftpd
       include TranslateExceptions
 
       # Get information about a single file or directory.
+      # @param ftp_path [String] The virtual path
+      # @return [FileInfo]
       #
       # Should follow symlinks (per
       # {http://cr.yp.to/ftp/list/eplf.html}, "lstat() is not a good
       # idea for FTP directory listings").
       #
-      # @return [FileInfo]
-      #
       # Called for:
       # * LIST
       #
       # If missing, then these commands are not supported.
 
-      def file_info(path)
-        stat = File.stat(expand_ftp_path(path))
+      def file_info(ftp_path)
+        stat = File.stat(expand_ftp_path(ftp_path))
         FileInfo.new(:ftype => stat.ftype,
                      :group => gid_name(stat.gid),
                      :identifier => identifier(stat),
@@ -230,20 +242,15 @@ module Ftpd
                      :mtime => stat.mtime,
                      :nlink => stat.nlink,
                      :owner => uid_name(stat.uid),
-                     :path => path,
+                     :path => ftp_path,
                      :size => stat.size)
       end
       translate_exceptions :file_info
 
       # Expand a path that may contain globs into a list of paths of
       # matching files and directories.
-      #
-      # * If the path matches no files, returns an empty list.
-      #
-      # * If the path has no glob and matches a directory, then the
-      #   list contains only that directory.
-      #
-      # * If the patch has a glob, it may return multiple entries.
+      # @param ftp_path [String] The virtual path
+      # @return [Array<String>]
       #
       # The paths returned are fully qualified, relative to the root
       # of the virtual file system.
@@ -269,8 +276,8 @@ module Ftpd
       #
       # If missing, then these commands are not supported.
 
-      def dir(path)
-        Dir[expand_ftp_path(path)].map do |path|
+      def dir(ftp_path)
+        Dir[expand_ftp_path(ftp_path)].map do |path|
           path.sub(/^#{@data_dir}/, '')
         end
       end

data/rake_tasks/yard.rake

@@ -1,4 +1,3 @@
 require 'yard'
 YARD::Rake::YardocTask.new do |t|
-  t.options += ['-o', 'doc-api']
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ftpd
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-04 00:00:00.000000000 Z
+date: 2013-03-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: memoizer
@@ -165,6 +165,7 @@ extra_rdoc_files:
 - LICENSE.md
 - README.md
 files:
+- .yardopts
 - Changelog.md
 - Gemfile
 - Gemfile.lock
@@ -300,7 +301,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1023046255
+      hash: 286911087
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: