Permalink
Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
230 lines (152 sloc) 5.19 KB
=========
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