file-tail 0.1.2

data/CHANGES

@@ -0,0 +1,34 @@
+2004-09-30 * 0.1.2 * First Rubyforge release
+                   * Added Rakefile
+                   * Supports gem build now.
+2004-09-01 * 0.1.1 * Josh Endries <josh@endries.org> found a bug
+                     that caused File::Tail to malfunction on FreeBSD.
+                     Hotfix: Use a side effect of seek to clearerr the tailed
+                     file handle after EOFError has been raised.
+2004-04-13 * 0.1.0 * API documentation with rdoc.
+                   * return_if_eof attribute added.
+                   * Added array return mode for finite tail call without block
+                     given.
+                   * install.rb now uses ruby version site_dir.
+                   * Some code and directory structure cleanup.
+2002-08-02 * 0.0.2 * Heavy refactoring, more and smaller methods
+                     and expception handling
+                   * Added check for inode and device equality of files
+                     as suggested by
+                     James F.Hranicky <jfh@cise.ufl.edu> and
+                     Curt Sampson  <cjs@cynic.net> to cover remove
+                     rotation
+                   * If filesize shrinks suddenly, File::Tail assumes that
+                     copy and truncate rotation has happend: The file
+                     is reopened and every new line is handled.
+                   * NFS-Fix: Errno::ESTALE is caught.
+                   * wind added to skip the first n lines, as
+                     James F.Hranicky's suggested and changed
+                     name of last-method to rewind, because I liked
+                     his method names better than mine ;)
+                   * Renamed next to tail either.
+                   * The API has changed - but I think very few people
+                     care at the moment.
+                   * Lots of tests added.
+
+2002-07-30 * 0.0.1 * Initial Release

data/GPL

@@ -0,0 +1,340 @@
+		    GNU GENERAL PUBLIC LICENSE
+		       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+                       59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+			    Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+		    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+			    NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+		     END OF TERMS AND CONDITIONS
+
+	    How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Ty Coon>, 1 April 1989
+  Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Library General
+Public License instead of this License.

data/README.en

@@ -0,0 +1,30 @@
+Installation
+============
+
+Just type into the command line as root:
+
+# ruby install.rb
+
+Documentation
+=============
+
+To create the documentation of this module, type
+
+$ ruby make_doc.rb
+
+and the API documentation is generated by your rdoc command.
+
+In the examples direcotry is a small example of tail and
+pager program that use this module. You also may want look
+at the end of file/tail.rb for a little example.
+
+Author
+======
+
+Florian Frank <flori@ping.de>
+
+License
+=======
+
+GNU General Public License (GPL)
+

data/Rakefile

@@ -0,0 +1,72 @@
+# Rakefile for File::Tail  -*- ruby -*-
+
+require 'rake/gempackagetask'
+require 'rbconfig'
+
+include Config
+
+PKG_NAME = 'file-tail'
+PKG_VERSION = File.read('VERSION').chomp
+PKG_FILES = Dir.glob("**/*").delete_if { |item|
+    item.include?("CVS") or item.include?("pkg")
+}
+
+desc "Installing library"
+task :install  do
+    libdir = CONFIG["sitelibdir"]
+    dest = File.join(libdir, 'file')
+    install('lib/file/tail.rb', dest)
+end
+
+spec = Gem::Specification.new do |s|
+
+    #### Basic information.
+
+    s.name = 'file-tail'
+    s.version = PKG_VERSION
+    s.summary = "File::Tail for Ruby"
+    s.description = ""
+
+    #### Dependencies and requirements.
+
+    #s.add_dependency('log4r', '> 1.0.4')
+    #s.requirements << ""
+
+    s.files = PKG_FILES
+
+    #### C code extensions.
+
+    #s.extensions << "ext/extconf.rb"
+
+    #### Load-time details: library and application (you will need one or both).
+
+    s.require_path = 'lib'                         # Use these for libraries.
+    s.autorequire = 'file/tail'
+
+    #s.bindir = "bin"                               # Use these for applications.
+    #s.executables = ["bla.rb"]
+    #s.default_executable = "bla.rb"
+
+    #### Documentation and testing.
+
+    s.has_rdoc = true
+    #s.extra_rdoc_files = rd.rdoc_files.reject { |fn| fn =~ /\.rb$/ }.to_a
+    #s.rdoc_options <<
+    #  '--title' <<  'Rake -- Ruby Make' <<
+    #  '--main' << 'README' <<
+    #  '--line-numbers'
+    s.test_files << 'tests/test.rb'
+
+    #### Author and project details.
+
+    s.author = "Florian Frank"
+    s.email = "flori@ping.de"
+    s.homepage = "http://file-tail.rubyforge.org"
+    s.rubyforge_project = "file-tail"
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+    pkg.need_tar = true
+    pkg.package_files += PKG_FILES
+end
+    # vim: set et sw=4 ts=4:

data/VERSION

@@ -0,0 +1 @@
+0.1.2

data/examples/pager.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+# A poor man's pager... :)
+
+require 'file/tail'
+
+filename = ARGV.shift or fail "Usage: #$0 filename [height]"
+height = (ARGV.shift || 24).to_i - 1
+
+File::Tail::Logfile.open(filename, :break_if_eof => true) do |log|
+	begin
+		log.tail(height) { |line| puts line }
+		print "Press return key to continue!" ; gets
+		print ""
+		redo
+	rescue File::Tail::BreakException
+	end
+end
+	# vim: set noet sw=4 ts=4:

data/examples/tail.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+require 'file/tail'
+
+filename = ARGV.pop or fail "Usage: #$0 number filename"
+number = (ARGV.pop || 0).to_i.abs
+
+File::Tail::Logfile.open(filename) do |log|
+	log.rewind(number).tail { |line| puts line }
+end
+	# vim: set noet sw=4 ts=4:

data/install.rb

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+
+require 'rbconfig'
+require 'fileutils'
+include FileUtils::Verbose
+
+include Config
+
+cd 'lib' do
+  libdir = CONFIG["sitelibdir"]
+  subdir = 'file'
+  filename = 'tail.rb'
+
+  dest = File.join(libdir, subdir)
+  mkdir_p(dest)
+  file = File.join('file', filename)
+  install(file, dest)
+end
+  # vim: set et sw=2 ts=2:

data/lib/file/tail.rb

@@ -0,0 +1,380 @@
+# File::Tail is a module in the File class. A lightweight class interface for
+# logfiles can be seen under File::Tail::Logfile.
+class File
+
+  # The File::Tail module can be included in File objects and mixes in
+  # the wind, rewind and tail methods.
+  #
+  # === Usage
+  # Direct extension of File objects works like that:
+  #  File.open(filename) do |log|
+  #    log.extend(File::Tail)
+  #    log.interval = 10
+  #    log.rewind(10)
+  #    log.tail { |line| puts line }
+  # end
+  #
+  # It's also possible to mix File::Tail in your own File classes
+  # (see also File::Tail::Logfile):
+  #  class MyFile < File
+  #    include File::Tail
+  #  end
+  #  log = MyFile.new("myfile")
+  #  log.interval = 10
+  #  log.rewind(10)
+  #  log.tail { |line| print line }
+  #
+  # The wind/rewind method returns self, so it's possible to chain
+  # methods together like that:
+  #  log.rewind(10).tail { |line| puts line }
+  module Tail
+
+    # This is an easy to use Logfile class that includes
+    # the File::Tail module.
+    #
+    # === Usage
+    # The unix command "tail -10f filename" can be emulated like that:
+    #  File::Tail::Logfile.open(filename, :rewind => 10) do |log|
+    #    log.tail { |line| puts line }
+    #  end
+    #
+    # To skip the first 10 lines of the file do that:
+    #  File::Tail::Logfile.open(filename, :wind => 10) do |log|
+    #    log.tail { |line| puts line }
+    #  end
+    #
+    # The unix command "head -10 filename" can be emulated like that:
+    #  File::Tail::Logfile.open(filename, :return_if_eof => true) do |log|
+    #    log.tail(10) { |line| puts line }
+    #  end
+    class Logfile < File
+    
+      include File::Tail
+
+      # This method creates an File::Tail::Logfile object and
+      # yields to it if a block is given, otherwise it just
+      # returns it. The opts hash takes an option like
+      # <code>:rewind => 10</code> to rewind
+      # <code>:wind => 10</code> to wind
+      # the logfile for 10 lines at the start. The buffersize
+      # for rewind can be set with the
+      # <code>:bufsiz => 8192</code> option.
+      # Every attribute of File::Tail can be set with a
+      # <code>:attributename => value</code> option.
+      def Logfile.open(filename, opts = {}) # :yields: file
+        file = new filename
+        opts.each do |o, v|
+          writer = o.to_s + "=" 
+          file.__send__(writer, v) if file.respond_to? writer
+        end
+        if opts[:rewind]
+          (args = []) << opts[:rewind]
+          args << opt[:bufsiz] if opts[:bufsiz]
+          file.rewind(*args)
+        elsif opts[:wind]
+          file.wind(opts[:wind])
+        end
+        if block_given?
+          yield file
+          nil
+        else
+          file
+        end
+      end
+      
+    end
+
+    # This is the base class of all exceptions that are raised
+    # in File::Tail.
+    class TailException < Exception; end
+
+    # The DeletedException is raised if a file is
+    # deleted while tailing it.
+    class DeletedException < TailException; end
+
+    # The ReturnException is raised and caught
+    # internally to implement "tail -10" behaviour.
+    class ReturnException < TailException; end
+
+    # The BreakException is raised if the <code>break_if_eof</code>
+    # attribute is set to a true value and the end of tailed file
+    # is reached.
+    class BreakException < TailException; end
+
+    # The ReopenException is raised internally if File::Tail
+    # gets suspicious something unusual has happend to 
+    # the tailed file, e. g., it was rotated away. The exception
+    # is caught and an attempt to reopen it is made.
+    class ReopenException < TailException
+  
+      attr_reader :mode
+    
+      # Creates an ReopenException object. The mode defaults to
+      # <code>:bottom</code> which indicates that the file
+      # should be tailed beginning from the end. <code>:top</code>
+      # indicates, that it should be tailed from the beginning from the
+      # start.
+      def initialize(mode = :bottom)
+        super(self.class.name)
+        @mode = mode
+      end
+
+    end
+
+    # The maximum interval File::Tail sleeps, before it tries
+    # to take some action like reading the next few lines
+    # or reopening the file.
+    attr_accessor :max_interval
+
+    # The start value of the sleep interval. This value
+    # goes against <code>max_interval</code> if the tailed
+    # file is silent for a sufficient time.
+    attr_accessor :interval
+
+    # If this attribute is set to a true value, File::Tail persists
+    # on reopening a deleted file waiting <code>max_interval</code> seconds
+    # between the attempts. This is useful if logfiles are
+    # moved away while rotation occurs but are recreated at
+    # the same place after a while. It defaults to true.
+    attr_accessor :reopen_deleted
+
+    # If this attribute is set to a true value, File::Tail
+    # attempts to reopen it's tailed file after
+    # <code>suspicious_interval</code> seconds of silence.
+    attr_accessor :reopen_suspicious
+
+    # This attribute is the invterval in seconds before File::Tail
+    # gets suspicious that something has happend to it's tailed file
+    # and an attempt to reopen it is made.
+    #
+    # If the attribute <code>reopen_suspicious</code> is
+    # set to a non true value, suspicious_interval is
+    # meaningless. It defaults to 60 seconds.
+    attr_accessor :suspicious_interval
+
+    # If this attribute is set to a true value, File::Fail's tail method
+    # raises a BreakException if the end of the file is reached.
+    attr_accessor :break_if_eof
+
+    # If this attribute is set to a true value, File::Fail's tail method
+    # just returns if the end of the file is reached.
+    attr_accessor :return_if_eof
+
+    # Skip the first <code>n</code> lines of this file. The default is to
+    # don't skip any lines at all and start at the beginning of this file.
+    def wind(n = 0)
+      seek(0, File::SEEK_SET)
+      while n > 0 and not eof?
+        readline
+        n -= 1
+      end
+      self
+    end
+
+    # Rewind the last <code>n</code> lines of this file, starting
+    # from the end. The default is to start tailing directly from the
+    # end of the file.
+    #
+    # The additional argument <code>bufsiz</code> is
+    # used to determine the buffer size that is used to step through
+    # the file backwards. It defaults to the block size of the 
+    # filesystem this file belongs to or 8192 bytes if this cannot
+    # be determined.
+    def rewind(n = 0, bufsiz = nil)
+      if n <= 0
+        seek(0, File::SEEK_END)
+        return self
+      end
+      bufsiz ||= stat.blksize || 8192
+      size = stat.size
+      begin
+        if bufsiz < size
+          seek(0, File::SEEK_END)
+          while n > 0 and tell > 0 do
+            start = tell
+            seek(-bufsiz, File::SEEK_CUR)
+            buffer = read(bufsiz)
+            n -= buffer.count("\n")
+            seek(-bufsiz, File::SEEK_CUR)
+          end
+        else
+          seek(0, File::SEEK_SET)
+          buffer = read(size)
+          n -= buffer.count("\n")
+          seek(0, File::SEEK_SET)
+        end
+      rescue Errno::EINVAL
+        size = tell
+        retry
+      end
+      pos = -1
+      while n < 0  # forward if we are too far back
+        pos = buffer.index("\n", pos + 1)
+        n += 1
+      end
+      seek(pos + 1, File::SEEK_CUR)
+      self
+    end
+
+    # This method tails this file and yields to the given block for
+    # every new line that is read.
+    # If no block is given an array of those lines is
+    # returned instead. (In this case it's better to use a
+    # reasonable value for <code>n</code> or set the
+    # <code>return_if_eof</code> or <code>break_if_eof</code>
+    # attribute to a true value to stop the method call from blocking.)
+    #
+    # If the argument <code>n</code> is given, only the next <code>n</code>
+    # lines are read and the method call returns. Otherwise this method
+    # call doesn't return, but yields to block for every new line read from
+    # this file for ever.
+    def tail(n = nil, &block) # :yields: line
+      result = []
+      array_result = false
+      unless block
+        block = lambda { |line| result << line }
+        array_result = true
+      end
+      preset_atts unless @lines
+      loop do
+        begin
+          restat
+          read_line(n, &block)
+          redo
+        rescue ReopenException => e
+          reopen_file(e.mode)
+        rescue ReturnException
+          return array_result ? result : nil
+        end
+      end
+    end
+    
+    private
+
+    def read_line(n)
+      if n
+        n.times do
+          yield readline
+          @lines += 1
+          @no_read = 0
+          debug
+        end
+        raise ReturnException
+      else
+        yield readline
+        @lines += 1
+        @no_read = 0
+        debug
+      end
+    rescue EOFError
+      seek(0, File::SEEK_CUR)
+      raise ReopenException if @reopen_suspicious and
+        @no_read > @suspicious_interval
+      raise BreakException if @break_if_eof
+      raise ReturnException if @return_if_eof
+      sleep_interval
+    rescue Errno::ENOENT
+    rescue Errno::ESTALE
+      raise ReopenException
+    end
+
+    def preset_atts
+      @reopen_deleted       = true if @reopen_deleted.nil?
+      @reopen_suspicious    = true if @reopen_suspicious.nil?
+      @break_if_eof         = false if @break_if_eof.nil?
+      @return_if_eof        = false if @return_if_eof.nil?
+      @max_interval         ||= 10
+      @interval             ||= @max_interval
+      @suspicious_interval  ||= 60
+      @lines                = 0
+      @no_read              = 0
+    end
+
+    def restat
+      stat = File.stat(path)
+      if @stat
+        if stat.ino != @stat.ino or stat.dev != @stat.dev
+          @stat = nil
+          raise ReopenException.new(:top)
+        end
+        if stat.size < @stat.size
+          @stat = nil
+          raise ReopenException.new(:top)
+        end
+      else
+        @stat = stat
+      end
+    rescue Errno::ENOENT
+    rescue Errno::ESTALE
+      raise ReopenException
+    end
+
+    def sleep_interval
+      if @lines > 0
+        # estimate how much time we will spend on waiting for next line
+        @interval = (@interval.to_f / @lines)
+        @lines = 0
+      else
+        # exponential backoff if logfile is quiet
+        @interval *= 2
+      end
+      if @interval > @max_interval
+        # max. wait @max_interval
+        @interval = @max_interval
+      end
+      debug
+      sleep @interval
+      @no_read += @interval
+    end
+    
+    def reopen_file(mode)
+      $DEBUG and $stdout.print "Reopening '#{path}', mode = #{mode}.\n"
+      @no_read = 0
+      reopen(path)
+      if mode == :bottom
+        rewind
+      end
+    rescue Errno::ESTALE
+    rescue Errno::ENOENT
+      if @reopen_deleted    
+        sleep @max_interval
+        retry
+      else
+        raise DeletedException
+      end
+    end
+
+    def debug
+      $DEBUG or return
+      h = {
+        :lines    => @lines,
+        :interval => @interval,
+        :no_read  => @no_read,
+      }
+      $stderr.print h.inspect, "\n"
+    end
+    
+  end
+
+end
+
+if $0 == __FILE__
+  filename = ARGV.shift or fail "Usage: #$0 filename [number]"
+  number = (ARGV.shift || 0).to_i
+  File.open(filename) do |log|
+    log.extend(File::Tail)
+    # Some settings to make watching tail.rb with "ruby -d" fun
+    log.interval            = 1
+    log.max_interval        = 5
+    log.reopen_deleted      = true # is default
+    log.reopen_suspicious   = true # is default
+    log.suspicious_interval = 20
+    number >= 0 ? log.rewind(number, 8192) : log.wind(-number)
+    #loop do          # grab 5 lines at a time and return
+    #  log.tail(5) { |line| puts line }
+    #  print "Got 5!\n"
+    #end
+    log.tail { |line| puts line }
+  end
+end
+  # vim: set et sw=2 ts=2:

data/make_doc.rb

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+$outdir = 'doc/'
+puts "Creating documentation in '#$outdir'."
+system "rdoc -o #$outdir lib/file/tail.rb"
+  # vim: set et sw=2 ts=2:

data/tests/test.rb

@@ -0,0 +1,219 @@
+#!/usr/bin/env ruby
+
+require 'test/unit'
+require 'file/tail'
+require 'tempfile'
+require 'timeout'
+require 'thread'
+
+class TC_FileTail < Test::Unit::TestCase
+
+  include File::Tail
+
+  def setup
+    @out = Tempfile.new("test")
+    append(@out, 100)
+    @in = File.new(@out.path)
+    @in.extend(File::Tail)
+    @in.interval            = 0.4
+    @in.max_interval        = 0.8
+    @in.reopen_deleted      = true # is default
+    @in.reopen_suspicious   = true # is default
+    @in.suspicious_interval  = 60
+  end
+
+  def test_wind
+    [ 0, 1, 2, 10, 100 ].each do |lines|
+      @in.wind(lines)
+      assert_equal(100 - lines, count(@in))
+    end
+    @in.wind(101)
+    assert_equal(0, count(@in))
+  end
+
+  def test_rewind
+    [ 0, 1, 2, 10, 100 ].each do |lines|
+      @in.rewind(lines)
+      assert_equal(lines, count(@in))
+    end
+    @in.rewind(101)
+    assert_equal(100, count(@in))
+  end
+
+  def test_tail_with_block_without_n
+    timeout(10) do
+      lines = []
+      @in.rewind(1)
+      assert_raises(TimeoutError) do
+        timeout(1) { @in.tail { |l| lines << l } }
+      end
+      assert_equal(1, lines.size)
+      #
+      lines = []
+      @in.rewind(10)
+      assert_raises(TimeoutError) do
+        timeout(1) { @in.tail { |l| lines << l } }
+      end
+      assert_equal(10, lines.size)
+      #
+      lines = []
+      @in.rewind(100)
+      assert_raises(TimeoutError) do
+        timeout(1) { @in.tail { |l| lines << l } }
+      end
+      assert_equal(100, lines.size)
+      #
+      lines = []
+      @in.rewind(101)
+      assert_raises(TimeoutError) do
+        timeout(1) { @in.tail { |l| lines << l } }
+      end
+    end
+  end
+
+  def test_tail_with_block_with_n
+    timeout(10) do
+      @in.rewind(1)
+      lines = []
+      timeout(1) { @in.tail(0) { |l| lines << l } }
+      assert_equal(0, lines.size)
+      #
+      @in.rewind(1)
+      lines = []
+      timeout(1) { @in.tail(1) { |l| lines << l } }
+      assert_equal(1, lines.size)
+      #
+      @in.rewind(10)
+      lines = []
+      timeout(1) { @in.tail(10) { |l| lines << l } }
+      assert_equal(10, lines.size)
+      #
+      @in.rewind(100)
+      lines = []
+      @in.rewind(1)
+      assert_raises(TimeoutError) do
+        timeout(1) { @in.tail(2) { |l| lines << l } }
+      end
+      assert_equal(1, lines.size)
+      #
+    end
+  end
+
+  def test_tail_without_block_with_n
+    timeout(10) do
+      @in.rewind(1)
+      lines = []
+      timeout(1) { lines += @in.tail(0) }
+      assert_equal(0, lines.size)
+      #
+      @in.rewind(1)
+      lines = []
+      timeout(1) { lines += @in.tail(1) }
+      assert_equal(1, lines.size)
+      #
+      @in.rewind(10)
+      lines = []
+      timeout(1) { lines += @in.tail(10) }
+      assert_equal(10, lines.size)
+      #
+      @in.rewind(100)
+      lines = []
+      @in.rewind(1)
+      assert_raises(TimeoutError) do
+        timeout(1) { lines += @in.tail(2) }
+      end
+      assert_equal(0, lines.size)
+      #
+    end
+  end
+
+  def test_tail_withappend
+    @in.rewind
+    lines = []
+    threads = []
+    threads << Thread.new do
+      begin
+        timeout(1) { @in.tail { |l| lines << l } }
+      rescue TimeoutError
+      end
+    end
+    threads << Thread.new { append(@out, 10) }
+    threads.collect { |t| t.join }
+    assert_equal(10, lines.size)
+  end
+
+  def test_tail_truncated
+    @in.rewind
+    lines = []
+    threads = []
+    threads << appender = Thread.new do
+      Thread.stop
+      @out.close
+      File.truncate(@out.path, 0)
+      @out = File.new(@in.path, "a")
+      append(@out, 10)
+    end
+    threads << Thread.new do
+      begin
+        timeout(1) do
+          @in.tail do |l|
+            lines << l
+            lines.size == 100 and appender.wakeup
+          end
+        end
+      rescue TimeoutError
+      end
+    end
+    threads.collect { |t| t.wakeup and t.join }
+    assert_equal(10, lines.size)
+  end
+
+  def test_tail_remove
+    @in.rewind
+    lines = []
+    threads = []
+    threads << appender = Thread.new do
+      Thread.stop
+      @out.close
+      File.unlink(@in.path)
+      @out = File.new(@in.path, "w")
+      append(@out, 10)
+    end
+    threads << Thread.new do
+      begin
+        timeout(2) do
+          @in.tail do |l|
+            lines << l
+            lines.size == 100 and appender.wakeup
+          end
+        end
+      rescue TimeoutError
+      end
+    end
+    threads.collect { |t| t.wakeup and t.join }
+    assert_equal(10, lines.size)
+  end
+
+  def tear_down
+    @in.close
+    @out.close
+  end
+
+  private
+
+  def count(file)
+    n = 0
+    until file.eof?
+      file.readline
+      n += 1
+    end
+    return n
+  end
+
+  def append(file, n)
+    (1..n).each { |x| file << "#{x} #{"A" * 70}\n" }
+    file.flush
+  end
+
+end
+  # vim: set noet sw=2 ts=2:

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.1
+specification_version: 1
+name: file-tail
+version: !ruby/object:Gem::Version 
+  version: 0.1.2
+date: 2004-09-30
+summary: File::Tail for Ruby
+require_paths: 
+  - lib
+author: Florian Frank
+email: flori@ping.de
+homepage: http://file-tail.rubyforge.org
+rubyforge_project: file-tail
+description: ''
+autorequire: file/tail
+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
+files: 
+  - README.en
+  - CHANGES
+  - GPL
+  - examples
+  - Rakefile
+  - VERSION
+  - install.rb
+  - make_doc.rb
+  - lib
+  - tests
+  - examples/pager.rb
+  - examples/tail.rb
+  - lib/file
+  - lib/file/tail.rb
+  - tests/test.rb
+test_files: 
+  - tests/test.rb
+rdoc_options: []
+extra_rdoc_files: []
+executables: []
+extensions: []
+requirements: []
+dependencies: []