stylus 0.0.3 → 0.1.0

data/.gitignore

@@ -2,3 +2,4 @@
 .bundle
 Gemfile.lock
 pkg/*
+docs

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## Changelog
 
+### 0.1.0 (2011-06-21)
+[Compare view](https://github.com/lucasmazza/ruby-stylus/compare/v0.0.3...v0.1.0)
+
+* Support for Stylus plugins via `Stylus.use`.
+* Docco documentation live at [http://lucasmazza.github.com/ruby-stylus](http://lucasmazza.github.com/ruby-stylus).
+
+
 ### 0.0.3 (2011-06-06)
 [Compare view](https://github.com/lucasmazza/ruby-stylus/compare/v0.0.2...v0.0.3)
 

data/README.md

@@ -21,6 +21,9 @@ Stylus.compile(File.read('application.styl'))
 
 # Converting old and boring CSS to awesome Stylus.
 Stylus.convert(File.new('file.css'))
+
+# Importing plugins directly from Node.JS, like nib.
+Stylus.use :nib
 ```
 ### With the Rails 3.1 Asset Pipeline.
 

data/Rakefile

@@ -1,5 +1,7 @@
+require 'fileutils'
 require 'bundler'
 require 'rspec/core/rake_task'
+require 'rocco/tasks'
 Bundler::GemHelper.install_tasks
 
 desc "Run specs"
@@ -7,5 +9,17 @@ RSpec::Core::RakeTask.new do |task|
   task.rspec_opts = ["-c -b"]
 end
 
+task :default => :spec
 
-task :default => :spec
+Rocco::make 'docs/'
+
+desc 'Builds Rocco docs'
+task :docs => :rocco do
+  Dir['docs/lib/**/*.html'].each do |file|
+    path = file.gsub(/lib/,'')
+    FileUtils.mkdir_p(File.dirname(path))
+    FileUtils.mv(file, path)
+  end
+  cp 'docs/stylus.html', 'docs/index.html', :preserve => true
+end
+directory 'docs/'

data/lib/stylus.rb

@@ -1,40 +1,81 @@
+## Stylus
+
+# `stylus` is a bridge between your Ruby code and the [Stylus](https://github.com/LearnBoost/stylus)
+# library that runs on Node.js. It's aims to be a replacement for the
+# [stylus_rails](https://github.com/lucasmazza/stylus_rails) gem and to support the Rails 3.1 asset pipeline
+# (via [Tilt](https://github.com/rtomayko/tilt)) and other scenarios,
+# backed by the [ExecJS](https://github.com/sstephenson/execjs) gem.module Stylus
+### Usage
+# To compile a `.styl` file or an arbitrary String to .CSS using stylus, just use the `compile` method.
+#
+# `Stylus.compile(File.new('application.styl'))`
+#
+# A hash of options for the stylus API is accepted.
+#
+# `Stylus.compile(File.read('application.styl'), :compress => true)`
+#
+
 require 'execjs'
 require 'stylus/version'
 require 'stylus/railtie' if defined?(::Rails)
-
 module Stylus
-
   class << self
     @@compress = false
     @@paths = []
+    @@plugins = {}
+
+    # Stores a list of plugins to import inside `Stylus`, with an optional hash.
+
+    def use(*options)
+      arguments = options.last.is_a?(Hash) ? options.pop : {}
+      options.each do |plugin|
+        @@plugins[plugin] = arguments
+      end
+    end
+    alias :plugin :use
+
+    # Retrieves the plugins registered by `use`.
+    def plugins
+      @@plugins
+    end
 
+    # Returns the global load path `Array` for your stylesheets.
     def paths
       @@paths
     end
 
+    # Replaces the global load path `Array` of paths.
     def paths=(val)
       @@paths = Array(val)
     end
 
+    # Returns the global compress flag.
     def compress
       @@compress
     end
 
+    # Sets the global flag for the `compress` option.
     def compress=(val)
       @@compress = val
     end
 
+    # Compiles a given input - a `File`, `StringIO`, `String` or anything that responds to `read`.
+    # Also accepts a hash of options that will be merged with the global configuration.
     def compile(source, options = {})
       source = source.read if source.respond_to?(:read)
       options = merge_options(options)
-      context.call('compiler', source, options)
+      context.call('compiler', source, options, plugins)
     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)
     end
 
+    # Returns a `Hash` of the given `options` merged with the default configuration.
+    # It also concats the global load path with a given `Array`.
     def merge_options(options)
       _paths = options.delete(:paths)
       options = defaults.merge(options)
@@ -42,26 +83,30 @@ module Stylus
       options
     end
 
+    # Returns the default `Hash` of options.
     def defaults
       { :compress => self.compress, :paths => self.paths }
     end
 
+    # Return the gem version alongside with the current `Stylus` version of your system.
     def version
       "Stylus - gem #{VERSION} library #{context.call('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
 
+    # We're targeting the Runtime directly so we don't mess with other
+    # gems using `ExecJS`.
     def backend
-      # Targeting the Runtime directly so we don't mess with other
-      # gems using ExecJS.
       @@_backend ||= ExecJS::Runtimes::Node
     end
   end

data/lib/stylus/compiler.js

@@ -1,8 +1,14 @@
 var stylus = require('stylus');
 
-function compiler(str, options) {
+function compiler(str, options, plugins) {
   var style = stylus(str, options);
   var output = '';
+
+  for(var name in plugins) {
+    var fn = require(name);
+    style.use(fn(plugins[name]));
+  }
+
   style.render(function(error, css) {
     if(error) throw error;
     output = css;

data/lib/stylus/railtie.rb

@@ -1,3 +1,7 @@
+### Stylus Railtie
+# `Railtie` responsible for injecting `stylus` inside the
+# Rails application and the `Sprockets` Asset Pipeline.
+
 require 'stylus/tilt'
 
 module Stylus
@@ -7,11 +11,14 @@ module Stylus
       config.app_generators.stylesheet_engine :styl
       next unless app.config.assets.enabled
 
+      # Loading `Sprockets` before Rails so we can register our own Engine.
       require 'sprockets'
       require 'sprockets/engines'
       Sprockets.register_engine '.styl', Tilt::StylusTemplate
     end
 
+    # Includes the `Rails` asset load path into `stylus` so any
+    # `.styl` file inside it can be imported.
     config.after_initialize do |app|
       Stylus.paths.concat app.assets.paths
     end

data/lib/stylus/tilt.rb

@@ -1,11 +1,9 @@
+### Stylus template implementation for `Tilt`.
+# It can be used by the `Rails` Asset Pipeline or `Sinatra` Applications.
 require 'tilt'
 require 'tilt/template'
 
 module Tilt
-  # Stylus template implementation. See:
-  # http://learnboost.github.com/stylus/
-  #
-  # Stylus templates do not support object scopes, locals, or yield.
   class StylusTemplate < Template
     self.default_mime_type = 'text/css'
 

data/lib/stylus/version.rb

@@ -1,3 +1,3 @@
 module Stylus
-  VERSION = "0.0.3"
+  VERSION = "0.1.0"
 end

data/spec/fixtures/nib.css

@@ -0,0 +1,5 @@
+background {
+  line-height: 1;
+  color: #000;
+  background: #fff;
+}

data/spec/fixtures/nib.styl

@@ -0,0 +1,4 @@
+@import 'nib'
+
+background
+  reset-body()

data/spec/stylus_spec.rb

@@ -1,6 +1,11 @@
 require 'spec_helper'
 
 describe Stylus do
+
+  before do
+    Stylus.plugins.clear
+  end
+
   it "compiles the given source" do
     input, output = fixture :simple
     Stylus.compile(input).should == output
@@ -43,4 +48,15 @@ describe Stylus do
     stylus, css = fixture :stylesheet
     Stylus.convert(css).should == stylus
   end
+
+  it "stores the given plugins" do
+    Stylus.use :one, :two, :argument => true
+    Stylus.should have(2).plugins
+  end
+
+  it "includes the given plugins" do
+    Stylus.use :nib
+    input, output = fixture :nib
+    Stylus.compile(input).should == output
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: stylus
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 27
   prerelease: 
   segments: 
   - 0
+  - 1
   - 0
-  - 3
-  version: 0.0.3
+  version: 0.1.0
 platform: ruby
 authors: 
 - Lucas Mazza
@@ -15,8 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-06-06 00:00:00 -03:00
-default_executable: 
+date: 2011-06-22 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: execjs
@@ -105,6 +104,8 @@ files:
 - spec/fixtures/import.css
 - spec/fixtures/import.styl
 - spec/fixtures/mixins/vendor.styl
+- spec/fixtures/nib.css
+- spec/fixtures/nib.styl
 - spec/fixtures/simple.css
 - spec/fixtures/simple.styl
 - spec/fixtures/stylesheet.css
@@ -113,7 +114,6 @@ files:
 - spec/stylus_spec.rb
 - spec/tilt_spec.rb
 - stylus.gemspec
-has_rdoc: true
 homepage: https://github.com/lucasmazza/ruby-stylus
 licenses: []
 
@@ -143,7 +143,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.6.1
+rubygems_version: 1.8.5
 signing_key: 
 specification_version: 3
 summary: Ruby Stylus Compiler
@@ -153,6 +153,8 @@ test_files:
 - spec/fixtures/import.css
 - spec/fixtures/import.styl
 - spec/fixtures/mixins/vendor.styl
+- spec/fixtures/nib.css
+- spec/fixtures/nib.styl
 - spec/fixtures/simple.css
 - spec/fixtures/simple.styl
 - spec/fixtures/stylesheet.css