Declare methods as immutable, somewhat like Java's "final" but still allowing child classes to override.
|lib||Fixed bug in UNIQ constant. Tests work fine now|
|spec||Allow some immutable methods to be silent, while others still raise e…|
|CHANGELOG||Features for v0.3 was extended to v0.4|
|README||Why, it's a new year|
|Rakefile||Enable spec/spec.opts (optional)|
|immutable.gemspec||Put back my own repo info|
========= Immutable ========= :Author: Garry Dolley :Date: 09-21-2008 :Version: v0.2 The ``Immutable`` module provides a method (immutable_method) that let's one declare method(s) as immutable. That is, other code will not be able to open your class and replace your method with one of the same name. Child classes, however, can still override the method. So this is not like Java's "final" method modifier. One can argue that in OOP, if you want to reimplement or extend a method, a child class is the only place where you should be doing that anyway. Alpha ----- This code is very new and despite a pretty comprehensive spec, I'm sure there's cases where someone can figure out how to defeat this. So be it. :) This code has been tested on the following systems: * GNU/Linux (Ubuntu 8.04.1) with Ruby 1.8.6 * FreeBSD 7.0 with Ruby 1.8.6 * OpenBSD 4.3 with Ruby 1.8.6 * Mac OS X 10.5 with Ruby 1.8.6 Please see the Author section below and report any problems. Motivation ---------- My motivation for writing something that provides what some may call "evil" functionality of closed methods/classes came from my trials of trying to improve Rails loading time by reimplementing some ActiveSupport methods in C (Ruby extension). I absolutely needed my C versions of certain methods to be present, and not clobbered by ActiveSupport. So why didn't I just load my extension after ActiveSupport? Because by then it is too late. Rails is already loaded, along with slow running methods that get called over 10,000 times. Run the profiler and see for yourself: :: ./script/performance/profiler "require 'config/environment'" Releases -------- The latest code is in git:: * git://github.com/up_the_irons/immutable.git Requirements ------------ * None Optionals --------- * RubyGems 1.2.0 or higher Installation ------------ git ~~~ :: git clone git://github.com/up_the_irons/immutable.git Add the path where the repo was cloned on your filesystem to $RUBYLIB, or just use the full path when you "require". See "Getting Started" section. RubyGems ~~~~~~~~ :: gem sources -a http://gems.github.com sudo gem install up_the_irons-immutable Getting Started --------------- If you installed ``Immutable`` by cloning the git repo, put the path to the repo in $RUBYLIB, then put:: require 'lib/immutable' at the top of your programs. Alternatively, you can just require the full path to immutable.rb and not mess with $RUBYLIB. If you installed ``Immutable`` from RubyGems, put:: require 'rubygems' require 'immutable' at the top of your programs. Using ----- There's not much to say, so let me present a fully working example: :: require 'rubygems' require 'immutable' module Foo include Immutable def foo :foo end def bar :bar end immutable_method :foo, :bar end Now methods foo() and bar() cannot be overridden by other code opening Foo and reimplementing them. So the following: :: module Foo def foo :baz end end Will raise an error: :: Cannot override the immutable method: foo (Immutable::CannotOverrideMethod) There is one option to immutable_method() called :silent. If :silent is true, no exception will be raised. One can then do: :: module Foo include Immutable def foo :foo end immutable_method :foo, :silent => true end module Foo def foo :baz end end include Foo foo # => :foo foo() returns :foo, not :baz. It did not allow itself to be overriden. Using :silent can bring a great deal of confusion to other developers wondering why their method overrides aren't working. I would consider using :silent bad practice in all but very limited cases. Use with extreme caution. There is an alias for immutable_method() called immutable_methods() (plural). Use whichever style you prefer. To Do ----- Make method_added immutable, as well as immutable_method. Write tests to try to "defeat" an immutable method, see if we can prevent it. I finished my TODOs, cool. Author ------ Garry C. Dolley gdolley [at] NOSPAM- ucla.edu AIM: garry97531 IRC: up_the_irons in #git and #caboose on Freenode (and usually many other channels) Formatting ---------- This README is formatted in reStructredText [RST]_. It has the best correlation between what a document looks like as plain text vs. its formatted output (HTML, LaTeX, etc...). What I like best is, markup doesn't look like markup, even though it is. .. [RST] http://docutils.sourceforge.net/rst.html Copyright --------- Copyright (c) 2008,2009 Garry C. Dolley Immutable 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. Immutable 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 Immutable; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA