Skip to content
This repository
file 348 lines (314 sloc) 10.87 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347
require 'pathname'
require 'set'
require 'shellwords'
require 'yaml'

module Sprockets
  # 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"
  # */
  #
  # 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)
  #
  class DirectiveProcessor
    # 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.
    #
    HEADER_PATTERN = /
\A (
(?m:\s*) (
(\/\* (?m:.*?) \*\/) |
(\#\#\# (?m:.*?) \#\#\#) |
(\/\/ .* \n?)+ |
(\# .* \n?)+
)
)+
/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"
    #
    DIRECTIVE_PATTERN = /
^ \W* = \s* (\w+.*?) (\*\/)? $
/x

    def self.call(input)
      new.call(input)
    end

    def call(input)
      @environment = input[:environment]
      @filename = input[:filename]
      @base_path = Pathname.new(@filename).dirname
      @content_type = input[:content_type]

      data = input[:data]
      @header = data[HEADER_PATTERN, 0] || ""
      @body = $' || data
      # Ensure body ends in a new line
      @body += "\n" if @body != "" && @body !~ /\n\Z/m

      @result = ""
      @result.force_encoding(@body.encoding)

      @has_written_body = false

      @required_paths = []
      @stubbed_assets = Set.new
      @dependency_paths = Set.new
      @dependency_assets = Set.new

      process_directives
      process_source

      {
        data: @result,
        required_paths: @required_paths,
        stubbed_assets: @stubbed_assets,
        dependency_paths: @dependency_paths,
        dependency_assets: @dependency_assets
      }
    end

    # Returns the header String with any directives stripped.
    def processed_header
      lineno = 0
      @processed_header ||= @header.lines.map { |line|
        lineno += 1
        # Replace directive line with a clean break
        directives.assoc(lineno) ? "\n" : line
      }.join.chomp
    end

    # 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"]]
    #
    def directives
      @directives ||= @header.lines.each_with_index.map { |line, index|
        if directive = line[DIRECTIVE_PATTERN, 1]
          name, *args = Shellwords.shellwords(directive)
          if respond_to?("process_#{name}_directive", true)
            [index + 1, name, *args]
          end
        end
      }.compact
    end

    protected
      # 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)
      #
      def process_directives
        directives.each do |line_number, name, *args|
          begin
            send("process_#{name}_directive", *args)
          rescue Exception => e
            e.set_backtrace(["#{@filename}:#{line_number}"] + e.backtrace)
            raise e
          end
        end
      end

      def process_source
        unless @has_written_body || processed_header.empty?
          @result << processed_header << "\n"
        end

        unless @has_written_body
          @result << @body
        end
      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"
      #
      def process_require_directive(path)
        filename = resolve(path, content_type: @content_type)
        @dependency_assets << filename
        @required_paths << filename
      end

      # `require_self` causes the body of the current file to be inserted
      # before any subsequent `require` 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 .
      # */
      #
      def process_require_self_directive
        if @has_written_body
          raise ArgumentError, "require_self can only be called once per source file"
        end

        @required_paths << @filename
        process_source
        @has_written_body = true
      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"
      #
      def process_require_directory_directive(path = ".")
        if relative?(path)
          root = @base_path.join(path).expand_path

          unless (stats = @environment.stat(root)) && stats.directory?
            raise ArgumentError, "require_directory argument must be a directory"
          end

          @dependency_paths << root.to_s

          @environment.entries(root).each do |pathname|
            pathname = root.join(pathname)
            stat = @environment.stat(pathname)
            content_type = @environment.content_type_of(pathname)

            if pathname.to_s == @filename
              next
            elsif stat.file? && content_type == @content_type
              @dependency_assets << pathname.to_s
              @required_paths << pathname.to_s
            end
          end
        else
          # The path must be relative and start with a `./`.
          raise ArgumentError, "require_directory argument must be a relative path"
        end
      end

      # `require_tree` requires all the nested files in a directory.
      # Its glob equivalent is `path/**/*`.
      #
      # //= require_tree "./public"
      #
      def process_require_tree_directive(path = ".")
        if relative?(path)
          root = @base_path.join(path).expand_path

          unless (stats = @environment.stat(root)) && stats.directory?
            raise ArgumentError, "require_tree argument must be a directory"
          end

          @dependency_paths << root.to_s

          required_paths = []
          @environment.recursive_stat(root).each do |pathname, stat|
            content_type = @environment.content_type_of(pathname)

            if pathname.to_s == @filename
              next
            elsif stat.directory?
              @dependency_paths << pathname.to_s
            elsif stat.file? && content_type == @content_type
              required_paths << pathname
            end
          end
          required_paths.sort_by(&:to_s).each do |pathname|
            @dependency_assets << pathname.to_s
            @required_paths << pathname.to_s
          end
        else
          # The path must be relative and start with a `./`.
          raise ArgumentError, "require_tree argument must be a relative path"
        end
      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"
      #
      def process_depend_on_directive(path)
        @dependency_paths << resolve(path)
      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"
      #
      def process_depend_on_asset_directive(path)
        @dependency_assets << resolve(path)
      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"
      #
      def process_stub_directive(path)
        @stubbed_assets << resolve(path, content_type: @content_type)
      end

    private
      def relative?(path)
        path =~ /^\.($|\.?\/)/
      end

      def resolve(path, options = {})
        @environment.resolve(path, options.merge(base_path: @base_path))
      end
  end
end
Something went wrong with that request. Please try again.