Class Sprockets::DirectiveProcessor
In: lib/sprockets/directive_processor.rb
Parent: Tilt::Template

The `DirectiveProcessor` is responsible for parsing and evaluating directive comments in a source file.

A directive comment starts with a comment prefix, followed by an "=", then the directive name, then any arguments.

    // JavaScript
    //= require "foo"

    # CoffeeScript
    #= require "bar"

    /* CSS
     *= require "baz"
     */

The Processor is implemented as a `Tilt::Template` and is loosely coupled to Sprockets. This makes it possible to disable or modify the processor to do whatever you‘d like. You could add your own custom directives or invent your own directive syntax.

`Environment#processors` includes `DirectiveProcessor` by default.

To remove the processor entirely:

    env.unregister_processor('text/css', Sprockets::DirectiveProcessor)
    env.unregister_processor('application/javascript', Sprockets::DirectiveProcessor)

Then inject your own preprocessor:

    env.register_processor('text/css', MyProcessor)

Methods

Constants

HEADER_PATTERN = / \A ( (?m:\s*) ( (\/\* (?m:.*?) \*\/) | (\#\#\# (?m:.*?) \#\#\#) | (\/\/ .* \n?)+ | (\# .* \n?)+ ) )+ /x   Directives will only be picked up if they are in the header of the source file. C style (/* */), JavaScript (//), and Ruby (#) comments are supported.

Directives in comments after the first non-whitespace line of code will not be processed.

DIRECTIVE_PATTERN = / ^ [\W]* = \s* (\w+.*?) (\*\/)? $ /x   Directives are denoted by a `=` followed by the name, then argument list.

A few different styles are allowed:

    // =require foo
    //= require foo
    //= require "foo"

Attributes

body  [R] 
context  [R] 
header  [R] 
included_pathnames  [R] 
pathname  [R] 

Public Instance methods

Returns an Array of directive structures. Each structure is an Array with the line number as the first element, the directive name as the second element, followed by any arguments.

    [[1, "require", "foo"], [2, "require", "bar"]]

Implemented for Tilt#render.

`context` is a `Context` instance with methods that allow you to access the environment and append to the bundle. See `Context` for the complete API.

Returns the header String with any directives stripped.

Returns the source String with any directives stripped.

Protected Instance methods

Checks if Sprockets 1.x compat mode enabled

Sprockets 1.x allowed for constant interpolation if a constants.yml was present. This is only available if compat mode is on.

Enable Sprockets 1.x compat mode.

Makes it possible to use the same JavaScript source file in both Sprockets 1 and 2.

    //= compat

Allows you to state a dependency on an asset without including it.

This is used for caching purposes. Any changes that would invalid the asset dependency will invalidate the cache our the source file.

Unlike `depend_on`, the path must be a requirable asset.

    //= depend_on_asset "bar.js"

Allows you to state a dependency on a file without including it.

This is used for caching purposes. Any changes made to the dependency file will invalidate the cache of the source file.

This is useful if you are using ERB and File.read to pull in contents from another file.

    //= depend_on "foo.png"

Gathers comment directives in the source and processes them. Any directive method matching `process_*_directive` will automatically be available. This makes it easy to extend the processor.

To implement a custom directive called `require_glob`, subclass `Sprockets::DirectiveProcessor`, then add a method called `process_require_glob_directive`.

    class DirectiveProcessor < Sprockets::DirectiveProcessor
      def process_require_glob_directive
        Dir["#{pathname.dirname}/#{glob}"].sort.each do |filename|
          require(filename)
        end
      end
    end

Replace the current processor on the environment with your own:

    env.unregister_processor('text/css', Sprockets::DirectiveProcessor)
    env.register_processor('text/css', DirectiveProcessor)

The `include` directive works similar to `require` but inserts the contents of the dependency even if it already has been required.

    //= include "header"

`provide` is stubbed out for Sprockets 1.x compat. Mutating the path when an asset is being built is not permitted.

The `require` directive functions similar to Ruby‘s own `require`. It provides a way to declare a dependency on a file in your path and ensures its only loaded once before the source file.

`require` works with files in the environment path:

    //= require "foo.js"

Extensions are optional. If your source file is ".js", it assumes you are requiring another ".js".

    //= require "foo"

Relative paths work too. Use a leading `./` to denote a relative path:

    //= require "./bar"

`require_directory` requires all the files inside a single directory. It‘s similar to `path/*` since it does not follow nested directories.

    //= require_directory "./javascripts"

`require_self` causes the body of the current file to be inserted before any subsequent `require` or `include` directives. Useful in CSS files, where it‘s common for the index file to contain global styles that need to be defined before other dependencies are loaded.

    /*= require "reset"
     *= require_self
     *= require_tree .
     */

`require_tree` requires all the nested files in a directory. Its glob equivalent is `path/**/*`.

    //= require_tree "./public"

[Validate]