liquid-autoescape 0.2.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    N2JlOGEyMGM1MWQ0NWRhMjJhN2NmMjg0NjFlMjY1NWQ2MTZjNjM0MQ==
+  data.tar.gz: !binary |-
+    YTFmMDdkMGQxMWQyMzVmZmU3ZWQ5MWNmZjEwNjZlYzZlNTA2NmE4YQ==
+SHA512:
+  metadata.gz: !binary |-
+    YWRmOWZlMzRmNDY1MDgzZjk1OTkyOWRiMzc5YjE3Y2Y4YjM1NDY4YTc4MTA2
+    MWQ1OWM2NTZmMThlN2NiMzNkOTUxMGNmMjdmYWJlNTY0NGRhMDYzYjkyNzBm
+    MTc1MjljN2M2ODg5MzE0NjMwYWIyNTY4Y2YxZjZhOWM2Y2RkYzY=
+  data.tar.gz: !binary |-
+    MzQ3YmQ0OWFkMWNlMzMyZjA1N2NhZjRmMjcxNTAwYjdiNGE0NDM2Y2VmYjIz
+    ODk1ZTQ1M2M1ZjQzZTczMTQ2N2IwMWE5NzMyOGFjODRhM2ZlZDkxYzMxNjdk
+    M2ZjZDc1MjhiNDFhNTVmZjk2YTM4NDI5OTc1MTBjNGQ5MDdkOWM=

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Within3
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,165 @@
+# Liquid Autoescape
+
+[![Build Status](https://travis-ci.org/Within3/liquid-autoescape.svg)](https://travis-ci.org/Within3/liquid-autoescape)
+
+This adds an `{% autoescape %}` block tag to Liquid that causes all variables
+referenced within it to be escaped for display in an HTML context.
+
+## Requirements
+
+* Ruby 1.9.3+
+* Liquid 2 or 3
+
+## Basic Usage
+
+To enable the `{% autoescape %}` tag in your Liquid templates, load the tag's
+files in any Ruby file that will be executed before rendering templates using
+the following line:
+
+```ruby
+require "liquid/autoescape"
+```
+
+With the tag loaded, you can escape all variables in a Liquid template by
+wrapping them in an `{% autoescape %}` tag.
+
+```liquid
+{% autoescape %}
+  {{ variable_one }}
+  {{ variable_two }}
+{% endautoescape %}
+```
+
+To prevent a variable contained in an `{% autoescape %}` block from being
+escaped, use the `skip_escape` filter.
+
+```liquid
+{% autoescape %}
+  Escaped: {{ untrusted_content }}
+  Not Escaped: {{ trusted_content | skip_escape }}
+{% endautoescape %}
+```
+
+## Advanced Usage
+
+Autoescaping can be customized to work better with your environment via a
+Ruby-level configuration object.  To configure autoescaping, use the `config`
+object exposed by `Liquid::Autoescape.configure` in any Ruby file loaded before
+templates are rendered.
+
+```ruby
+require "liquid/autoescape"
+
+Liquid::Autoescape.configure do |config|
+  ...
+end
+```
+
+The autoescape options that can be configured are detailed below.
+
+### Trusted Filters
+
+If you are using custom Liquid filters that always generate trusted HTML, you
+can add them to the list of trusted filters.  Any variables that are passed
+through a trusted filter will not be escaped.
+
+```ruby
+Liquid::Autoescape.configure do |config|
+  config.trusted_filters << :generate_markup
+end
+```
+
+```liquid
+{% autoescape %}
+  Escaped: {{ variable | downcase }}
+  Not Escaped: {{ variable | generate_markup }}
+{% endautoescape %}
+```
+
+### Custom Exemptions
+
+If there are complex conditions under which a variable should not be escaped,
+you can describe these conditions by creating custom exemptions.  Exemptions are
+functions that receive an instance of `Liquid::Autoescape::TemplateVariable`
+that represents a Liquid variable as used in a template and return a boolean
+value indicating whether the variable is exempt from escaping.
+
+#### Adding Individual Exemptions
+
+To quickly add a single exemption, use code similar to the following:
+
+```ruby
+Liquid::Autoescape.configure do |config|
+  config.exemptions.add do |variable|
+    ...
+  end
+end
+```
+
+#### Importing Exemption Functions
+
+If you prefer to define exemptions as instance methods on a module, you can
+import those methods using code similar to the following:
+
+```ruby
+module MyExemptions
+
+  def exemption_one(variable)
+    ...
+  end
+
+  def exemption_two(variable)
+    ...
+  end
+
+end
+
+Liquid::Autoescape.configure do |config|
+  config.exemptions.import(MyExemptions)
+end
+```
+
+The names of the module methods have no bearing on determining exemptions, so
+they can be whatever you want them to be.
+
+#### Exemption Conditions
+
+As mentioned above, each exemption function is passed an object that describes a
+Liquid variable as used in a template.  This object exposes the variable's name,
+as well as a list of any filters that it uses. These values can be used by each
+exemption function to determine whether a variable should be exempt from
+autoescaping, as shown by the code below:
+
+```ruby
+Liquid::Autoescape.configure do |config|
+  config.exemptions.add do |variable|
+    variable.name == "var_one" && variable.filters.include?(:downcase)
+  end
+end
+```
+
+```liquid
+{% autoescape %}
+  Escaped: {{ var_one }}
+  Escaped: {{ var_two | downcase }}
+  Not Escaped: {{ var_one | downcase }}
+{% endautoescape %}
+```
+
+### Global Mode
+
+Autoescaping can be globally enabled, which will cause all variables in all
+Liquid templates to be escaped, removing the need to use the `{% autoescape %}`
+tag.  Trusted filters and custom exemptions still apply in global mode, so there
+is always the ability to mark a variable as exempt from escaping.
+
+```ruby
+Liquid::Autoescape.configure do |config|
+  config.global = true
+end
+```
+
+```liquid
+Escaped: {{ variable }}
+Not Escaped: {{ variable | skip_escape }}
+```

data/lib/liquid/autoescape.rb

@@ -0,0 +1,33 @@
+require "liquid/autoescape/configuration"
+require "liquid/autoescape/filters"
+require "liquid/autoescape/tags/autoescape"
+
+module Liquid
+  module Autoescape
+
+    # The context variable that stores the autoescape state
+    #
+    # @private
+    ENABLED_FLAG = "liquid_autoescape_enabled"
+
+    # Configure Liquid autoescaping
+    #
+    # @yieldparam [Liquid::Autoescape::Configuration] config The autoescape configuration
+    def self.configure
+      yield(configuration)
+    end
+
+    # Restore the configuration's default values
+    def self.reconfigure
+      configuration.reset
+    end
+
+    # The current autoescape configuration
+    #
+    # @return [Liquid::Autoescape::Configuration]
+    def self.configuration
+      @configuration ||= Configuration.new
+    end
+
+  end
+end

data/lib/liquid/autoescape/configuration.rb

@@ -0,0 +1,41 @@
+require "liquid/autoescape/core_exemptions"
+require "liquid/autoescape/exemption_list"
+
+module Liquid
+  module Autoescape
+
+    # A configuration file for setting autoescape options
+    class Configuration
+
+      # @return [Liquid::Autoescape::ExemptionList] The list of custom exemptions
+      attr_reader :exemptions
+
+      # @return [Boolean] Whether global mode is enabled
+      attr_writer :global
+
+      # @return [Array<Symbol>] The list of trusted filter names
+      attr_accessor :trusted_filters
+
+      # Create a new configuration object with default values
+      def initialize
+        reset
+      end
+
+      # Reset the configuration's values to their defaults
+      def reset
+        @exemptions = ExemptionList.from_module(CoreExemptions)
+        @global = false
+        @trusted_filters = []
+      end
+
+      # Whether global mode is enabled
+      #
+      # @return [Boolean]
+      def global?
+        @global
+      end
+
+    end
+
+  end
+end

data/lib/liquid/autoescape/core_exemptions.rb

@@ -0,0 +1,40 @@
+require "liquid/autoescape"
+
+module Liquid
+  module Autoescape
+
+    # Core exemptions for all Liquid variables
+    #
+    # These exemptions are used to build the default exemption list referenced
+    # when determining whether variables should be escaped.
+    module CoreExemptions
+
+      # A list of all filters that influence escaping
+      ESCAPING_FILTERS = [:escape, :skip_escape]
+
+      # Determine whether a Liquid variable uses an escaping filter
+      #
+      # This accounts for both filters that are known to escape the variable
+      # and those that should prevent the variable from being escaped.
+      #
+      # @param [Liquid::Autoescape::TemplateVariable] A Liquid variable used in a template
+      # @return [Boolean]
+      def uses_escaping_filter?(variable)
+        !(variable.filters & ESCAPING_FILTERS).empty?
+      end
+
+      # Determine whether a Liquid variable uses a trusted filters
+      #
+      # Trusted filters can be configured by the user to include any custom
+      # filters that are known to generate already escaped markup.
+      #
+      # @param [Liquid::Autoescape::TemplateVariable] A Liquid variable used in a template
+      # @return [Boolean]
+      def uses_trusted_filter?(variable)
+        !(variable.filters & Autoescape.configuration.trusted_filters).empty?
+      end
+
+    end
+
+  end
+end

data/lib/liquid/autoescape/errors.rb

@@ -0,0 +1,11 @@
+module Liquid
+  module Autoescape
+
+    # The base error from which all other autoescape errors inherit
+    class AutoescapeError < StandardError; end
+
+    # An error raised when an exemption encounters an issue
+    class ExemptionError < AutoescapeError; end
+
+  end
+end

data/lib/liquid/autoescape/exemption.rb

@@ -0,0 +1,47 @@
+require "liquid/autoescape/errors"
+
+module Liquid
+  module Autoescape
+
+    # An exemption that may apply to a Liquid template variable
+    #
+    # Exemptions are created from functions that accept a template variable and
+    # and return a boolean value indicating whether or not the variable is
+    # exempt from autoescaping.
+    #
+    # @example An exemption based on a variable's name
+    #   exemption = Exemption.new do |variable|
+    #     variable.name == "safe_variable"
+    #   end
+    #
+    # @example An exemption based on a variable's filters
+    #   exemption = Exemption.new do |variable|
+    #     variable.filters.include?(:trusted_filter)
+    #   end
+    class Exemption
+
+      # Create a new autoescaping exemption
+      #
+      # This requires a filter function to be provided that will be passed a
+      # +TemplateVariable+ instance that it can use to return a boolean
+      # indicating whether the exemption applies to the variable.
+      #
+      # @param [Proc] filter A filter function to use for calculating the exemption
+      # @raise [Liquid::Autoescape::ExemptionError] if a filter function is not provided
+      def initialize(&filter)
+        raise ExemptionError, "You must provide an exemption with a block that determines if an exemption applies" unless block_given?
+        @filter = filter
+      end
+
+      # Determine whether the exemption applies to a Liquid variable
+      #
+      # @param [Liquid::Autoescape::TemplateVariable] A Liquid variable used in a template
+      # @return [Boolean] Whether the exemption applies to the variable
+      def applies?(variable)
+        @filter.call(variable)
+      end
+
+    end
+
+  end
+end

data/lib/liquid/autoescape/exemption_list.rb

@@ -0,0 +1,106 @@
+require "liquid/autoescape"
+require "liquid/autoescape/exemption"
+
+module Liquid
+  module Autoescape
+
+    # A list of exemptions that may apply to template variables
+    #
+    # Exemption lists manage one or more exemptions, and determine whether any
+    # managed exemptions applies to a template variable.  Exemptions can be
+    # added as individual filter functions, or can be imported in bulk from a
+    # module.
+    #
+    # @example Adding exemption functions
+    #   exemptions = ExemptionList.new
+    #   ExemptionList.add { |variable| variable.name == "one" }
+    #   ExemptionList.add { |variable| variable.name == "two" }
+    #
+    # @example Importing exemptions from a module
+    #   module MyExemptions
+    #
+    #     def exemption_one(variable)
+    #       variable.name == "one"
+    #     end
+    #
+    #     def exemption_two(variable)
+    #       variable.name == "two"
+    #     end
+    #
+    #   end
+    #
+    #   exemptions = ExemptionList.new
+    #   exemptions.import(MyExemptions)
+    #
+    class ExemptionList
+
+      # Create an exemption list from a module's instance methods
+      #
+      # @param [Module] source The module providing exemptions as methods
+      # @return [Liquid::Autoescape::ExemptionList]
+      def self.from_module(source)
+        exemptions = new
+        exemptions.import(source)
+        exemptions
+      end
+
+      # Create a new exemption list
+      def initialize
+        @exemptions = []
+      end
+
+      # Add a single filter function to use as an exemption
+      #
+      # @param [Proc] filter A filter function to use as an exemption
+      # @return [Liquid::Autoescape::ExemptionList] The updated exemption list
+      def add(&filter)
+        @exemptions << Exemption.new(&filter)
+        self
+      end
+
+      # Add all instance methods of a module as exemptions
+      #
+      # @param [Module] source The module providing exemptions as methods
+      # @return [Liquid::Autoescape::ExemptionList] The updated exemption list
+      def import(source)
+        container = Module.new { extend source }
+        exemptions = source.instance_methods(false)
+        exemptions.each do |exemption|
+          @exemptions << Exemption.new(&container.method(exemption))
+        end
+        self
+      end
+
+      # Determine whether any of the exemptions apply to a Liquid variable
+      #
+      # @param [Liquid::Autoescape::TemplateVariable] variable A Liquid variable used in a template
+      # @return [Boolean] Whether any of the exemptions apply to the variable
+      def applies?(variable)
+        @exemptions.each do |exemption|
+          if exemption.applies?(variable)
+            return true
+          end
+        end
+        false
+      end
+
+      alias_method :apply?, :applies?
+
+      # Whether the exemption list has exemptions
+      #
+      # @return [Boolean]
+      def populated?
+        !@exemptions.empty?
+      end
+
+      # The number of exemptions in the list
+      #
+      # @return [Integer]
+      def size
+        @exemptions.size
+      end
+
+    end
+
+  end
+end