pinion 0.2.2 → 0.3.0

data/README.md

@@ -50,7 +50,7 @@ class YourApp < Sinatra::Base
     pinion.watch "public/stylus"
   end
 
-  helpers { include Pinion::SinatraHelpers }
+  helpers Pinion::SinatraHelpers
   ...
 end
 ```
@@ -117,31 +117,33 @@ Pinion provides some helpers to help you construct links for assets.
 ```
 
 This assumes that you have the `Pinion::Server` instance available inside your app as `pinion`. If you're
-using sinatra and `Pinion::SinatraHelpers`, then the helpers are available right in your app's scope:
+using Sinatra and `Pinion::SinatraHelpers`, then the helpers are available right in your app's scope:
 
 ``` erb
   <%= css_url("style.css") %>
 ```
 
-# In Production
+## In Production
 
 In production, you may wish to concatenate and minify your assets before you serve them. This is done through
 using asset bundles. Pinion provides a predefined bundle type, `:concatenate_and_uglify_js`, for your
 convenience.
 
-You can bundle files by putting this in your app:
+You will create bundles when you set up your `Pinion::Server` instance:
+
+``` ruby
+pinion.create_bundle(:main_bundle, :concatenate_and_uglify_js, ["app.js", "util.js", "jquery.js"])
+```
+
+In this case, `:main_bundle` is an identifier for this bundle, and will the name under which this bundle is
+served. In your view, you will use the bundle similarly to how you use the `js_url` or `css_url` helpers:
 
 ``` erb
-<%= pinion.js_bundle(:concatenate_and_uglify_js, "main-bundle",
-    "app.js",
-    "helpers.js",
-    "util.js",
-    "jquery.js"
-    ) %>
+<%= js_bundle(:main_bundle) %>
 ```
 
-In development, the individual `<script>` tags for each asset will be emitted; in production, a single asset
-(`main-bundle.js`) will be produced.
+In development, the individual `<script>` tags for each asset will be emitted; in production, a single
+asset (`main-bundle.js`) will be produced.
 
 The `:concatenate_and_uglify_js` bundle type simply concatenates JS files and runs them through
 [Uglifier](https://github.com/lautis/uglifier). No default CSS bundle type is provided (but the built-in Sass
@@ -168,6 +170,15 @@ Note that in production mode, asset URLs will have the md5sum of the asset inser
 
 and these assets are served with long (1-year) expiry, for good cacheability.
 
+# Example
+
+You can see an example app using Pinion and Sinatra in the `example/` directory. This app shows serving some
+static and compiled assets as well as a simple asset bundle. Run `bundle install` in that directory to get the
+necessary gems, then run it:
+
+    rackup config.ru                     # Development mode
+    RACK_ENV=production rackup config.ru # Production mode
+
 # Notes
 
 * Currently, Pinion sidesteps the dependency question by invalidating its cache of each file of a particular
@@ -176,12 +187,39 @@ and these assets are served with long (1-year) expiry, for good cacheability.
   intance, if `foo/bar` and `foo/baz` are both on the watch list, and both of the files `foo/bar/style.scss`
   and `foo/baz/style.scss` exist, then `foo/bar/style.scss` will be used if a request occurs for
   `/style.css`.)
-
-You can see an example app using Pinion and Sinatra in the `example/` directory. Run `bundle install` in that
-directory to get the necessary gems, then run it:
-
-    rackup config.ru                     # Development mode
-    RACK_ENV=production rackup config.ru # Production mode
+* If you don't use the url helpers provided by Pinion and instead just serve assets with a plain url (that is,
+  without a checksum in the url), Pinion will serve the assets with 10-minute expiry in the Cache-Control
+  header. In general, you should try to serve all your assets by using the urls given by the helpers.
+
+## Why not use Sprockets?
+
+You should! [Sprockets](https://github.com/sstephenson/sprockets/) is a great project. Pinion is a smaller
+project than Sprockets, and it does fewer things. I made Pinion because I'm not using Rails (the Rails
+integration is where Sprockets really shines) and because some of the design choices that Sprockets makes
+don't really fit my ideal workflow. Here are a few things that Pinion does differently:
+
+* Conversions are defined from one filetype to another (e.g. `:scss => :css`), not by the chain of file
+  extensions (e.g. `foo.css.scss`). I like the asset manager to follow the file naming scheme, not the other
+  way around.
+* It's very easy to define your own conversions instead of using the built-in ones (and this is expected, as
+  Pinion only comes with a few of them). This makes it very simple to customize the behavior for your own
+  needs. Want to output minified css in production but a human-readable version in dev? This is easy to do
+  (and this is the default behavior of the built-in sass/scss converters).
+* To support concatenation, Sprockets uses special directives in comments at the beginning of files (e.g.
+  `//= require jquery`) to specify dependencies between files. To my mind, this is not desirable because:
+
+    * It's easier to debug in development if the files aren't all concatentated together.
+    * Other systems (say, a node.js-based JS test runner) don't understand these dependencies.
+    * How you bundle assets is mostly a caching/performance concern separate from your app logic, so it
+      doesn't necessarily make sense to tie them together. For instance, you may wish to bundle together your
+      vendored JS separately from your application JS if you expect the latter to change much more frequently.
+
+  In contrast, Pinion bundles are created by using the `*_bundle` methods in your app server (view) code,
+  which (in my opinion) is much more obvious behavior.
+
+This being said, you should certainly consider using Sprockets if it fits into your project. It is a very
+established project that powers the Rails asset pipeline, and it has great support for a wide variety of
+conversion types. If you use both, let me know what you think!
 
 # Authors
 

data/lib/pinion/bundle.rb

@@ -8,41 +8,47 @@ module Pinion
   # A `Bundle` is a set of assets of the same type that will be served as a single grouped asset in
   # production. A `Bundle` has a `BundleType` that defines how to process the bundle.
   class Bundle < Asset
+    # Each bundle is cached by name.
     @@bundles = {}
 
-    attr_reader :contents, :name
+    attr_reader :contents, :name, :paths
 
     # Create a new `Bundle`.
-    def initialize(bundle_type, name, assets)
+    def initialize(bundle_type, name, paths)
       @bundle_type = bundle_type
       @name = name
-      @assets = assets
-      raise Error, "No assets provided" if assets.empty?
-      @extension = assets.first.extension
-      unless assets.all? { |asset| asset.extension == @extension }
+      @paths = paths
+      raise Error, "No paths provided" if paths.empty?
+
+      @assets = paths.map do |path|
+        asset = Asset[path]
+        raise "Error: no such asset available: #{path}" unless asset
+        asset
+      end
+      @extension = @assets.first.extension
+      unless @assets.all? { |asset| asset.extension == @extension }
         raise Error, "All assets in a bundle must have the same extension"
       end
-      @contents = bundle_type.process(assets)
+      @contents = bundle_type.process(@assets)
       @checksum = Digest::MD5.hexdigest(@contents)
-      @mtime = assets.map(&:mtime).max
+      @mtime = @assets.map(&:mtime).max
       @length = Rack::Utils.bytesize(@contents)
     end
 
-    # Create a new bundle from a bundle_type name (e.g. `:concatenate_and_uglify_js`) and an array of
-    # `Asset`s. The name is taken as the identifier in the resulting path.
-    def self.create(bundle_type_name, name, assets)
+    # Create a new bundle from a bundle_type name (e.g. `:concatenate_and_uglify_js`) and an array of paths.
+    # The name is taken as the identifier in the resulting path.
+    def self.create(name, bundle_type_name, paths)
       bundle_type = BundleType[bundle_type_name]
       raise Error, "No such bundle type #{bundle_type_name}" unless bundle_type
-      bundle = Bundle.new(bundle_type, name, assets)
-      @@bundles[bundle.checksum] = bundle
+      if @@bundles[name.to_s]
+        raise Error, "There is already a bundle called #{name}. Each bundle must have a different name."
+      end
+      bundle = Bundle.new(bundle_type, name, paths)
+      @@bundles[name.to_s] = bundle
       bundle
     end
 
-    # Find a `Bundle` by its name and checksum
-    def self.[](name, checksum)
-      return nil unless name && checksum
-      bundle = @@bundles[checksum]
-      (bundle && (bundle.name == name)) ? bundle : nil
-    end
+    # Find a `Bundle` by its name.
+    def self.[](name) name && @@bundles[name.to_s] end
   end
 end

data/lib/pinion/server.rb

@@ -64,14 +64,30 @@ module Pinion
         path.sub!("-#{checksum_tag}", "")
       end
 
-      asset = Bundle[bundle_name, checksum_tag] || Asset[path]
+      # First see if there is a bundle with this name
+      asset = Bundle[bundle_name]
+      if asset
+        # If the checksum doesn't match the bundle, we want to return a 404.
+        asset = nil unless asset.checksum == checksum_tag
+      else
+        # If there is no bundle with this name, find another type of Asset with the name instead.
+        asset = Asset[path]
+      end
 
       if asset
         # If the ETag matches, give a 304
         return [304, {}, []] if env["HTTP_IF_NONE_MATCH"] == %Q["#{asset.checksum}"]
 
-        # Cache for a year in production; don't cache in dev
-        cache_policy = checksum_tag ? "max-age=31536000" : "must-revalidate"
+        if Pinion.environment == "production"
+          # In production, if there is a checksum, cache for a year (because if the asset changes with a
+          # redeploy, the checksum will change). If there is no checksum, cache for 10 minutes (this way at
+          # worst we only serve 10 minute stale assets, and caches in front of Pinion will be able to help
+          # out).
+          cache_policy = checksum_tag ? "max-age=31536000" : "max-age=600"
+        else
+          # Don't cache in dev.
+          cache_policy = "must-revalidate"
+        end
         headers = {
           "Content-Type" => asset.content_type,
           "Content-Length" => asset.length.to_s,
@@ -113,29 +129,36 @@ module Pinion
     def css_inline(path) %Q{<style type="text/css">#{asset_inline(path)}</style>} end
     def js_inline(path) %Q{<script>#{asset_inline(path)}</script>} end
 
-    # Bundle several assets together. In production, the single bundled result is produced; otherwise, each
-    # individual asset_url is returned.
-    def bundle_url(bundle_name, name, *paths)
-      return paths.map { |p| asset_url(p) } unless Pinion.environment == "production"
-      paths.each { |path| path.sub!(%r[^(#{@mount_point})?/?], "") }
-      assets = paths.map do |path|
-        asset = Asset[path]
-        raise "Error: no such asset available: #{path}" unless asset
-        asset
+    # Create a bundle of assets. Each asset must convert to the same final type. `name` is an identifier for
+    # this bundle; `bundle_name` is the # identifier for your bundle type (e.g. `:concatenate_and_uglify_js`);
+    # and `paths` are all the asset paths. In development, no bundles will be created (but the list of
+    # discrete assets will be saved for use in a subsequent `bundle_url` call).
+    def create_bundle(name, bundle_name, paths)
+      if Bundle[name]
+        raise "Error: there is already a bundle called #{name} with different component files. Each " <<
+              "bundle must have a unique name."
       end
-      bundle = Bundle.create(bundle_name, name, assets)
-      ["#{@mount_point}/#{bundle.name}-#{bundle.checksum}.#{bundle.extension}"]
-    end
-    def js_bundle(bundle_name, name, *paths)
-      bundle_url(bundle_name, name, *paths).map { |path| js_wrapper(path) }.join
+
+      normalized_paths = paths.map { |path| path.sub(%r[^(#{@mount_point})?/?], "") }
+      Bundle.create(name, bundle_name, normalized_paths)
     end
-    def css_bundle(bundle_name, name, *paths)
-      bundle_url(bundle_name, name, *paths).map { |path| css_wrapper(path) }.join
+
+    # Return the bundle url. In production, the single bundled result is produced; otherwise, each individual
+    # asset_url is returned.
+    def bundle_url(name)
+      bundle = Bundle[name]
+      raise "No such bundle: #{name}" unless bundle
+      return bundle.paths.map { |p| asset_url(p) } unless Pinion.environment == "production"
+      ["#{@mount_point}/#{bundle.name}-#{bundle.checksum}.#{bundle.extension}"]
     end
+    def js_bundle(name) bundle_url(name).map { |path| js_wrapper(path) }.join end
+    def css_bundle(name) bundle_url(name).map { |path| css_wrapper(path) }.join end
 
     private
 
-    def js_wrapper(inner) %Q{<script src="#{inner}"></script>} end
+    # Need type="text/javascript" for IE compatibility. The content-type will be set correctly as
+    # "application/javascript" in the response.
+    def js_wrapper(inner) %Q{<script type="text/javascript" src="#{inner}"></script>} end
     def css_wrapper(inner) %Q{<link type="text/css" rel="stylesheet" href="#{inner}" />} end
 
     def with_content_length(response)

data/lib/pinion/sinatra_helpers.rb

@@ -9,9 +9,7 @@ module Pinion
   #
   # then mix in in this module in your sinatra app:
   #
-  #     helpers do
-  #       include Pinion::SinatraHelpers
-  #     end
+  #     helpers Pinion::SinatraHelpers
   #
   # Now you can access the Pinion::Server helper methods in your view:
   #

data/lib/pinion/version.rb

@@ -1,3 +1,3 @@
 module Pinion
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pinion
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-03 00:00:00.000000000Z
+date: 2012-08-17 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
-  requirement: &20353460 !ruby/object:Gem::Requirement
+  requirement: &26493960 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: '1.0'
   type: :runtime
   prerelease: false
-  version_requirements: *20353460
+  version_requirements: *26493960
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &20353040 !ruby/object:Gem::Requirement
+  requirement: &26493500 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *20353040
+  version_requirements: *26493500
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &20352580 !ruby/object:Gem::Requirement
+  requirement: &26493020 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *20352580
+  version_requirements: *26493020
 - !ruby/object:Gem::Dependency
   name: scope
-  requirement: &20352160 !ruby/object:Gem::Requirement
+  requirement: &26492500 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *20352160
+  version_requirements: *26492500
 - !ruby/object:Gem::Dependency
   name: rack-test
-  requirement: &20351740 !ruby/object:Gem::Requirement
+  requirement: &26492020 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *20351740
+  version_requirements: *26492020
 - !ruby/object:Gem::Dependency
   name: coffee-script
-  requirement: &20351320 !ruby/object:Gem::Requirement
+  requirement: &26491360 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *20351320
+  version_requirements: *26491360
 - !ruby/object:Gem::Dependency
   name: dedent
-  requirement: &20350900 !ruby/object:Gem::Requirement
+  requirement: &26490460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,7 +87,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *20350900
+  version_requirements: *26490460
 description: ! 'Pinion is a Rack application that you can use to compile and serve
   assets (such as Javascript and CSS).