hulk

Hulk: simple asset compression

Hulk makes it easy to compress CSS and JavaScript strings into groups called bundles. It works with raw strings, not file systems. Compression is done with YUI Compressor.

Why another asset compiler?

Hulk processes raw strings. This means you can load your assets from wherever you want: a database, filesystem, remote URL, unicorn colony, etc.

Why use raw strings instead of a file system? Flexibility. For example, a hosted CMS might allows users to edit CSS & JS through a web-interface and save it to a database.

Hulk is extremely simple -- it's basically just a light layer of sugar on top of YUI Compressor.If you want support for all kinds of other fandangled preprocessors or are simply reading files from a filesystem, you'll probably want to use one of these instead:

• Sprockets
• Jammit
• Crush

Overview

Bundles are the basic compilation unit of Hulk. A bundle is a collection of strings that compile into a single, named unit. Usually you'll just have two bundles: one for you CSS, and one for your JavaScripts.

Although you can work with bundles directly, it's much easier to do so indirectly through an instance of Hulk::Assets. This lets you build up your source strings and compile them all in one go.

Example Usage

First, create an instance of Hulk::Assets to hold your bundles:

assets = Hulk::Assets.new

Now add your CSS & JavaScript to the appropriate bundle:

assets.css[:all] << File.read('reset.css')
assets.css[:all] << File.read('screen.css')
assets.css[:all] << File.read('mobile.css')
assets.css[:all] << "body { background: #fff; }"

assets.js[:all] << File.read('jquery.js')
assets.js[:all] << File.read('backbone.js')
assets.js[:all] << File.read('application.js')

If you want to use something like Sass or CoffeeScript you can compile the sources yourself before adding to the bundle:

assets.css[:all] << Sass.compile(File.read('helpers.scss'))
assets.js[:all] << CoffeeScript.compile(File.read('app.coffee'))

And finally, compile everything:

assets.compile!

Assets are compiled in the same order they're appended.

Use either to_css or to_js to get the contents of the bundle:

assets.css[:all].to_css   # The compiled CSS
assets.js[:all].to_js     # The compiled JS

These methods will compile the bundle if it's not already compiled.

From here you can do whatever you want, like write the bundle to a file:

file = File.open("all.css", 'w')
file.write(assets.css[:base].to_css)
file.close()

Bundles have a digest based on the compiled contents:

assets.css[:all].digest # => "d41d8cd98f00b204e9800998ecf8427e"

They also have a filename helper method:

assets.css[:all].filename # => "d41d8cd98f00b204e9800998ecf8427e-all.css"

Once compiled, bundles are immutable:

assets.compile!
assets.css[:base] << "p { border: none; }" # Raises `Hulk::FrozenBundleError`

Bug Reports & Contributing

You can report bugs using the issue tracker right here on GitHub! You get extra mojo if you include a fix.

License

Hulk is distributed under a Simplified BSD License:

Copyright 2011 Carbonmade LLC. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of Carbonmade LLC.