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:
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
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.