module Stylus
Stylus
`stylus` is a bridge between your Ruby code and the [Stylus](github.com/LearnBoost/stylus) library that runs on Node.js. It's aims to be a replacement for the [stylus_rails](github.com/lucasmazza/stylus_rails) gem and to support the Rails
3.1 asset pipeline (via [Tilt](github.com/rtomayko/tilt)) and other scenarios, backed by the [ExecJS](github.com/sstephenson/execjs) gem.
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)`
Based on the ImportProcessor
from the less-rails gem, by @metaskills
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
Public: A Tilt
template to compile Stylus
stylesheets with asset helpers.
Constants
- VERSION
Public Class Methods
Compiles a given input - a plain String, `File` or some sort of IO object that responds to `read`. It accepts a hash of options that will be merged with the global configuration. If the source has a `path`, it will be expanded and used as the :filename option So the debug options can be used.
# File lib/stylus.rb, line 113 def compile(source, options = {}) if source.respond_to?(:path) && source.path options[:filename] ||= File.expand_path(source.path) end source = source.read if source.respond_to?(:read) options = merge_options(options) exec('compile', source, options, plugins, imports, definitions) end
Returns the global compress flag.
# File lib/stylus.rb, line 98 def compress @@compress end
Sets the global flag for the `compress` option.
# File lib/stylus.rb, line 104 def compress=(val) @@compress = val 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`.
# File lib/stylus.rb, line 124 def convert(source) source = source.read if source.respond_to?(:read) exec('convert', source) end
Returns the `debug` flag used to set the `linenos` and `firebug` option for Stylus
.
# File lib/stylus.rb, line 79 def debug @@debug end
Sets the `debug` flag.
# File lib/stylus.rb, line 93 def debug=(val) @@debug = val end
Returns a Hash with the debug options to pass to Stylus
.
# File lib/stylus.rb, line 151 def debug_options { linenos: self.debug?, firebug: self.debug? } end
Returns the default `Hash` of options: the compress flag and the global load path.
# File lib/stylus.rb, line 145 def defaults { compress: self.compress?, paths: self.paths } end
Stores a list of defined variables to create on every compile process.
# File lib/stylus.rb, line 53 def define(variable, value, options = {}) literal = true if options[:literal] @@definitions[variable] = { value: value, literal: literal } end
Retrieves all the registered variables.
# File lib/stylus.rb, line 64 def definitions @@definitions end
Internal: Gets the desired Tilt
template handler to the current configuration. If a 'rails' option is present then the Rails
specific template will be returned instead of the default Stylus
Tilt
template.
Returns a Tilt::Template children class.
# File lib/stylus/sprockets.rb, line 52 def self.detect_template_hander(options = {}) if options[:rails] Stylus::Rails::StylusTemplate else Tilt::StylusTemplate end end
Stores a list of stylesheets to import on every compile process.
# File lib/stylus.rb, line 43 def import(*paths) if paths.any? @@imports = @@imports.concat(paths) end @@imports end
Returns a `Hash` of the given `options` merged with the default configuration. It also concats the global load path with a given `:paths` option.
# File lib/stylus.rb, line 131 def merge_options(options) filename = options[:filename] _paths = options.delete(:paths) options = defaults.merge(options) options[:paths] = paths.concat(Array(_paths)) if filename options = options.merge(debug_options) end options end
Marks the `nib` plugin to be loaded and included on every stylesheet.
# File lib/stylus.rb, line 85 def nib=(flag) if flag use :nib import :nib end end
Returns the global load path `Array` for your stylesheets.
# File lib/stylus.rb, line 69 def paths @@paths end
Replaces the global load path `Array` of paths.
# File lib/stylus.rb, line 74 def paths=(val) @@paths = Array(val) end
Retrieves all the registered plugins.
# File lib/stylus.rb, line 59 def plugins @@plugins end
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: {})
:rails - a flag to inform that the current application is a Rails app. :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.
# File lib/stylus/sprockets.rb, line 34 def self.setup(environment, options = {}) paths = options[:paths] || environment.paths Stylus.paths.concat(paths) Stylus.debug = options.fetch(:debug, Stylus.debug) Stylus.compress = options.fetch(:compress, Stylus.compress) template = detect_template_hander(options) environment.register_mime_type 'text/styl', extensions: ['.styl'] environment.register_mime_type 'text/css', extensions: ['.css'] environment.register_transformer 'text/styl', 'text/css', template end
Stores a list of plugins to import inside `Stylus`, with an optional hash.
# File lib/stylus.rb, line 34 def use(*options) arguments = options.last.is_a?(Hash) ? options.pop : {} options.each do |plugin| @@plugins[plugin] = arguments end end
Return the gem version alongside with the current `Stylus` version of your system.
# File lib/stylus.rb, line 156 def version "Stylus - gem #{VERSION} library #{exec('version')}" end
Protected Class Methods
# File lib/stylus.rb, line 161 def bundled_path File.dirname(Stylus::Source.bundled_path) end