repertoire-assets 0.2.0

data/.gitignore

@@ -0,0 +1,5 @@
+.DS_Store
+*~
+pkg
+doc
+*.gem

data/FAQ

@@ -0,0 +1,90 @@
+Repertoire Assets FAQ
+=====================
+
+Q. If I use repertoire-assets for all of my javascript and css, none of my
+html templates have <script...> or <link...>!
+
+A. Yes, exactly.
+
+
+
+Q. My application is not loading javascript or css files.  There is nothing
+about them in the log.
+
+A. You have not installed the Rack middleware in your application's rackup
+file. The middleware is automatically loaded for Rails 3.0 when you add
+repertoire-assets to your Gemfile - but not for other frameworks.  Consult
+the README.
+
+
+
+Q. I'm getting a Could not process '//= require <foo/bar>' error.  But foo is 
+listed as a known library!
+
+A. Are you also getting a "Multiple libraries for <foo>" warning?  If so, the
+one it's using doesn't provide the <foo/bar> sublibrary.  You can fix this by
+eliminating the spurious version of <foo>.
+
+
+
+Q. My HTML looks like the following, but the middleware is not expanding
+javascript require statements.
+
+<script language='javascript'>
+//- require <jquery>
+//- require <widgets>
+</script>
+
+A. require and require instructions are only preprocessed in free-standing
+javascript files. Instead, use:
+
+public/javascripts/application.js:
+...
+//- require <jquery>
+//- require <widgets>
+
+
+
+Q. I have compress set to true, but in my deployed application
+digest.js or digest.css aren't YUI compressed.
+
+A. You are probably using an uncompressable Javascript syntax. Try compressing
+by hand on the command-line and YUI compressor will give you an error
+statement. This should also appear in the application's log.
+[ If using Rails 3, use rake 'assets:build' to compress the files by hand. ]
+
+
+
+Q. Why do gem assets appear mixed into the same url space?  Wouldn't it be
+better to namespace them by the gem's name?
+
+A. So that gems can specify in which directory in the host application they
+appear.  e.g., 'foo_gem-0.0.1/public/images/foo/bar.png' is served as though it
+were '<host app>/public/images/foo/bar.png'. 
+
+This way, existing image_tag and other helpers in Rails can be used 
+with assets pulled from gems.
+
+
+
+Q. I want to bundle different sets of javascript and css for different pages,
+or different browsers.
+
+A. This was considered, but isn't implemented.  Issue a feature request.
+
+
+
+Q. Repertoire assets seems like sprockets or juicer.  How is it different?
+
+A. Only Repertoire assets addresses distributing javascript and css via
+rubygems. Its syntax is borrowed from sprockets, but it has better css support
+than sprockets, and better provisions for debugging than either since you can
+develop on unbundled source files.
+
+
+
+Q. Can I use repertoire-assets together with merb-assets?
+
+A. Yes.  It replaces merb-asset's bundling and javascript/stylesheet helpers,
+but the remaining helpers can be used with assets from either the main app or
+assets in gems.

data/INSTALL

@@ -0,0 +1,35 @@
+Repertoire Assets
+=================
+
+
+(1) Make sure your application loads the middleware.  For Rails 3.0,
+    including repertoire-assets in your Gemfile does this automatically.
+    
+	For Merb and others, you will need to alter your rackup file.  The
+	middleware takes two optional arguments: a configuration hash and
+	the system logger.
+
+      <app>/config/rack.rb (Mongrel)
+      <app>/config.ru      (Passenger) 
+  
+*        require 'repertoire-assets'
+*        use Repertoire::Assets::Processor, Merb::Config, Merb.logger
+    
+         run Merb::Rack::Application.new
+
+
+(2) Turn on precaching and compression in your production environment,
+    so gem assets are served by your web server. e.g. for Rails:
+  
+    <app>/config/environments/production.rb:
+  
+*        config.repertoire_assets.compress = true
+
+    Or in Merb:
+  
+    <app>/config/environments/production.rb:
+
+*        c[:compress] = true
+
+    For other options that can be used in the configuration hash, see the
+    documentation for Repertoire::Assets::Processor.

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2009-2010 MIT Hyperstudio
+
+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.

data/README

@@ -0,0 +1,234 @@
+Repertoire Assets 
+=================
+
+Repertoire Assets is software for developing and distributing Javascript and
+CSS components for re-use in ruby web projects. It helps you manage large
+javascript codebases by dividing code among many files, and allows you to
+publish your javascript libraries (and their css and images) via ruby gems.
+You can then require them in other javascript web applications, and the asset
+software will manage any dependencies among the libraries so that you can
+focus on writing your own code.
+
+While you're developing, the Repertoire middleware ensures that any javascript
+and css you've required appear seamlessly in your own application's url space--
+even though they're loaded from elsewhere. You can step through javascript
+code file by file, just as it appears in your application and gems. When a
+javascript source file changes, it is reloaded automatically and its
+dependencies re-analyzed.
+
+Finally, when you have packaged your app for production use, the asset
+software bundles and compresses javascripts and stylesheets, and copies any
+associated binary assets into your application's public directory. This way,
+all the assets will be served directly by your web server, only one compressed
+javascript and one css file are downloaded to the client. This yields a much
+more responsive user experience.
+
+If you want to distribute your javascript component for use in non-ruby frame-
+works, repertoire assets can also be used to build and bundle the files.  This
+gives you the flexibility of developing and deploying components easily for use
+within ruby frameworks, but also distributing your code to a wider audience.
+
+
+
+*Architecture*
+
+The software consists of two components:
+
+(1) A preprocessor that assembles javascript based on dependencies in your
+code, much like C's #include directive or ruby's "require" method. For
+example, you could require the "shapes" javascript library from a ruby gem by
+including '//= require <shapes>' your javascript source. The preprocessor will
+find the library and load it and its depedencies into your web page before
+your own code, in the proper order. If a given code library has already been
+sourced, it is not loaded again.
+
+This is accomplished by compiling an ordered manifest of all the javascript
+files required by your code, and then inserting the appropriate <script> and
+<link> tags into your pages' html. Because it uses a rack filter, the system
+is largely transparent to your application. Whether it's written in Rails,
+Merb, Sinatra, or another ruby web framework, the javascript and css will
+still work.
+
+
+(2) A pair of rack filters: one that intercepts http requests for assets in
+the manifest and serves them directly, and another that inserts the manifest
+into html pages right before they are served. In a production environment, the
+filters collect all of your application's required assets, compress those they
+can, and cache them in your application's public asset directory.
+
+
+
+*Preparing your application*
+
+You can use javascript components packaged with Repertoire Assets in any ruby
+web application based on Rack (this includes Rails, Merb, Sinatra and others).
+
+The javascript gem libraries can either be bundled with your application, or
+reside in the system rubygems repository. Likewise, the repertoire-assets gem
+may be in either place.
+
+For Rails 3.0, no configuration is necessary for development use.  Production
+environments require a single line of configuration.  See the INSTALL file
+for details.
+
+
+
+*Importing Javascript Libraries and Files*
+
+Repertoire-assets works by scanning a set of javascript source files in your
+application on startup and locating any required libraries (and their
+dependents) on the ruby load path. In development mode, the files will be
+re-scanned whenever a dependency is modified.
+
+Files are sourced in the following order:
+
+  <app>/public/javascripts/application.js
+  <app>/public/javascripts/*.js
+
+In these files, you can use preprocessor directives similar to C's:
+
+  //= require <shapes>                         /* search for a library shapes.js in gems load path */
+  //= require "drawing/scene"                  /* load ./drawing/scene.js relative to the current file */
+  //= require "../stylesheets/red-theme.css"   /* load css relative to the current file */
+
+The relevant <script> and <link> tags for any file you 'require' are added to
+your application's outgoing html automatically. Any dependencies are added
+in logical order.
+
+
+
+*Structuring Your Application's Javascript*
+
+It's best to establish a layout similar to most ruby or C code, where files
+require any dependencies at their head and a single application file starts
+everything off.
+
+For example, a paint application might look like:
+
+  <app>/public/javascripts/application.js:
+    //= require "drawing/scene"
+    //= require "accounts/user"
+    ...
+  <app>/public/javascripts/drawing/graph.js
+  <app>/public/javascripts/drawing/scene.js:  
+    //= require "graph"
+    ...
+  <app>/public/javascripts/accounts/user.js
+
+The asset preprocessor will figure out what order to load files, so you don't
+have to. But when you debug using Firebug or Webkit, your code will still
+appear in the file layout you're used to rather than jumbled together
+(something other javascript asset bundlers commonly do).
+
+
+
+*Developing Javascript and CSS Gem Components*
+
+Repertoire assets javascript libraries are ordinary rubygems packages. Say
+you wanted to create a javascript drawing package to support the painting
+application above. Here is the suggested gem source structure:
+
+  superdraw/README
+  superdraw/Rakefile                                    # see below
+  superdraw/superdraw.gemspec                           # generated by Rakefile
+  superdraw/lib/superdraw.rb                            # empty file (required for rubygems)
+  superdraw/public/javascripts
+  superdraw/public/javascripts/superdraw.js             # the superdraw library file
+  superdraw/public/javascripts/superdraw/circle.js
+  superdraw/public/javascripts/superdraw/polyhedron.js
+  superdraw/public/javascripts/superdraw/square.js
+  superdraw/public/stylesheets/superdraw.css            # required css
+  superdraw/public/images/superdraw/anchor.png          # provided image assets 
+  superdraw/public/images/superdraw/crosshairs.png
+  superdraw/LICENSE
+  superdraw/TODO
+
+As you can see, a Javascript component gem has the same structure as a Rails
+or Merb application. You may also include ruby library code in lib/ if you wish.
+
+The asset loader will find any library in $LOAD_PATH/../public/javascripts/*.js,
+in this case 'superdraw.js'.  This file might look something like the following:
+
+  //= require "superdraw/circle"                      # load private source files
+  //= require "superdraw/polyhedron"
+  //= require "superdraw/square"
+  //= require "../stylesheets/superdraw.css"          # the library's main css file
+  //= provide "../images/splashscreen.jpeg"           # ancillary assets
+  //= provide "../images/superdraw/**/*"
+
+If the circle, polyhedron or square files use other javascript libraries --
+say, the Processing javascript framework -- they will include require
+directives of their own.
+
+The provide directive is used to specify additional assets that should be
+available in the host application's url space. You can reference these files
+in your css, and any relative urls will be rewritten appropriately when the
+css files are bundled together and moved to a new location in the host app.
+
+Unix-style file globs can be used in any require or provide statement, as seen
+in the final provide statement above. Also, you can combine search and
+relative file paths to load sub-libraries (e.g. 'require <superdraw/circle>').
+
+Keep in mind that files under /public may appear in your host app's URL
+space. Hence, it is advantageous to namespace your materials in directories
+named after your library (e.g. /images/superdraw/circle.png rather than
+/images/circle.png).
+
+For security reasons, the system will never serve a file that was not
+explicitly required or provided.
+
+If you are using Rails and would like to preview the manifest or generate
+digests by hand, use 'rake assets:list' and 'rake assets:build'.
+
+
+
+*Debugging Javascript Dependencies*
+
+When your web application starts up, the asset manager logs a record of which
+javascript and css files have been required, by which libraries, and what url
+each is served at.  For example:
+
+~ Requiring /javascripts/application.js (/Users/yorkc/facet-example-app/public/javascripts/application.js)
+~ Requiring   /stylesheets/master.css (/Users/yorkc/facet-example-app/public/stylesheets/master.css)
+~ Requiring   /javascripts/rep.faceting.js (repertoire_faceting-0.3.4)
+~ Requiring     /javascripts/jquery.js (jquery-1.3.2)
+~ Requiring       /javascripts/jquery/jquery-1.3.2.js (jquery-1.3.2)
+~ Requiring     /stylesheets/rep.faceting.css (repertoire_faceting-0.3.4)
+~ Providing     /images (repertoire_faceting-0.3.4)
+~ Requiring   /javascripts/rep.protovis-facets.js (repertoire_faceting-0.3.4)
+~ Requiring     /javascripts/protovis.js (repertoire_faceting-0.3.4)
+~ Requiring       /javascripts/protovis/protovis-d3.1.js (repertoire_faceting-0.3.4)
+~ Assets processed: 1 source files, 5 libraries available, 10 assets provided, 9 files in manifest
+
+Requiring a file that cannot be found is a fatal error, as in Ruby or C. If
+two libraries are found that satisfy a requirement, you will be informed of
+the conflict and told which one is being used.
+
+
+*Deployment Options*
+
+The following options are available for production configurations.
+
+   - precache [false]                   # copy and bundle assets into host application?
+   - compress [false]                   # compress bundled javascript & stylesheets? (implies :precache)
+   - disable_rack_assets [false]               # don't interpolate <script> and <link> tags
+   - path_prefix     ['']                      # prefix for all generated urls
+
+In general, 'compress' is preferred. This copies all binary assets into
+your host application, bundles together all required javascript and css into
+files named '/digest.js' and '/digest.css', and compresses these files using
+YUI compressor.  Use 'precache' if you do not want to compress the files.
+
+In both cases, the asset mirroring middleware is disabled, and your app's
+webserver serves all assets directly from the filesystem.
+
+If desired, you may also disable the <script> and <link> middleware in your
+production install while still precaching and compressing all assets. Set the
+'disable_rack_assets' configuration option to true, and add the following to
+your html header:
+
+<link rel='stylesheet' type='text/css' href='/digest.css'/> 
+<script language='javascript' type='text/javascript' src='/digest.js'></script>
+
+Note, however, that the server performance gain from 'disable_rack_assets' is
+minimal.

data/Rakefile

@@ -0,0 +1,10 @@
+require __FILE__ + '/../lib/repertoire-assets'
+
+gemspec = eval(File.read("repertoire-assets.gemspec"))
+
+task :build => "#{gemspec.full_name}.gem"
+
+file "#{gemspec.full_name}.gem" => gemspec.files + ["repertoire-assets.gemspec"] do
+  system "gem build repertoire-assets.gemspec"
+  system "gem install repertoire-assets-#{Repertoire::Assets::VERSION}.gem"
+end

data/TODO

@@ -0,0 +1,52 @@
+- tainted files need to check css
+
+- rails3. rework rake tasks to use Rails configuration	DONE
+- rails3. use middleware automatically via a railtie	DONE
+- rails3. use rails-style gemspec configuration			DONE 
+
+- create digests based on the gem name for asset builds DONE
+- test exclude functionality                        DONE
+- test asset build config                           DONE
+- test old functionality, using facet ex app        DONE  
+- document asset build feature                      DONE
+
+- write method to copy over cached files            DONE
+- write method to preprocess/require a source file  DONE
+- write method to css insert a source file          DONE
+- yui compress the cached files                     DONE
+- convert to using a manifest instead of includes   DONE
+- helpers for generating the manifests              NOT NECESSARY
+- try running in an actual app                      DONE
+- check digesting                                   DONE
+- verify works with prefix_path 					          DONE
+- check runs unbundled                              DONE
+- provisions for digesting and compressing css      DONE
+- gems should be able to register their own load_paths  NOT NECESSARY
+- when caching, stat mtimes first (multiple merbs)  DONE
+- write a merb-specific rack for options            NOT NECESSARY
+- combine middleware?                               DONE
+- separate out cache?                               NOT TO DO
+- convert to use nokogiri SAX                       NOT POSSIBLE
+- convert to use regexp                             DONE
+- make log output pretty                            DONE
+- optimise checking if update needed on cache       DONE
+- clean task?                                       NOT TO DO
+- option to disable manifester & provider           DONE
+- improve configuration param names                 DONE
+- avoid multiple processes compressing digest       DONE
+- optimise the code                                 DONE
+- in code documentation                             DONE
+- dump load path when cannot resolve a dependency   DONE
+- support for //= require <jquery/ui/accordion>     DONE
+- support for //= require "foo/*.js" (globs)        DONE
+- test suite?                                       NOT FOR NOW
+- find streaming XML module for manifest filter     NOT FOR NOW
+- convert to simplest regexp that fit HTML 4.0 DTD  DONE
+- asset-gen binary                                  NOT FOR NOW
+- README                                            DONE
+
+- provision for http://foo.com in require?
+
+- source files should not be libraries				DONE
+- README needs info on bundling/gem requires
+- README needs note on empty ruby libary file		DONE	

data/lib/repertoire-assets/exceptions.rb

@@ -0,0 +1,8 @@
+module Repertoire
+  module Assets
+    class Error < ::StandardError;        end
+    class ConfigurationError < Error;     end
+    class UnknownAssetError < Error;      end
+    class UnknownDirectiveError < Error;  end
+  end
+end