evilr

evilr subverts ruby’s runtime and lets you do things you shouldn’t do, such as changing the classes of objects. It’s inspired by evil.rb, but is a C extension as opposed to ruby code that uses DL.

Why?

It’s a good way to learn about how ruby works under the hood. It’s fun to push the boundries of ruby’s runtime, to see the difference between what’s just not allowed (i.e. changing classes) and what’s not possible for technical reasons (i.e. sharing singleton classes, instance variables, or method tables).

Installation

gem install evilr

What evil is currently available?

  • Object

    • class= : Change the class of an object

    • detach_singleton_class : Make current singleton class not a singleton, becoming the object’s main class.

    • dup_singleton_class : Make a copy of the current singleton class as a regular class.

    • evilr_debug_print : Print method ancestry chain to standard output.

    • extend_between : Given a module and a block, calls the block repeatedly with two arguments, each a module or class in the super chain. The first time the block returns true, the module argument given to the method is inserted between the given extended modules. Starts with the object’s singleton class and continues until the object’s class. If the argument given already extends the object, will remove it and reinsert it. If the argument is already included in the object’s class, raises an exception.

    • pop_singleton_class : Remove closest singleton class from the object

    • push_singleton_class : Add a new singleton class to the object in front of any existing singleton class.

    • remove_singleton_class : Remove an object’s singleton class and any modules that extend the object.

    • remove_singleton_classes : Remove all singleton classes and extended modules.

    • set_singleton_class : Take a given class and make it the object’s singleton class, replacing any existing singleton class.

    • swap : Completely swap two objects (singleton class, class, instance variables).

    • swap_singleton_class : Swap an object’s singleton class with another object’s singleton class.

    • swap_instance_variables: Swap two instance’s instance variables.

    • unextend : Remove a module that extends the object from the super chain.

    • unfreeze : Unfreeze the object.

  • Kernel

    • segfault : Dereferences NULL.

    • seppuku : kill -KILL’s the current process.

    • set_safe_level : Allows you to lower ruby’s $SAFE level.

  • Module

    • include_between : Given a module and a block, calls the block repeatedly with two arguments, each a module or class in the super chain. The first time the block returns true, the module argument given to the method is inserted between the given modules. Continues until the end of the super chain. If the argument given is already included, will remove it and reinsert it.

    • swap_method_tables : Swap the method tables of the receiver with the ones in the given module/class.

    • to_class : Return a copy of the module as a class.

    • uninclude : Remove the given module from the super chain, including going into superclasses if the receiver is a class.

  • Class

    • detach_singleton : If the class is a singleton class, remove its singleton status.

    • inherit : Allows inheriting from multiple classes, basically including them as modules.

    • singleton_class_instance : If the class is a singleton class, return the related instance.

    • superclass= : Modify the superclass of the receiver.

    • to_module : Return a copy of the class as a module.

  • UnboundMethod

    • force_bind : Bind the method to the object even if it is a different class than the method.

  • Proc

    • self : Get the default receiver of the proc’s methods

    • self= : Change the default receiver of the proc’s methods

  • Empty

    • A class with no superclass, only allocate, new, initialize, and superclass defined. More basic than even BasicObject.

Good bugs

If bugs are evil in good code, then surely bugs in evil code are good:

http://github.com/jeremyevans/evilr/issues

Contributing

I’m happy to accept more evil, hopefully without good bugs and with evil specs:

http://github.com/jeremyevans/evilr

evilr currently requires:

  • rake

  • rake-compiler

  • rspec

Running the specs

Even evil code should have specs! The default rake task runs the specs:

rake

Platforms Tested

Operating Systems/Platforms

  • OpenBSD (amd64, i386)

  • Linux (i386)

  • Windows XP (i386)

Compiler Versions

  • gcc 4.2.1

  • gcc 4.4.5

Ruby Versions

  • ruby 1.8.6

  • ruby 1.8.7

  • ruby 1.9.2

ruby 1.9.1 is not supported. It mostly works but has spec failures.

If your platform, compiler version, or ruby version is not listed above, please test and send me a report including:

  • Your operating system and platform (e.g. i386, x86_64/amd64)

  • Your compiler

  • Your ruby version

  • The output of rake

Author

Jeremy Evans <[email protected]>