= Juicer
Official URL: http://github.com/cjohansen/juicer/tree/master
Christian Johansen (http://www.cjohansen.no)

== DESCRIPTION:

Juicer is a command line tool that helps you ship frontend code for production.

High level overview; Juicer can

* figure out which files depend on each other and merge them together, reducing
  the number of http requests per page view, thus improving performance
* use YUI Compressor to compress code, thus improving performance
* verify that your JavaScript is safe to minify/compress by running JsLint on it
* cycle asset hosts in CSS files
* add "cache busters" to URLs in CSS files
* recalculate relative URLs in CSS files, as well as convert them to absolute
  (or convert absolute URLs to relative URLs)

== FEATURES:

=== Merging and minifying

Juicer can read @import statements in CSS files and use them to combine all your
stylesheets into a single file. This file may be minified using the YUI
Compressor. Eventually it will support other minifying tools too.

Juicer can treat your JavaScript files much the same way too, parsing a comment
switch @depend, as this example shows:

  /**
   * My script file
   *
   * @depend jquery-1.2.0.js
   */
  var myNS = {
      myObject = {}
  };

Running <tt>juicer merge</tt> on this file will result in a minified file
<tt>filename.min.js</tt> containing the file jquery-1.2.0.js (located in the
same directory) and the code above.

You can use @import (CSS files) and @depend (JavaScript) recursively, effectively
creating a dependency chain for Juicer to climb and merge.

=== Paths

When merging CSS files, you may want to merge CSS files in different directories.
You may also want the resulting CSS file to end up in another directory as well.
Juicer automatically recalculates referenced URLs to reflect this change.

Absolute URLs are not changed by default, but if you provide juicer merge with
--document-root [DIR] and --relative-urls then absolute URLs are converted to
URLs relative to output directory. You can also use --absolute-urls to convert
all URLs to absolute ones.

=== Cache busters

Juicer supports so-called cache busters. A cache buster is a pattern in a path
whose only purpose is to "trick" browsers to redownload a file when it has
changed in cases where a far future expires header is used.

There are two types of cache busters; soft ones add a parameter to the URL, like
so: http://assets/images/1.png?cb1234567890, ie the letters "cb" (as in cache
buster) and then the timestamp of the files mtime.

Unfortunately, the popular web proxy Squid shipped for some time with a default
configuration which would not treat a URL as a "new" URL if the only thing changed
was the GET parameters. For this reason Juicer provides hard cache busters.

Hard cache busters result in URLs such as http://assets/images/1-cb1234567890.png,
ie URLs that require either renaming of files, or (more conveniently) a web
server configuration that will forward URLs to the right files anyway.

== PLANNED FEATURES:

Juicer 0.2.0 is the first usable release. Work will continue from here. Improving
documentation and APIs is one concern, but there are also new features planned:

* Support more minifiers, JsMin (Ruby port), Packer and possibly others
* Add support for CssTidy to compress CSS files
* juicer build, a command that can build several files in one swoop using a
  configuration file
* juicer doc, a command that produces documentation using YUI Doc or JsDoc

If you have any ideas, feature requests, want to contribute or whatever, fork
the project on github, or get in touch through christian (at) cjohansen.no.

== SYNOPSIS:

  juicer merge myfile.css
  -> Produces myfile.min.css which may contain several CSS files, minified

  juicer merge myfile.js
  -> Produces myfile.min.js, minified and combined

  juicer help

== REQUIREMENTS:

In order to use YUI Compressor and JsMin (requires Rhino) you need Java
installed and the java executable available on your path.

== INSTALL:

  $ gem install juicer
  $ juicer install yui_compressor
  $ juicer install jslint

You need Java installed and available on your PATH. During gem installation,
Juicer will download and install YUI Compressor, JsLint and Rhino for you.

== For developers

Before running tests you should run
  rake test:setup

which brings in third party libraries (ie, requires a working network connection)

== LICENSE:

(The MIT License)

Copyright (c) 2008-2009 Christian Johansen

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.