onload

onload

A preprocessor system for Ruby.

Intro

Onload makes it possible to preprocess Ruby files before they are loaded into the interpreter. It works with plain 'ol Ruby code, within Rails, or wherever Zeitwerk is used.

What is preprocessing?

Preprocessing has been around for a long time in the C world. The idea is to be able to compile the code differently depending on operating system, architecture, etc. In interpreted languages, preprocessing is most useful for transpilation, i.e. converting code from one dialect to another. Maybe the most familiar example of this is translating TypeScript to JavaScript. The JavaScript interpreters inside web browsers and Node.js can't run TypeScript directly - it has to be converted into JavaScript first.

In the JavaScript ecosystem it's very common for your code to pass through a build step, but not so in Ruby. That's where onload comes in.

Why onload

Onload lets you transform Ruby code just before it's loaded into the Ruby interpreter. You give it a file extension and a callable object, and it does the rest. Onload is the transpilation system behind rux, a tool that let's you write HTML tags inside your view components (think if it like jsx for Ruby).

Usage

Let's write an (admittedly contrived) preprocessor that upcases literal strings in Ruby files. We'll use the file extension .up to indicate which files to process.

Preprocessors can be any Ruby object that responds to the #call method.

class UpcasePreprocessor
  def self.call(source)
    source.gsub(/(\"\w+\")/, '\1.upcase')
  end
end

Next we'll tell onload about our preprocessor.

Onload.register(".up", UpcasePreprocessor)

Finally, we'll load the necessary monkeypatches by "installing" onload into the interpreter. In Rails environments you can skip this step, as it is done for you via the included railtie.

Onload.install!

Now, the contents of any file with a .up file extension will be passed to UpcasePreprocessor.call. The return value will be written to a separate Ruby file and loaded instead of the original .up file.

Ignoring Processed Files

It can often be desirable to add processed/generated files to your .gitignore file. Onload comes with a mechanism that can do exactly that. Simply set the config option before running onload:

Onload.config.ignore_path = ".gitignore"

Now whenever files are processed, the generated file will be automatically updated.

Running Tests

Install Docker, then run ./script/run_appraisals to run Rails and plain Ruby tests for all supported versions.

Otherwise, use Appraisal to run tests for Rails or plain ruby:

• Plain ruby: bundle exec appraisal ruby rake spec:ruby
• Rails: bundle exec appraisal <version> rake spec:rails. Run bundle exec appraisal list to see the available versions. To run tests for Rails 7.0, try bundle exec appraisal rails-7.0 rake spec:rails
• Note that you must be running the correct version of Ruby specified in each gemfile.

License

Licensed under the MIT license. See LICENSE for details.

Authors

• Cameron C. Dutro: http://github.com/camertron