stylus 0.5.1 → 0.6.0

data/CHANGELOG.md

@@ -1,33 +1,39 @@
 ## Changelog
 
+### 0.6.0 (2012-05-20)
+[Compare view](https://github.com/lucasmazza/ruby-stylus/compare/v0.5.1...v.0.6.0)
+
+* Sprockets configuration extracted to `Stylus.setup` - you can use this on a Sinatra or Rack app;
+* When `node` isn't available, Stylus will raise a exception of it's own instead of blowing up inside ExecJS.
+
 ### 0.5.1 (2012-05-07)
-[Compare view](https://github.com/lucasmazza/ruby-stylus/compare/v0.5.0...v.0.5.1)
+[Compare view](https://github.com/lucasmazza/ruby-stylus/compare/v0.5.0...v0.5.1)
 
 * Fixes the `ImportProcessor` so it doesn't evaluates the stylesheets.
 
 ### 0.5.0 (2012-03-26)
-[Compare view](https://github.com/lucasmazza/ruby-stylus/compare/v0.4.2...v.0.5.0)
+[Compare view](https://github.com/lucasmazza/ruby-stylus/compare/v0.4.2...v0.5.0)
 
 * Rewrite of the Railtie initializers to match 3.2 loading order;
 * Only folders ending with `stylesheets` will be copied over to `Stylus.paths`.
 
 ### 0.4.2 (2012-03-24)
-[Compare view](https://github.com/lucasmazza/ruby-stylus/compare/v0.4.1...v.0.4.2)
+[Compare view](https://github.com/lucasmazza/ruby-stylus/compare/v0.4.1...v0.4.2)
 
 * Tells Rails to always run the Railtie initializer.
 
 ### 0.4.1 (2012-01-06)
-[Compare view](https://github.com/lucasmazza/ruby-stylus/compare/v0.4.0...v.0.4.1)
+[Compare view](https://github.com/lucasmazza/ruby-stylus/compare/v0.4.0...v0.4.1)
 
 * Skips Sprockets configuration if `config.assets.enabled` isn't true.
 
 ### 0.4.0 (2011-11-23)
-[Compare view](https://github.com/lucasmazza/ruby-stylus/compare/v0.3.0...v.0.4.0)
+[Compare view](https://github.com/lucasmazza/ruby-stylus/compare/v0.3.0...v0.4.0)
 
 * `@import` directives will be added as dependencies to Sprockets (based on the work by @metaskills on the less-rails).
 
 ### 0.3.0 (2011-10-17)
-[Compare view](https://github.com/lucasmazza/ruby-stylus/compare/v0.2.2...v.0.3.0)
+[Compare view](https://github.com/lucasmazza/ruby-stylus/compare/v0.2.2...v0.3.0)
 
 * This gem now uses the [stylus-source](https://github.com/railsjedi/ruby-stylus-source) gem to bundle the latest [NPM](http://search.npmjs.org/#/stylus) package of Stylus, so there's no setup required to install stylus via `npm install` or cloning it into the `node_modules` folder - Thanks @railsjedi.
 * Added a `debug` configuration option, that enables the `linenos` and `firebug` flags on Stylus. Inside Rails, this configuration option will be copied from the `config.assets.debug`;

data/README.md

@@ -62,6 +62,26 @@ If you use Stylus `@import` to expose variables, mixins or just to concatenate c
 @import 'mixins'
 ```
 
+### Standalone Sprockets usage
+
+If you're using Sprockets outside Rails, on Sinatra or on a plain Rack app, you can wire up Stylus inside a instance of `Sprockets::Environment` with the `Stylus.setup` method.
+
+An example of serving stylesheets from `./stylesheets` using just Sprockets and Rack.
+
+```ruby
+require 'sprockets'
+require 'stylus'
+
+# Serve your stylesheets living on ./stylesheets
+assets = Sprockets::Environment.new
+assets.append_path('stylesheets')
+
+Stylus.setup(assets)
+
+# Run the Sprockets with Rack
+map('/assets') { run assets.index }
+```
+
 ## Plugins
 
 [Stylus](https://github.com/LearnBoost/stylus) exposes a nice API to create plugins written on [node.js](http://nodejs.org), like [nib](https://github.com/visionmedia/nib). The installation process should be the same as described above for [Stylus](https://github.com/LearnBoost/stylus) (since they're all npm packages after all). You can hook them up on your Ruby code with `Stylus.use`:

data/lib/stylus.rb

@@ -1,8 +1,9 @@
-require 'execjs'
+require 'stylus/runtime'
+require 'stylus/source'
+require 'stylus/sprockets'
 require 'stylus/version'
 require 'stylus/tilt' if defined?(::Tilt)
 require 'stylus/railtie' if defined?(::Rails)
-require 'stylus/source'
 ## Stylus
 #
 # `stylus` is a bridge between your Ruby code and the [Stylus](https://github.com/LearnBoost/stylus)
@@ -22,6 +23,7 @@ require 'stylus/source'
 # `Stylus.compile(File.read('application.styl'), :compress => true)`
 #
 module Stylus
+  extend Runtime, Sprockets
   class << self
     @@compress = false
     @@debug    = false
@@ -103,14 +105,14 @@ module Stylus
       end
       source  = source.read if source.respond_to?(:read)
       options = merge_options(options)
-      context.call('compiler', source, options, plugins, imports)
+      exec('compile', source, options, plugins, imports)
     end
 
     # Converts back an input of plain CSS to the `Stylus` syntax. The source object can be
     #  a `File`, `StringIO`, `String` or anything that responds to `read`.
     def convert(source)
       source = source.read if source.respond_to?(:read)
-      context.call('convert', source)
+      exec('convert', source)
     end
 
     # Returns a `Hash` of the given `options` merged with the default configuration.
@@ -141,30 +143,10 @@ module Stylus
 
     # Return the gem version alongside with the current `Stylus` version of your system.
     def version
-      "Stylus - gem #{VERSION} library #{context.call('version')}"
+      "Stylus - gem #{VERSION} library #{exec('version')}"
     end
 
     protected
-    # Returns the `ExecJS` execution context.
-    def context
-      @@_context ||= backend.compile(script)
-    end
-
-    # Reads the default compiler script that `ExecJS` will execute.
-    def script
-      File.read(File.expand_path('../stylus/compiler.js',__FILE__))
-    end
-
-    # `ExecJS` 1.2.5+ doesn't support `require` statements on node anymore,
-    # so we use a new instance of the `ExternalRuntime` with the old runner script.
-    def backend
-      @@_backend ||= ExecJS::ExternalRuntime.new(
-        :name        => 'Node.js (V8)',
-        :command     => ["nodejs", "node"],
-        :runner_path => File.expand_path("../stylus/runner.js", __FILE__)
-        )
-    end
-
     def bundled_path
       File.dirname(Stylus::Source.bundled_path)
     end

data/lib/stylus/import_processor.rb

@@ -1,12 +1,24 @@
 # Based on the ImportProcessor from the less-rails gem, by @metaskills
 module Stylus
+  # Internal: A Tilt template that tracks down '@import' declarations
+  # and marks them as a dependency on the current asset.
+  #
+  # Example
+  #
+  #  @import 'dashboard'
+  #  # => A '//= depend_on dashboard' directive can be ommited from the stylesheet.
   class ImportProcessor < Tilt::Template
 
     IMPORT_SCANNER = /@import\s*['"]([^'"]+)['"]\s*/.freeze
 
+    # Internal: Tilt default interface requirement.
+    #
+    # Returns nothing.
     def prepare
     end
 
+    # Internal: Scan the stylesheet body, looking for '@import' calls to
+    # declare them as dependency on the context using 'depend_on' method.
     def evaluate(context, locals, &block)
       dependencies = data.scan(IMPORT_SCANNER).flatten.compact.uniq
 

data/lib/stylus/railtie.rb

@@ -1,32 +1,36 @@
-require 'stylus/tilt'
-require 'stylus/import_processor'
-
+require 'stylus'
 module Stylus
-  ### Stylus Railtie
+  # Internal: The Railtie responsible for integrate the Stylus library with
+  # a Rails 3.2 (or 3.1) application.
+  #
+  # Some of the customizations of using Stylus alongside Rails:
   #
-  # `Railtie` that hooks `stylus` inside a Rails application.
+  # * The application will use the Stylus stylesheet engine;
+  # * The Sprockets instance (present at Rails.application.assets) will be configured
+  #   with the Stylus templates and the configurations defined at 'config.assets' will
+  #   affect how Stylus compile your stylesheets;
+  # * The assets load path - the folders living on app/assets/stylesheets,
+  #   lib/assets/stylesheets and vendor/assets/stylesheets on your app - will be
+  #   added to the Stylus path registry.
   class Railtie < ::Rails::Railtie
 
+    # Internal: Set the Stylesheet engine to 'stylus', so the generator constants
+    # will be loaded from the `Stylus::Generators` namespace.
     config.app_generators.stylesheet_engine :stylus
 
-    initializer 'stylus.register', :after => 'sprockets.environment', :group => :all do |app|
-      if app.config.assets.enabled
-        app.assets.register_engine '.styl', Tilt::StylusTemplate
-        app.assets.register_preprocessor 'text/css', Stylus::ImportProcessor
-      end
-    end
-
-    # Initializer block to inspect the `Sprockets` configuration
-    # And reflect it on the `Stylus` module;
-    # It also includes the `Rails` asset load path into `Stylus` so any
-    # `.styl` file inside it can be imported by the `Stylus` API.
-    initializer 'stylus.config', :after => :append_assets_path, :group => :all do |app|
-      sprockets = app.config.assets
-      paths     = sprockets.paths.select { |dir| dir.to_s.ends_with?('stylesheets') }
-      if sprockets.enabled
-        Stylus.compress = sprockets.compress
-        Stylus.debug    = sprockets.debug
-        Stylus.paths.concat paths
+    # Internal: Initializer block that uses the Stylus.setup utility to configure
+    # both Stylus and the Sprockets instance that lives on 'app.assets'. The entire
+    # configuration object will be passed along.
+    #
+    # If you don't have the Asset Pipeline enabled on your application - done by
+    # setting the 'config.assets.enabled' flag to false, this setup process will be
+    # skipped.
+    #
+    # Returns nothing.
+    initializer 'stylus.setup', :after => :append_assets_path, :group => :all do |app|
+      config = app.config.assets
+      if config.enabled
+        Stylus.setup(app.assets, config)
       end
     end
   end

data/lib/stylus/runtime.rb

@@ -0,0 +1,55 @@
+require 'execjs'
+
+module Stylus
+  # Internal: Module responsible for the ExecJS interaction. Besides handling
+  # the compilation execution, this module provide a runtime validation to ensure
+  # that the Node.JS binary is available to use.
+  module Runtime
+    # Internal: Calls a specific function on the Node.JS context.
+    #
+    # Example
+    #  exec('version', 2)
+    #  # => "2"
+    #
+    # Returns The function returned value.
+    def exec(*arguments)
+      check_availability!
+      context.call(*arguments)
+    end
+
+    private
+    # Internal: Queries the runtime for it's availability and raises a 'RuntimeError'
+    # if the runtime isn't available. Otherwise, this is a noop.
+    def check_availability!
+      unless runtime.available?
+        message = "The Node.JS runtime isn't available to Stylus."
+        message << "Ensure that the 'node' (or 'nodejs') executable is present in your $PATH."
+        raise RuntimeError, message
+      end
+    end
+
+    # Internal: Compile the Stylus compilation script into a execution context
+    # to execute functions into.
+    #
+    # Returns the compiled context.
+    def context
+      @context ||= runtime.compile(script)
+    end
+
+    # Internal: The custom compilation script body.
+    def script
+      File.read(File.expand_path('../runtime/compiler.js',__FILE__))
+    end
+
+    # Internal: Create the ExecJS external runtime with a old runner script that
+    # maintains the state of 'require', so we can use it to load modules like on
+    # any Node.JS program.
+    def runtime
+      @runtime ||= ExecJS::ExternalRuntime.new(
+        :name        => 'Node.js (V8)',
+        :command     => ["nodejs", "node"],
+        :runner_path => File.expand_path("../runtime/runner.js", __FILE__)
+        )
+    end
+  end
+end

data/lib/stylus/{compiler.js → runtime/compiler.js}

@@ -1,6 +1,6 @@
 var stylus = require('stylus');
 
-function compiler(str, options, plugins, imports) {
+function compile(str, options, plugins, imports) {
   var style = stylus(str, options);
   var output = '';
 

data/lib/stylus/sprockets.rb

@@ -0,0 +1,46 @@
+require 'stylus/tilt'
+require 'stylus/import_processor'
+
+# Public: The setup logic to configure both Stylus and Sprockets on any
+# kind of application - Rails, Sinatra or Rack.
+#
+# Example
+#
+#  # mounting Sprockets as a Rack application with Stylus
+#  assets = Sprockets::Environment.new
+#  assets.append_path 'stylesheets'
+#  Stylus.setup(assets)
+#  run assets.index
+module Stylus
+  module Sprockets
+    # Public: Configure a Sprockets environment with Stylus Tilt engine
+    # and the ImportProcessor. It also accept a configuration Hash to
+    # setup the load path and flags of the Stylus module.
+    #
+    # environment - A instance of Sprockets::Environment.
+    # options     - The configuration Hash (default: {})
+    #             :paths - An Array of paths to use the '@import' directive, defaults
+    #                      to the `paths` attribute on the environment object.
+    #              :debug - The Boolean value for the debug flag.
+    #              :compress - The Boolean value for the debug compress.
+    #
+    # Example
+    #
+    #  assets = Sprockets::Environment.new
+    #  Stylus.setup(assets, :compress => settings.production?)
+    #
+    # Returns nothing.
+    def setup(environment, options = {})
+      paths = options[:paths] || environment.paths
+      directories = paths.select { |dir| dir.to_s =~ /stylesheets$/ }
+
+      Stylus.paths.concat(directories)
+
+      Stylus.debug = options.fetch(:debug, Stylus.debug)
+      Stylus.compress = options.fetch(:compress, Stylus.compress)
+
+      environment.register_engine('.styl', Tilt::StylusTemplate)
+      environment.register_preprocessor('text/css', Stylus::ImportProcessor)
+    end
+  end
+end

data/lib/stylus/tilt.rb

@@ -1,26 +1,50 @@
 require 'tilt'
-
+# Public: A Tilt template to compile Stylus stylesheets.
+#
+# Examples
+#
+#  template = Tilt::StylusTemplate.new { |t| File.read('app.styl') }
+#  template.render
+#  # => the compiled CSS from the app.styl file.
+#
+#  Options should assigned on the template constructor.
+#  template = Tilt::StylusTemplate.new(:compress => true) { |t| File.read('app.styl') }
+#  template.render
+#  # => the compiled CSS with compression enabled.
 module Tilt
-  ### stylus template implementation for `Tilt`.
-  #
-  # It can be used by the `Rails` 3.1 or `Sinatra` applications.
   class StylusTemplate < Template
+
+    # Public: The default mime type for stylesheets.
     self.default_mime_type = 'text/css'
 
+    # Internal: Checks if the Stylus module has been properly defined.
+    #
+    # Returns true if the 'Stylus' module is present.
     def self.engine_initialized?
       defined? ::Stylus
     end
 
+    # Internal: Require the 'stylus' file to load the Stylus module.
+    #
+    # Returns nothing.
     def initialize_engine
       require_template_library 'stylus'
     end
 
+    # Internal: Caches the filename as an option entry if it's present.
+    #
+    # Returns nothing.
     def prepare
       if self.file
         options[:filename] ||= self.file
       end
     end
 
+    # Internal: Compile the template Stylus using this instance options.
+    # The current 'scope' and given 'locals' are ignored and the output
+    # is cached.
+    #
+    # Returns the compiled stylesheet with CSS syntax.
     def evaluate(scope, locals, &block)
       @output ||= Stylus.compile(data, options)
     end

data/lib/stylus/version.rb

@@ -1,3 +1,3 @@
 module Stylus
-  VERSION = "0.5.1"
+  VERSION = "0.6.0"
 end

data/spec/rails_spec.rb

@@ -0,0 +1,49 @@
+require 'spec_helper'
+
+describe 'Rails integration' do
+
+  it "copies the folders ending with 'stylesheets' from the Sprockets load path" do
+    app = create_app
+    Stylus.paths.should == [fixture_root]
+    Stylus.paths.should_not == app.assets.paths
+  end
+
+  it 'process .styl files with the asset pipeline' do
+    result = fixture(:simple).last
+
+    app = create_app
+    app.assets['simple'].to_s.should == result
+  end
+
+  it 'enables @import definitions' do
+    result = fixture(:import).last
+
+    app = create_app
+    app.assets['import'].to_s.should == result
+  end
+
+  it 'skips debug info by default' do
+    app = create_app
+    asset = app.assets['simple']
+    asset.to_s.should_not match(/line 1 : #{asset.pathname}/)
+  end
+
+  it 'provides debug info if required' do
+    app = create_app(:debug => true)
+    asset = app.assets['simple']
+    asset.to_s.should match(/line 1 : #{asset.pathname}/)
+  end
+
+  it 'compress the output if Rails is configured to compress them too' do
+    result = fixture(:compressed).last
+
+    app = create_app(:compress => true)
+    app.assets['compressed'].to_s.should == result
+  end
+
+  it 'loads the app normally even when the asset pipeline is disabled' do
+    expect {
+      create_app(:enabled => false)
+    }.to_not raise_error
+  end
+end

data/spec/runtime_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+describe Stylus::Runtime do
+  it "raises an error if the runtime isn't available" do
+    Stylus.stub(:runtime) { mock("An unavailable Runtime", :available? => false) }
+
+    expect {
+      Stylus.version
+    }.to raise_error RuntimeError, %r[The Node.JS runtime isn't available to Stylus.]
+  end
+end

data/spec/spec_helper.rb

@@ -4,8 +4,8 @@ require 'rails/generators/test_case'
 
 require 'active_support/railtie'
 require 'action_controller/railtie'
+require 'sprockets'
 require 'sprockets/railtie'
-require 'stylus/railtie'
 require 'stylus'
 
 require 'active_support/core_ext/class/attribute_accessors'

data/spec/sprockets_spec.rb

@@ -1,55 +1,31 @@
 require 'spec_helper'
 
-describe 'Sprockets and Rails integration' do
-
-  it "copies the folders ending with 'stylesheets' from the Sprockets load path" do
-    app = create_app
-    Stylus.paths.should == [fixture_root]
-    Stylus.paths.should_not == app.assets.paths
-  end
-
-  it 'process .styl files with the asset pipeline' do
-    result = fixture(:simple).last
-
-    app = create_app
-    app.assets['simple'].to_s.should == result
-  end
-
-  it 'enables @import definitions' do
-    result = fixture(:import).last
-
-    app = create_app
-    app.assets['import'].to_s.should == result
+describe "Sprockets setup" do
+  let(:env) do
+    Sprockets::Environment.new do |assets|
+      assets.append_path fixture_root
+      assets.append_path 'javascripts'
+    end
   end
 
-  it 'skips debug info by default' do
-    app = create_app
-    asset = app.assets['simple']
-    asset.to_s.should_not match(/line 1 : #{asset.pathname}/)
+  it "register the Tilt engine" do
+    env.should_receive(:register_engine).with('.styl', Tilt::StylusTemplate)
+    Stylus.setup(env)
   end
 
-  it 'provides debug info if required' do
-    app = create_app(:debug => true)
-    asset = app.assets['simple']
-    asset.to_s.should match(/line 1 : #{asset.pathname}/)
+  it "register the import processor" do
+    env.should_receive(:register_preprocessor).with('text/css', Stylus::ImportProcessor)
+    Stylus.setup(env)
   end
 
-  it 'compress the output if Rails is configured to compress them too' do
-    result = fixture(:compressed).last
-
-    app = create_app(:compress => true)
-    app.assets['compressed'].to_s.should == result
+  it "copies the 'stylesheets' paths" do
+    Stylus.setup(env)
+    Stylus.paths.should == [fixture_root]
   end
 
-  it "share variables between imported stylesheets" do
-    result = fixture(:variables).last
-
-    app = create_app
-    app.assets['variables'].to_s.should == result
-  end
-  it 'loads the app normally even when the asset pipeline is disabled' do
-    expect {
-      create_app(:enabled => false)
-    }.to_not raise_error
+  it "configure the debug and compress flags" do
+    Stylus.setup(env, :debug => true, :compress => true)
+    Stylus.debug.should == true
+    Stylus.compress.should == true
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stylus
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-07 00:00:00.000000000 Z
+date: 2012-05-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: execjs
@@ -126,10 +126,12 @@ files:
 - lib/rails/generators/stylus/assets/templates/stylesheet.css.styl
 - lib/rails/generators/stylus/scaffold/scaffold_generator.rb
 - lib/stylus.rb
-- lib/stylus/compiler.js
 - lib/stylus/import_processor.rb
 - lib/stylus/railtie.rb
-- lib/stylus/runner.js
+- lib/stylus/runtime.rb
+- lib/stylus/runtime/compiler.js
+- lib/stylus/runtime/runner.js
+- lib/stylus/sprockets.rb
 - lib/stylus/tilt.rb
 - lib/stylus/version.rb
 - spec/cases/compressed.css
@@ -144,6 +146,8 @@ files:
 - spec/generators/controller_generator_spec.rb
 - spec/generators/scaffold_generator_spec.rb
 - spec/import_processor_spec.rb
+- spec/rails_spec.rb
+- spec/runtime_spec.rb
 - spec/spec_helper.rb
 - spec/sprockets_spec.rb
 - spec/stylesheets/compressed.styl
@@ -201,6 +205,8 @@ test_files:
 - spec/generators/controller_generator_spec.rb
 - spec/generators/scaffold_generator_spec.rb
 - spec/import_processor_spec.rb
+- spec/rails_spec.rb
+- spec/runtime_spec.rb
 - spec/spec_helper.rb
 - spec/sprockets_spec.rb
 - spec/stylesheets/compressed.styl