Using Compass from Ruby (not shell)

Question

I am building a script in Ruby where I would like to compile a single SCSS file using Compass. I am trying to make this as simple as possible, and would like to avoid using a config.rb file. I just want to set a couple settings via straight Ruby and tell Compass to compile a single SCSS file into a CSS file.

I know that this has to be possible but I have not been able to find any decent documentation on how to do it. Any help would be appreciated.

Answer 1

You're right, there's not really any comprehensive documentation on how to use Compass from Ruby. This is unfortunate, but let's not let little details like documentation stop us!

A First Attempt

When I was looking to do the same thing, I just poked around the Compass source and was able put together this little Ruby script. At first glance it seems to do the trick:

require 'compass'
require 'sass/plugin'

compiler = Compass::Compiler.new(
    # Compass working directory
    '.',
    # Input directory
    'styles/scss',
    # Output directory
    'styles/css',
    # Compass options
    { :style => :compressed }
)

compiler.compile('test.scss', 'test.css')

But apparently Compass has a bunch of default configuration options that aren't automatically included when invoking the compiler constructor directly (of which the SASS load_path is one). This can lead to errors when trying to import Compass functions and mixins, such as:

error: File to import not found or unreadable: compass/css3

Compass <1.0.0 (a.k.a. "the old way")

Here's how to call the compiler without overriding those defaults:

require 'compass'

Compass.add_configuration(
    {
        :project_path => '.',
        :sass_path => 'styles/scss',
        :css_path => 'styles/css'
    },
    'custom' # A name for the configuration, can be anything you want
)
Compass.compiler.compile('test.scss', 'test.css')

However, as of Compass version 1.0.0, Compass.compiler has been deprecated in favor of Compass.sass_compiler, leading to...

Compass >=1.0.0 (a.k.a. "the new way")

With thanks to @philipp for finding how to use the new API, we can update this snippet again to work with Compass.sass_compiler:

require 'compass'
require 'compass/sass_compiler'

Compass.add_configuration(
    {
        :project_path => '.',
        :sass_path => 'styles/scss',
        :css_path => 'styles/css'
    },
    'custom' # A name for the configuration, can be anything you want
)

compiler = Compass.sass_compiler({
  :only_sass_files => [
    'styles/scss/test.scss'
  ]
})

compiler.compile!