Path: | README |
Last Update: | Wed Dec 08 13:39:09 UTC 2004 |
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:
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 in some situations, 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 this at www.rubyforge.org.
require 'extensions/all' require_relative 'data/samples' 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) arr = [1, 3, 5] arr.rand # -> 1, 3, or 5 arr.none? { |n| n.even? } # -> true arr.one? { |n| n > 4 } # -> true Class.by_name "Process::Sys" # -> Process::Sys Process::Sys.basename # -> "Sys"
Home Page: | extensions.rubyforge.org (includes API documentation) |
Project page: | www.rubyforge.org/projects/extensions |
Wiki Page: | www.rubygarden.org/ruby?StandardClassExtensions |
Version 0.6 was released on 2004-12-08 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.
Several methods have been added since version 0.5. ChangeLog 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 long-term goal of extensions is to become part of the addlib project.
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.
The easiest way to install extensions is via RubyGems or the RPA.
gem install -r extensions rpa update rpa install extensions
The tarball version uses Minero Aoki’s install.rb. 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 extensions/* files somewhere you can load them, and rbxtm in a bin directory. I’ve combined these commands into install.sh if you want to run that instead.
extensions 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 /usr/local/doc/ruby. 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 build/rdoc 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.5.0 ruby install-doc.rb [location] cd .. rm -rf extensions-0.5.0
gem unpack is like having access to the tarball without having to manually download it.
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 (+ indicates new method since 0.5).
+ Array#only + Array#rand Array#select! Binding#[] Binding#[]= Binding#defined? Binding#eval Binding#local_variables Binding.of_caller Class#autoinit Continuation.create Enumerable#build_hash Enumerable#collect_with_index Enumerable#collectf Enumerable#contains? Enumerable#has? Enumerable#includes? Enumerable#map_with_index Enumerable#mapf + Enumerable#none? + Enumerable#one? Enumerable#partition_by Hash#select! IO.write IO.writelines Integer#even? Integer#odd? + Kernel#require_relative + Module.by_name + Module#basename + Module#deep_const_get 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 (loads all the others) extensions/binding extensions/class extensions/continuation extensions/enumerable extensions/io extensions/kernel extensions/module extensions/numeric extensions/object extensions/ostruct extensions/string extensions/symbol
The RDoc documentation has all the details. You can view this locally after running ruby install-doc.rb, or you can view it online. See the links at the bottom of the page.
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.
This package has a simple framework to ensure safety and some correctness. See the file _base.rb for more information.
There is a template used for new files: _template.rb. It will raise an error if you actually load it.
Unit tests are located in the test/ directory, and are most easily run using Rake with rake test.
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: | index.html for the website. |
etc/website/upload.sh: | Copies index.html 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 extensions 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 /usr/local/doc/ruby/extensions-0.2.0/. |
install.rb: | Minero Aoki’s installer. Installs the package on your system. |
install.sh: | Front-end for install.rb so you don’t have to run it three times. |
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.
Ruby/Extensions (extensions.rubyforge.org) is copyrighted free software created and maintained by Gavin Sinclair (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.