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)
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.
Directives are denoted by a `=` followed by the name, then argument list.
A few different styles are allowed:
// =require foo //= require foo //= require "foo"
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
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
# 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
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
Checks if Sprockets 1.x compat mode enabled
# File lib/sprockets/directive_processor.rb, line 367 367: def compat? 368: @compat 369: end
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
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
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
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
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
`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
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
`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
`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
`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
# 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
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
# File lib/sprockets/directive_processor.rb, line 402 402: def each_entry(root, &block) 403: context.environment.each_entry(root, &block) 404: end
# File lib/sprockets/directive_processor.rb, line 398 398: def entries(path) 399: context.environment.entries(path) 400: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.