extensions 0.4.0

data/ChangeLog

@@ -0,0 +1,190 @@
+2004-09-23  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* RELEASE: 0.4.0 ===================================================
+	* README: Updated with new release info, included sample code, and
+	  placed links near the beginning.
+	* etc/website/upload.sh: updated RDoc directory location.
+	* install-doc.rb: ditto, plus call 'rake rerdoc'.
+
+2004-07-19  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.3.9
+	* lib/extensions/ostruct.rb: Override OpenStruct#initialize to
+	  provide initialization via a block
+	* test/tc_ostruct.rb: test OpenStruct#initialize
+
+2004-07-19  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.3.8
+	* lib/extensions/string.rb: implemented String#join
+	* lib/extensions/object.rb: implemented Object#not_nil?, #non_nil?,
+	  and #define_method
+	* test/tc_{string,object}.rb: test above methods
+	* lib/extensions/_base.rb: made special case for implementing #initialize
+	* lib/extensions/_template.rb: removed some cruft
+
+2004-07-18  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.3.7
+	* Rakefile: improved gem spec and test target.
+
+2004-07-18  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.3.6
+	* lib/extensions/array.rb: implemented Array#select!
+	* lib/extensions/hash.rb: implemented Hash#select!
+	  - both methods suggested and implemented by Wayne Vucenic
+	* lib/extensions/all.rb: added array.rb and hash.rb to the require
+	  list (both being new files)
+	* test/tc{array,hash}.rb: added test cases for #select!
+	* Rakefile: added 'methods' task (list extensions methods)
+	* etc/list_methods.rb: removed (Rake handles this now)
+
+2004-07-18  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.3.5
+	* lib/extensions/io.rb: implemented IO.writelines, and improved
+	  IO.write's documentation.
+	* test/tc_io.rb: tested IO.writelines, and improved IO.write's
+	  test.
+
+2004-07-18  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.3.4
+	* .cvsignore: updated
+	* etc/release/.cvsignore: deleted
+	* etc/release: removed again
+	* Rakefile: added 'test' target
+
+2004-07-17  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.3.3
+	* test/TEST.rb: added
+	* etc/release: removed directory and contents (Rake handles packaging
+	  now)
+	* etc/gen-rdoc.rb: removed (Rake handles documentation now)
+	* etc/website/upload.sh: removed (Rake handles website upload now)
+
+2004-07-17  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.3.2
+	* lib/extensions/*.rb: moved unit tests to extensions/test/tc_*.rb.
+	* test/tc_*.rb: moved unit tests here from library files.
+	* Rakefile: first time in repository.
+
+2004-01-24  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.3.1
+	* lib/extensions/string.rb: more efficient algorithm for #expand_tabs;
+	  thanks to GGaramuno.
+
+2004-01-23  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* RELEASE: 0.3.0 ===================================================
+	* etc/gen-rdoc.sh: removed
+	* etc/gen-rdoc.rb: introduced
+	* install-doc.rb: use gen-rdoc.rb; removed extra 'rdoc' from target
+	  directory path
+	* README: updated information about the new release
+	* etc/checklist: added checklist for creating a new release
+
+2004-01-13  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.2.14
+	* lib/extensions/enumerable.rb: implemented Enumerable#partition_by
+	  -- idea and code by Jason Creighton.
+
+2004-01-13  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.2.13
+	* lib/extensions/numeric.rb: formatting options extended to include
+	  currency (:usd, :euro, and :percent); submitted by Austin Ziegler.
+	* lib/extensions/_base.rb: include project name in error messages.
+	* etc/gen-rdoc.sh: explicitly exclude CVS directories.
+
+2003-11-12  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.2.12
+	* lib/extensions/enumerable.rb: implemented Hash#build_hash as a
+	  workaround to a problem in Ruby that was fixed on 2003-10-24.  Also
+	  added extra documentation to this method.
+
+2003-10-27  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.2.11
+	* lib/extensions/string.rb: modified String#trim, so that
+	  str.trim('|') now does what str.trim('| ') used to do, and it
+	  handles blank lines properly.  WARNING: non-backwards-compatible.
+
+2003-10-27  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.2.10
+	* lib/extensions/string.rb: fixed String#leftmost indent (blank lines
+	  threw it off)
+
+2003-10-22  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.2.9
+	* lib/extensions/string.rb: implemented String#cmp to compare strings
+	* etc/checklist: couple more points
+
+2003-10-22  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.2.8
+	* lib/extensions/enumerable.rb: more unit tests
+
+2003-10-14  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.2.7
+	* lib/extensions/string.rb: implemented String#line(*args)
+	* lib/extensions/string.rb: removed test_leftmost_indent as it is a
+          protected method now
+
+2003-10-08  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.2.6
+	* install-doc.rb: reflects new location for etc/gen-rdoc.sh
+	* README.1st: simplified
+
+2003-10-08  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.2.5
+	* lib/extensions/object.rb: improved #pp_s documentation
+	* README.html: removed (it's just generated anyway)
+	* README.1st: introduced
+	* etc/doctools/*: moved to etc/
+	* etc/gen-rdoc.sh: no longer copy README.html to root directory
+	* etc/list-methods.rb: adapt library path to new location
+	* README: a bit of tidy-up, and reflect above changes, and some
+	  other recent changes
+
+2003-10-06  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* versions 0.2.4
+	* etc/website/index.html: added; redirects to rdoc/index.html
+	* etc/website/upload.sh: changed to upload index.html and rdoc
+	  directory
+	* etc/doctools/gen-rdoc.sh: only copy README.html to root directory
+	  if -c argument is given
+
+2003-10-06  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.2.3
+	* lib/extensions/object.rb: Added Object#pp_s to return a
+          pretty-printed string.
+
+2003-10-05  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.2.2
+	* lib/extensions/enumerable.rb: added Enumerable#mapf and #collectf
+
+2003-10-05  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* version 0.2.1
+	* lib/extensions/symbol.rb: added Symbol#to_proc
+	* lib/extensions/all.rb: include symbol.rb
+	* etc/checklist: added
+
+2003-10-04  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* RELEASE: 0.2.0 ===================================================

data/HISTORY

@@ -0,0 +1,59 @@
+This file describes the difference between releases, and documents that date
+those releases were made.  See ChangeLog for more information.
+
+2003-10-04, v0.2.0 (v0_2_0)
+
+  - string.rb completed with working functionality, two more methods, and full
+    unit tests.  New methods:
+       String#taballto
+       String#leftmost_indent
+       String#expand_tabs
+
+  - Numeric#format_s, adopted from Austin Ziegler's contribution to
+    FixNumFormat on the wiki, added.
+
+  - Fixed important typo in install-doc.rb.
+
+  - Removed most methods from io.rb as they look cluttered and I'm not exactly
+    sure what to do with them!  Only IO.write remains, which is the only
+    really important one.
+
+  - Generated RDoc goes to directory "rdoc" not "doc" now.  It is installed to
+    that directory, and uploaded to http://extensions.rubyforge.org/rdoc with
+    etc/doctools/website/upload.sh.
+
+  - General improvement in documentation.
+
+  - etc/release directory introduced for generating tarballs from CVS.
+
+
+2003-10-02, v0.1 (v0_1)
+
+  - 'rbxtm' returns the following
+
+       Class#autoinit
+       Enumerable#build_hash
+       Enumerable#collect_with_index
+       Enumerable#contains?
+       Enumerable#has?
+       Enumerable#includes?
+       Enumerable#map_with_index
+       IO::read_binary
+       IO::read_text
+       IO::write
+       IO::write_binary
+       IO::write_text
+       Integer#even?
+       Integer#odd?
+       Object#in?
+       Object#singleton_class
+       String#indent
+       String#outdent
+       String#tabto
+       String#trim
+
+  - Not all methods are thoroughly tested.  String and IO are the only ones
+    lacking, I think.
+
+  - Infrastructure: etc/website/*, etc/doctools/*, README all in good shape.
+    etc/release/* nonexistent.

data/README

@@ -0,0 +1,341 @@
+= Ruby Extensions Project README
+
+== Table of Contents
+
+1. Introduction
+2. Sample Code
+3. Links
+4. Current Version and Status
+5. Installation
+6. What's Included?
+7. Usage Information
+8. Technical Information
+9. Feedback
+10. Licence
+
+
+== Introduction
+
+This project contains several extensions to the Ruby standard classes.  Many are
+sourced from the Ruby Wiki (see links at end of document).
+
+Criteria for inclusion of a method are:
+- the method serves a general purpose
+- it is reasonably clear from the method name what its behaviour is
+- it would not generally be out of place in the language itself
+
+Apart from convenience, the benefit of this package is to provide a reference.
+You can use this package for your convenience, and deploy your code with a
+clear dependency on it, since anyone can download it.  That is better than
+releasing your package with a few ad hoc standard class modifications, and
+hoping that they don't conflict with any code your users have written.
+
+Long story short: it's useful that Ruby allows you to add methods to existing
+classes, even built-ins like String and Array.  Some people rightfully are
+uneasy about actually doing so, because of possible conflicts.  This project
+offers a standard set of extensions in order to mitigate that uneasiness by
+making them publicly available, and well documented.
+
+Thanks to the kind folk at InfoEther, Rich Kilmer and Tom Copeland, for
+providing the means and encouragement to host projects like these at
+http://www.rubyforge.org.
+
+
+== Sample Code
+
+  require 'extensions/all'
+
+  str = "Hello, \n\n  world!"
+  str.define_method(:heading) {
+    ('*** ' + self.join + ' ***').indent(3)
+  }
+  str.heading         # -> "   *** Hello, world! ***"
+
+  person = OpenStruct.new do |p|
+    p.name = 'John'
+    p.age  = 90
+  end
+
+  class Person
+    attr_reader :name, :age, :pension
+    autoinit :name, :age do |p|
+      @pension = 30000 + (@age - 65) * 350
+    end
+  end
+  john = Person.new('John', 90)
+  puts john.pension
+
+  HELP = %{
+    | Usage: ...
+    | Lorem ipsum...
+  }.trim('|')
+
+  NUMBERS  = (1..100)
+  squares  = NUMBERS.build_hash { |n| [n, n**2] }
+  squares[4]                     # -> 16
+  sq_roots = NUMBERS.build_hash { |n| [Math.sqrt(n), n] }
+  _4_mod_7 = NUMBERS.partition_by { |n| n % 7 }[4]
+
+  STR = "Hello, world!"
+  STR.starts_with? "Hello"       # -> true
+  STR.ends_with? "world"         # -> false
+  File.write("hello.txt", str)
+
+
+== Links
+
+Home Page::     http://extensions.rubyforge.org (includes API documentation)
+Project page::  http://www.rubyforge.org/projects/extensions
+Wiki Page::     http://www.rubygarden.org/ruby?StandardClassExtensions
+
+
+== Current Version and Status
+
+Version 0.4 was released on 2004-09-23 and can be installed as a gem,
+installed via the RPA, or downloaded from the project page.  Anybody is
+welcome to access the CVS and see changes as they happen.  As always,
+everything included is unit tested and well documented.
+
+Version 0.4 is a precursor to version 0.5 where yet more methods will be
+introduced.  It just makes sense to release what's currently available before
+committing to that effort.  The long-term goal of <tt>extensions</tt> is to
+become part of the <tt>addlib</tt> project.
+
+Several methods have been added since version 0.3.  <tt>ChangeLog</tt> has all
+the details, and the changes are highlighted below.
+
+Version 1.0 will (may?) occur when sufficient time has passed to make me
+confident there are no bugs in this, and after a few more minor versions are
+released with new methods.  Nobody has complained about bugs so far, and any
+bugs would be easy to fix, so I have no problem using this package in my own
+production code.
+
+The methods listed in this document will always reflect the most recent
+released version, but the online RDoc will reflect what's in the latest CVS.
+
+
+== Installation
+
+The easiest way to install <tt>extensions</tt> is via RubyGems or the RPA.
+
+  gem install -r extensions
+
+  rpa update
+  rpa install extensions
+
+=== Tarball installation
+
+The tarball version uses Minero Aoki's <tt>install.rb</tt>.  Run the
+following, with the last one as root if appropriate.
+
+  ruby install.rb config
+  ruby install.rb setup
+  ruby install.rb install
+
+This will install the <tt>extensions/*</tt> files somewhere you can load them,
+and +rbxtm+ in a +bin+ directory.  I've combined these commands into
+<tt>install.sh</tt> if you want to run that instead.
+
+=== Installing documentation
+
+<tt>extensions</tt> offers you the opportunity to install its RDoc-generated
+API documentation to your hard drive for ease of access.  Personally, I find
+it easier to hit the website all the time, but...  It only works if you have
+Rake installed.
+
+From the base directory, run (as root if that applies to you):
+
+  ruby install-doc.rb [location]
+
+If you don't provide a location, it will default to
+<tt>/usr/local/doc/ruby</tt>.  Well, that's on my platform; it will make an
+intelligent guess on yours.  This is not a tried and tested documentation
+installer; I wrote it just for this project, so please let me know if you're
+not happy with it for any reason.
+
+A side effect of installing the documentation is that it will be generated
+into the <tt>build/rdoc</tt> directory of the package.
+
+The "base directory" is the directory you unpacked from the tarball.  If you
+installed via RubyGems, you might try this:
+
+  gem unpack extensions
+  cd extensions-0.4.0
+  ruby install-doc.rb [location]
+  cd ..
+  rm -rf extensions-0.4.0
+
+<tt>gem unpack</tt> is like having access to the tarball without having to
+manually download it.
+
+
+== What's included?
+
+When you install this package, you can run the command +rbxtm+ ("Ruby
+Extension Methods") to get a list of the methods implemented by this project.
+At time of writing, this command gives (<tt>+</tt> indicates new method since
+0.3).
+
+ + Array#select!
+   Class#autoinit
+   Enumerable#build_hash
+   Enumerable#collect_with_index
+   Enumerable#collectf
+   Enumerable#contains?
+   Enumerable#has?
+   Enumerable#includes?
+   Enumerable#map_with_index
+   Enumerable#mapf
+   Enumerable#partition_by
+   Hash#select!
+   IO.write
+   IO.writelines
+   Integer#even?
+   Integer#odd?
+   Numeric#format_s
+ + Object#define_method
+   Object#in?
+ + Object#non_nil?
+ + Object#not_nil?
+   Object#pp_s
+   Object#singleton_class
+ + OpenStruct.new
+   String#cmp
+   String#ends_with?
+   String#expand_tabs
+   String#indent
+ + String#join
+   String#leftmost_indent
+   String#line
+   String#outdent
+   String#starts_with?
+   String#taballto
+   String#tabto
+   String#trim
+   Symbol#to_proc
+
+The files that you can load are:
+
+  extensions/all
+  extensions/class
+  extensions/enumerable
+  extensions/io
+  extensions/numeric
+  extensions/object
+  extensions/ostruct
+  extensions/string
+  extensions/symbol
+
+The RDoc documentation has all the details.  You can view this locally after
+running <tt>ruby install-doc.rb</tt>, or you can view it online.  See the
+links at the bottom of the page.
+
+
+== Usage Information
+
+Using this package is simple.  After installation, just include the following
+line in your Ruby program:
+
+  require 'extensions/all'
+
+Then you can use any of the methods listed above.  If you want to only use
+some of the methods, then load the file that names the class whose extensions
+you wish to use.  For example:
+
+  require 'extensions/string'
+
+  puts report.indent(3)
+
+If you install it via RubyGems, then you may need to do this in your code:
+
+  require 'rubygems'
+  require 'extensions/string'       # Or whatever you want to load.
+
+
+== Technical Information
+
+=== Special library files
+
+This package has a simple framework to ensure safety and some correctness.
+See the file <tt>_base.rb</tt> for more information.
+
+There is a template used for new files: <tt>_template.rb</tt>.  It will raise an error
+if you actually load it.
+
+=== Unit testing
+
+Unit tests are located in the <tt>test/</tt> directory, and are most easily
+run using Rake with <tt>rake test</tt>.
+
+=== How the package is organised
+
+Relative to the root directory of the package:
+bin/rbxtm::
+    Lists the methods implemented by all the extensions that are installed.
+    This file is installed in the +bin+ directory on the user's machine.
+build/::
+    A directory into which RDoc and packages are built.
+etc/checklist::
+    Contains a checklist for creating a new teeny version or a new minor
+    release.
+etc/website/index.html::
+    <tt>index.html</tt> for the website.
+etc/website/upload.sh::
+    Copies <tt>index.html</tt> and the entire +rdoc+ directory to the website.
+lib/extensions/*.rb::
+    The extensions libraries themselves.
+
+In the root directory:
+ChangeLog::
+    Records changes to the package (after v0.2).
+HISTORY::
+    Documents the main changes between minor versions (before v0.2).
+README::
+    Either the file you're reading, or the source file for the file you're
+    reading.
+README.1st::
+    Instructions for generating documentation (specifically README.html)
+Rakefile::
+    Encapsulates all sorts of project tasks: generate documentation, create a
+    tarball or gem for release, run unit tests, list the <tt>extensions</tt>
+    methods.  This replaces three special-purpose scripts and does a better
+    job to boot.  Thanks Jim!
+VERSION::
+    Current version of the package.  Used to decide on a directory for
+    installing documentation.
+install-doc.rb::
+    Generates +rdoc+ documentation and installs it in a directory like
+    <tt>/usr/local/doc/ruby/extensions-0.2.0/</tt>.
+install.rb::
+    Minero Aoki's installer.  Installs the package on your system.
+install.sh::
+    Front-end for <tt>install.rb</tt> so you don't have to run it three times.
+
+== Feedback
+
+If you would like to report a bug, suggest a method for inclusion, or make
+some other suggestion (documentation, package layout, etc.), then head to the
+project page (see links at end of document) and use the bug tracker or feature
+request.  If neither of these is appropriate, or if you want to discuss
+something before submitting, please contact me via email.
+
+
+== Licence
+
+Ruby/Extensions (http://extensions.rubyforge.org) is copyrighted free software
+created and maintained by Gavin Sinclair (mailto:gsinclair@soyabean.com.au)
+and released under the same license as Ruby.
+
+Standard disclaimer:
+  THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+  IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+  PURPOSE.
+
+
+------
+
+<i>
+$Id: README,v 1.12 2004/09/23 09:44:43 gsinclair Exp $
+vim: et sw=2 ts=2 sts=2 ai
+</i>