Parent

Sprockets::DirectiveProcessor

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)

Constants

HEADER_PATTERN

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

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

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

Public Instance Methods

directives() click to toggle source

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"]]
     # File lib/sprockets/directive_processor.rb, line 125
125:     def directives
126:       @directives ||= header.lines.each_with_index.map { |line, index|
127:         if directive = line[DIRECTIVE_PATTERN, 1]
128:           name, *args = Shellwords.shellwords(directive)
129:           if respond_to?("process_#{name}_directive", true)
130:             [index + 1, name, *args]
131:           end
132:         end
133:       }.compact
134:     end
evaluate(context, locals, &block) click to toggle source

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.

     # File lib/sprockets/directive_processor.rb, line 91
 91:     def evaluate(context, locals, &block)
 92:       @context = context
 93: 
 94:       @result = ""
 95:       @has_written_body = false
 96: 
 97:       process_directives
 98:       process_source
 99: 
100:       @result
101:     end
prepare() click to toggle source
    # File lib/sprockets/directive_processor.rb, line 74
74:     def prepare
75:       @pathname = Pathname.new(file)
76: 
77:       @header = data[HEADER_PATTERN, 0] || ""
78:       @body   = $' || data
79:       # Ensure body ends in a new line
80:       @body  += "\n" if @body != "" && @body !~ /\n\Z/
81: 
82:       @included_pathnames = []
83:       @compat             = false
84:     end
processed_header() click to toggle source

Returns the header String with any directives stripped.

     # File lib/sprockets/directive_processor.rb, line 104
104:     def processed_header
105:       lineno = 0
106:       @processed_header ||= header.lines.map { |line|
107:         lineno += 1
108:         # Replace directive line with a clean break
109:         directives.assoc(lineno) ? "\n" : line
110:       }.join.chomp
111:     end
processed_source() click to toggle source

Returns the source String with any directives stripped.

     # File lib/sprockets/directive_processor.rb, line 114
114:     def processed_source
115:       @processed_source ||= processed_header + body
116:     end

Protected Instance Methods

compat?() click to toggle source

Checks if Sprockets 1.x compat mode enabled

     # File lib/sprockets/directive_processor.rb, line 367
367:       def compat?
368:         @compat
369:       end
constants() click to toggle source

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

     # File lib/sprockets/directive_processor.rb, line 374
374:       def constants
375:         if compat?
376:           pathname = Pathname.new(context.root_path).join("constants.yml")
377:           stat(pathname) ? YAML.load_file(pathname) : {}
378:         else
379:           {}
380:         end
381:       end
process_compat_directive() click to toggle source

Enable Sprockets 1.x compat mode.

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

    //= compat
     # File lib/sprockets/directive_processor.rb, line 362
362:       def process_compat_directive
363:         @compat = true
364:       end
process_depend_on_asset_directive(path) click to toggle source

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"
     # File lib/sprockets/directive_processor.rb, line 339
339:       def process_depend_on_asset_directive(path)
340:         context.depend_on_asset(path)
341:       end
process_depend_on_directive(path) click to toggle source

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"
     # File lib/sprockets/directive_processor.rb, line 324
324:       def process_depend_on_directive(path)
325:         context.depend_on(path)
326:       end
process_directives() click to toggle source

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)
     # File lib/sprockets/directive_processor.rb, line 162
162:       def process_directives
163:         directives.each do |line_number, name, *args|
164:           context.__LINE__ = line_number
165:           send("process_#{name}_directive", *args)
166:           context.__LINE__ = nil
167:         end
168:       end
process_include_directive(path) click to toggle source

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

    //= include "header"
     # File lib/sprockets/directive_processor.rb, line 246
246:       def process_include_directive(path)
247:         pathname = context.resolve(path)
248:         context.depend_on_asset(pathname)
249:         included_pathnames << pathname
250:       end
process_provide_directive(path) click to toggle source

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

     # File lib/sprockets/directive_processor.rb, line 386
386:       def process_provide_directive(path)
387:       end
process_require_directive(path) click to toggle source

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"
     # File lib/sprockets/directive_processor.rb, line 206
206:       def process_require_directive(path)
207:         if @compat
208:           if path =~ /<([^>]+)>/
209:             path = $1
210:           else
211:             path = "./#{path}" unless relative?(path)
212:           end
213:         end
214: 
215:         context.require_asset(path)
216:       end
process_require_directory_directive(path = ".") click to toggle source

`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"
     # File lib/sprockets/directive_processor.rb, line 258
258:       def process_require_directory_directive(path = ".")
259:         if relative?(path)
260:           root = pathname.dirname.join(path).expand_path
261: 
262:           unless (stats = stat(root)) && stats.directory?
263:             raise ArgumentError, "require_directory argument must be a directory"
264:           end
265: 
266:           context.depend_on(root)
267: 
268:           entries(root).each do |pathname|
269:             pathname = root.join(pathname)
270:             if pathname.to_s == self.file
271:               next
272:             elsif context.asset_requirable?(pathname)
273:               context.require_asset(pathname)
274:             end
275:           end
276:         else
277:           # The path must be relative and start with a `./`.
278:           raise ArgumentError, "require_directory argument must be a relative path"
279:         end
280:       end
process_require_self_directive() click to toggle source

`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 .
     */
     # File lib/sprockets/directive_processor.rb, line 229
229:       def process_require_self_directive
230:         if @has_written_body
231:           raise ArgumentError, "require_self can only be called once per source file"
232:         end
233: 
234:         context.require_asset(pathname)
235:         process_source
236:         included_pathnames.clear
237:         @has_written_body = true
238:       end
process_require_tree_directive(path = ".") click to toggle source

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

    //= require_tree "./public"
     # File lib/sprockets/directive_processor.rb, line 287
287:       def process_require_tree_directive(path = ".")
288:         if relative?(path)
289:           root = pathname.dirname.join(path).expand_path
290: 
291:           unless (stats = stat(root)) && stats.directory?
292:             raise ArgumentError, "require_tree argument must be a directory"
293:           end
294: 
295:           context.depend_on(root)
296: 
297:           each_entry(root) do |pathname|
298:             if pathname.to_s == self.file
299:               next
300:             elsif stat(pathname).directory?
301:               context.depend_on(pathname)
302:             elsif context.asset_requirable?(pathname)
303:               context.require_asset(pathname)
304:             end
305:           end
306:         else
307:           # The path must be relative and start with a `./`.
308:           raise ArgumentError, "require_tree argument must be a relative path"
309:         end
310:       end
process_source() click to toggle source
     # File lib/sprockets/directive_processor.rb, line 170
170:       def process_source
171:         unless @has_written_body || processed_header.empty?
172:           @result << processed_header << "\n"
173:         end
174: 
175:         included_pathnames.each do |pathname|
176:           @result << context.evaluate(pathname)
177:         end
178: 
179:         unless @has_written_body
180:           @result << body
181:         end
182: 
183:         if compat? && constants.any?
184:           @result.gsub!(/<%=(.*?)%>/) { constants[$1.strip] }
185:         end
186:       end
process_stub_directive(path) click to toggle source

Allows dependency to be excluded from the asset bundle.

The `path` must be a valid asset and may or may not already be part of the bundle. Once stubbed, it is blacklisted and can’t be brought back by any other `require`.

    //= stub "jquery"
     # File lib/sprockets/directive_processor.rb, line 351
351:       def process_stub_directive(path)
352:         context.stub_asset(path)
353:       end

Private Instance Methods

each_entry(root, &block) click to toggle source
     # File lib/sprockets/directive_processor.rb, line 402
402:       def each_entry(root, &block)
403:         context.environment.each_entry(root, &block)
404:       end
entries(path) click to toggle source
     # File lib/sprockets/directive_processor.rb, line 398
398:       def entries(path)
399:         context.environment.entries(path)
400:       end
relative?(path) click to toggle source
     # File lib/sprockets/directive_processor.rb, line 390
390:       def relative?(path)
391:         path =~ /^\.($|\.?\/)/
392:       end
stat(path) click to toggle source
     # File lib/sprockets/directive_processor.rb, line 394
394:       def stat(path)
395:         context.environment.stat(path)
396:       end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.