Saturday, January 5, 2013


What is Namebox?

Namebox is a gem I've developed to create namespace boxes to protect the core classes' methods from changes, like Refinements. But, unlike Refinements, Namebox can protect your classes from changes made by external unrefined libraries.

Why Namebox instead of Refinements?

Well, there are a number of reasons for that:
  • Refinements are supposed to be included in Ruby 2.0, but they're complex (see discussions) and maybe they won't be included in that version yet. Namebox can be used now.
  • Personal implementations of Refinements (like mine) could work before Ruby 2.0, but only in programmer's new projects/libraries. You can't use your Refinements to refine a gem made by other people. And even after Ruby 2.0 you must wait to gems' authors to refine them. With Namebox you can protect your core classes from changes caused by existing gems and other external unrefined libraries.
  • Namebox doesn't work exactly as Refinements.
Refinements use modules with the keyword refine, and blocks/regions with the keyword using. There is lexical scope, but it will probably affect subclasses in other files, which is bug-prone. There are some discussions about using modules for Refinements; that new module's role could create confusion.

Namebox is a box where changes can ocurr in the initialize block. When you want use that changes, you open the box in a point of your code file, and close it later. Every method call (of changed methods of the protected classes) inside that region will invoke the code defined in the initialize block. Elsewhere that methods will play their original behavior (or new ones, defined after Namebox initialization). An open region is restricted to its file; it doesn't affect subclasses nor other files. There's no place to confusion and bad surprises.

Why "Namebox"?

It was like looking for a new domain name. The original name was "Namespace", but there was a gem with that name. I tried other names, looking for a short one, and the word "classbox" made me think about "namespace boxes" - that is what nameboxes are.

What are Namebox issues?

Performance. Needless to say, every piece of code takes some time to run. Namebox must check all methods of the protected classes once to detect changes. Moreover, the changed methods are redefined to check the namebox openness and decide which version of the method must be called. If that method is heavily called, it can impact performance. Effort was made to keep that redefined methods as clean and fast as possible. I believe that the speed changes will be imperceptible in most cases, but only everyday use will tell how much.

As mentioned above, Namebox will redefine the changed methods to a decisor method, which will sometimes be in the class or module being protected. If that method is redefined later (outside another Namebox definition), there will be no way to get the desisor method back.

There are some situations where Namebox won't work as expected. For example, if two (or more) nameboxes require the same file somewhere in the initialization block, and that file changes methods of the protected classes, only the first namebox will detect that changes (since require loads each file only once), and that changes won't be available to subsequent nameboxes - unless they're defined where the first is open. I tried to hack Kernel.require to avoid it, but it would impact performance and cause several collateral effects. I expect that kind of case will be rare and circumventable.

Versions. Ruby 1.8.7 and 1.9.1 have some issues regarding class methods. To make Namebox compatible with them, it's necessary to make a more complex code, which runs differently and it's more memory-consuming. Even so, when running over Ruby 1.8.7, the class methods can loose self when changed by extending modules in subclasses (self will be the class instead of subclass when namebox is closed). Namebox versions 0.1.8 and 0.l.9 are compatible with Ruby 1.8.7 and 1.9.1, but newer versions (0.2.0 and greater) are compatible only with Ruby 1.9.2 and later.

Why Public Domain?

I like freedom, but I like it so much that I don't like the limits of GPL/LGPL - they impose freedom in a way that I feel constrained. Public Domain is the most freedom-prone license I've ever heard of. With Public Domain, anyone can do anything with the code, including changing the license, use in private code, earn money, and even improve the code and publish it in a free form.

And the most expected question...

How to use Namebox?

The principle is simple:

# Create a namebox to protect String's methods
NB = do
  # hack String
  class String
    def to_hex

# String#to_hex is visible here:
puts 'ABC'.to_hex   #=> '414243'


# but not here:
puts 'ABC'.to_hex   #=> NoMethodError

Protecting core classes when requiring something:

# :core refers to all loaded modules (but not submodules)
NB = do
  require "sequel"

puts :abc & :def     #=> # a Sequel object


puts :abc & :def     #=> NoMethodError

There is a wrapper for require:

# :core refers to all loaded modules (but not submodules)
NB = Namebox.require "sequel", :core

puts :abc & :def     #=> # a Sequel object


puts :abc & :def     #=> NoMethodError

That examples are very silly. Besides you can open and close a namebox several times, you won't want to do that every time. A more practical use is to define methods to use later in your program, like in the Camelize example:

  class String
    def camelize
      dup.gsub(/_([a-z])/) { $1.upcase }

class Foo
  def camelize_string(str)
    str.camelize            # works because NB_CAMEL is open here

class Bar < Foo
  def change_string1(str)
    camelize_string(str)    # ok
  def change_string2(str)
    str.camelize            # NoMethodError: NB_CAMEL isn't open here

Mixing nameboxes:

# with this, you won't need to specify the
# protected modules in this file.
Namebox.default_modules = :core

NB_SEQUEL = Namebox.require "sequel"

  class Symbol
    def & x
      "#{self} and #{x}"

p :abc & :def     #=> abc and def

p :abc & :def     #=> Sequel object;
                  # included modules wins over
                  # superclass changes

NB_OBJECT.close   # you don't need to close the
                  # last opened namebox first

p :abc & :def     #=> Sequel object


p :abc & :def     #=> NoMethodError

You can use Namebox to hack Namebox itself (e.g., to define default_modules thru other files, as constants are global):

  def Namebox.default_modules
    [Symbol, String]

NB_SEQUEL = Namebox.require("sequel")
# would be the same as Namebox.require("sequel", Symbol, String) 


You can invoke the previous version of the method thru _old(...):

s = "abc"

puts s.length       #=> 3, any doubt?

NB = do
  class String
    def length
      _old + 1      #=> please, don't do that out of home

puts s.length       #=> 3 (namebox is closed here)

puts s.length       #=> 4


puts s.length       #=> 3

Current version (0.2.2, by 2013-01-27) is under tests, and can be considered a pre-release for 1.0.0. Please, came back later to check for that version! ;-)

No comments:

Post a Comment