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

compile(source, options = {}) click to toggle source

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

compress() click to toggle source

Returns the global compress flag.

# File lib/stylus.rb, line 98
def compress
  @@compress
end

Also aliased as: compress?

compress=(val) click to toggle source

Sets the global flag for the `compress` option.

# File lib/stylus.rb, line 104
def compress=(val)
  @@compress = val
end

compress?()

Alias for: compress

convert(source) click to toggle source

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

debug() click to toggle source

Returns the `debug` flag used to set the `linenos` and `firebug` option for Stylus.

# File lib/stylus.rb, line 79
def debug
  @@debug
end

Also aliased as: debug?

debug=(val) click to toggle source

Sets the `debug` flag.

# File lib/stylus.rb, line 93
def debug=(val)
  @@debug = val
end

debug?()

Alias for: debug

debug_options() click to toggle source

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

defaults() click to toggle source

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

define(variable, value, options = {}) click to toggle source

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

definitions() click to toggle source

Retrieves all the registered variables.

# File lib/stylus.rb, line 64
def definitions
  @@definitions
end

detect_template_hander(options = {}) click to toggle source

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

import(*paths) click to toggle source

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

Also aliased as: imports

imports(*paths)

Alias for: import

merge_options(options) click to toggle source

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

nib=(flag) click to toggle source

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

paths() click to toggle source

Returns the global load path `Array` for your stylesheets.

# File lib/stylus.rb, line 69
def paths
  @@paths
end

paths=(val) click to toggle source

Replaces the global load path `Array` of paths.

# File lib/stylus.rb, line 74
def paths=(val)
  @@paths = Array(val)
end

plugin(*options)

Alias for: use

plugins() click to toggle source

Retrieves all the registered plugins.

# File lib/stylus.rb, line 59
def plugins
  @@plugins
end

setup(environment, options = {}) click to toggle source

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

use(*options) click to toggle source

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

Also aliased as: plugin

version() click to toggle source

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

bundled_path() click to toggle source

# File lib/stylus.rb, line 161
def bundled_path
  File.dirname(Stylus::Source.bundled_path)
end