i18n-processes 0.1.0

data/lib/i18n/processes/scanners/pattern_scanner.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'i18n/processes/scanners/file_scanner'
+require 'i18n/processes/scanners/relative_keys'
+require 'i18n/processes/scanners/occurrence_from_position'
+require 'i18n/processes/scanners/ruby_key_literals'
+
+module I18n::Processes::Scanners
+  # Scan for I18n.t usages using a simple regular expression.
+  class PatternScanner < FileScanner
+    include RelativeKeys
+    include OccurrenceFromPosition
+    include RubyKeyLiterals
+
+    TRANSLATE_CALL_RE = /(?<=^|[^\w'\-.]|[^\w'\-]I18n\.|I18n\.)t(?:ranslate)?/
+    IGNORE_LINES = {
+      'opal' => /^\s*#(?!\si18n-tasks-use)/,
+      'haml' => /^\s*-\s*#(?!\si18n-tasks-use)/,
+      'slim' => %r{^\s*(?:-#|/)(?!\si18n-tasks-use)},
+      'coffee' => /^\s*#(?!\si18n-tasks-use)/,
+      'erb' => /^\s*<%\s*#(?!\si18n-tasks-use)/
+    }.freeze
+
+    def initialize(**args)
+      super
+      @translate_call_re = config[:translate_call].present? ? Regexp.new(config[:translate_call]) : TRANSLATE_CALL_RE
+      @pattern = config[:pattern].present? ? Regexp.new(config[:pattern]) : default_pattern
+      @ignore_lines_res = (config[:ignore_lines] || IGNORE_LINES).each_with_object({}) do |(ext, re), h|
+        h[ext.to_s] = Regexp.new(re)
+      end
+    end
+
+    protected
+
+    # Extract i18n keys from file based on the pattern which must capture the key literal.
+    # @return [Array<[key, Results::Occurrence]>] each occurrence found in the file
+    def scan_file(path)
+      keys = []
+      text = read_file(path)
+      text.scan(@pattern) do |match|
+        src_pos = Regexp.last_match.offset(0).first
+        location = occurrence_from_position(path, text, src_pos, raw_key: strip_literal(match[0]))
+        next if exclude_line?(location.line, path)
+        key = match_to_key(match, path, location)
+        next unless key
+        key += ':' if key.end_with?('.')
+        next unless valid_key?(key)
+        keys << [key, location]
+      end
+      keys
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      raise ::I18n::Processes::CommandError.new(e, "Error scanning #{path}: #{e.message}")
+    end
+
+    # @param [MatchData] match
+    # @param [String] path
+    # @return [String] full absolute key name
+    def match_to_key(match, path, location)
+      absolute_key(strip_literal(match[0]), path,
+                   calling_method: -> { closest_method(location) if key_relative_to_method?(path) })
+    end
+
+    def exclude_line?(line, path)
+      re = @ignore_lines_res[File.extname(path)[1..-1]]
+      re && re =~ line
+    end
+
+    VALID_KEY_RE_DYNAMIC = /^(#{VALID_KEY_CHARS}|[:\#{@}\[\]])+$/
+
+    def valid_key?(key)
+      if @config[:strict]
+        super(key)
+      else
+        key =~ VALID_KEY_RE_DYNAMIC
+      end
+    end
+
+    def key_relative_to_method?(path)
+      /controllers|mailers/ =~ path
+    end
+
+    def closest_method(occurrence)
+      method = File.readlines(occurrence.path, encoding: 'UTF-8')
+                   .first(occurrence.line_num - 1).reverse_each.find { |x| x =~ /\bdef\b/ }
+      method && method.strip.sub(/^def\s*/, '').sub(/[\(\s;].*$/, '')
+    end
+
+    # This method only exists for backwards compatibility with monkey-patches and plugins
+    attr_reader :translate_call_re
+
+    def default_pattern
+      # capture only the first argument
+      /
+      #{translate_call_re} [\( ] \s* (?# fn call begin )
+      (#{first_argument_re})         (?# capture the first argument)
+      /x
+    end
+
+    def first_argument_re
+      literal_re
+    end
+  end
+end

data/lib/i18n/processes/scanners/pattern_with_scope_scanner.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'i18n/processes/scanners/pattern_scanner'
+
+module I18n::Processes::Scanners
+  # Scans for I18n.t(key, scope: ...) usages
+  # both scope: "literal", and scope: [:array, :of, 'literals'] forms are supported
+  # Caveat: scope is only detected when it is the first argument
+  class PatternWithScopeScanner < PatternScanner
+    protected
+
+    def default_pattern
+      # capture the first argument and scope argument if present
+      /#{super}
+      (?: \s*,\s* #{scope_arg_re} )? (?# capture scope in second argument )
+      /x
+    end
+
+    # Given
+    # @param [MatchData] match
+    # @param [String] path
+    # @return [String] full absolute key name with scope resolved if any
+    def match_to_key(match, path, location)
+      key   = super
+      scope = match[1]
+      if scope
+        scope_parts = extract_literal_or_array_of_literals(scope)
+        return nil if scope_parts.nil? || scope_parts.empty?
+        "#{scope_parts.join('.')}.#{key}"
+      else
+        key unless match[0] =~ /\A\w/
+      end
+    end
+
+    # parse expressions with literals and variable
+    def first_argument_re
+      /(?: (?: #{literal_re} ) | #{expr_re} )/x
+    end
+
+    # strip literals, convert expressions to #{interpolations}
+    def strip_literal(val)
+      if val =~ /\A[\w@]/
+        "\#{#{val}}"
+      else
+        super(val)
+      end
+    end
+
+    # scope: literal or code expression or an array of these
+    def scope_arg_re
+      /(?:
+         :scope\s*=>\s* | (?# :scope => :home )
+         scope:\s*        (?#    scope: :home )
+        ) (\[[^\n)%#]*\]|[^\n)%#,]*)/x
+    end
+
+    # match a limited subset of code expressions (no parenthesis, commas, etc)
+    def expr_re
+      /[\w@.&|\s?!]+/
+    end
+
+    # extract literal or array of literals
+    # returns nil on any other input
+    # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+    def extract_literal_or_array_of_literals(s)
+      literals = []
+      braces_stack = []
+      acc = []
+      consume_literal = proc do
+        acc_str = acc.join
+        if acc_str =~ literal_re
+          literals << strip_literal(acc_str)
+          acc = []
+        else
+          return nil
+        end
+      end
+      s.each_char.with_index do |c, i|
+        if c == '['
+          return nil unless braces_stack.empty?
+          braces_stack.push(i)
+        elsif c == ']'
+          break
+        elsif c == ','
+          consume_literal.call
+          break if braces_stack.empty?
+        elsif c =~ VALID_KEY_CHARS || /['":]/ =~ c
+          acc << c
+        elsif c != ' '
+          return nil
+        end
+      end
+      consume_literal.call unless acc.empty?
+      literals
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+  end
+end

data/lib/i18n/processes/scanners/relative_keys.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module I18n::Processes
+  module Scanners
+    module RelativeKeys
+      # @param key [String] relative i18n key (starts with a .)
+      # @param path [String] path to the file containing the key
+      # @param roots [Array<String>] paths to relative roots
+      # @param calling_method [#call, Symbol, String, false, nil]
+      # @return [String] absolute version of the key
+      def absolute_key(key, path, roots: config[:relative_roots], calling_method: nil)
+        return key unless key.start_with?(DOT)
+        fail 'roots argument is required' unless roots.present?
+        normalized_path = File.expand_path(path)
+        (root = path_root(normalized_path, roots)) ||
+          fail(CommandError, "Cannot resolve relative key \"#{key}\".\n" \
+                              "Set search.relative_roots in config/i18n-processes.yml (currently #{roots.inspect})")
+        normalized_path.sub!(root, '')
+        "#{prefix(normalized_path, calling_method: calling_method)}#{key}"
+      end
+
+      private
+
+      DOT = '.'
+
+      # Detect the appropriate relative path root
+      # @param [String] path /full/path
+      # @param [Array<String>] roots array of full paths
+      # @return [String] the closest ancestor root for path, with a trailing {File::SEPARATOR}.
+      def path_root(path, roots)
+        roots.map do |p|
+          File.expand_path(p) + File::SEPARATOR
+        end.sort.reverse_each.detect do |root|
+          path.start_with?(root)
+        end
+      end
+
+      # @param normalized_path [String] path/relative/to/a/root
+      # @param calling_method [#call, Symbol, String, false, nil]
+      def prefix(normalized_path, calling_method: nil)
+        file_key       = normalized_path.gsub(%r{(\.[^/]+)*$}, '').tr(File::SEPARATOR, DOT)
+        calling_method = calling_method.call if calling_method.respond_to?(:call)
+        if calling_method && calling_method.present?
+          # Relative keys in mailers have a `_mailer` infix, but relative keys in controllers do not have one:
+          "#{file_key.sub(/_controller$/, '')}.#{calling_method}"
+        else
+          # Remove _ prefix from partials
+          file_key.gsub(/\._/, DOT)
+        end
+      end
+    end
+  end
+end

data/lib/i18n/processes/scanners/results/key_occurrences.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'i18n/processes/scanners/results/occurrence'
+
+module I18n::Processes::Scanners::Results
+  # A scanned key and all its occurrences.
+  #
+  # @note This is a value type. Equality and hash code are determined from the attributes.
+  class KeyOccurrences
+    # @return [String] the key.
+    attr_reader :key
+
+    # @return [Array<Occurrence>] the key's occurrences.
+    attr_reader :occurrences
+
+    def initialize(key:, occurrences:)
+      @key         = key
+      @occurrences = occurrences
+    end
+
+    def ==(other)
+      other.key == @key && other.occurrences == @occurrences
+    end
+
+    def eql?(other)
+      self == other
+    end
+
+    def hash
+      [@key, @occurrences].hash
+    end
+
+    def inspect
+      "KeyOccurrences(#{key.inspect}, [#{occurrences.map(&:inspect).join(', ')}])"
+    end
+
+    # Merge {KeyOccurrences} in an {Enumerable<KeyOccurrences>} so that in the resulting {Array<KeyOccurrences>}:
+    # * Each key occurs only once.
+    # * {Occurrence}s from multiple instances of the key are merged.
+    # * The order of keys is preserved, occurrences are ordered by {Occurrence#path}.
+    # @param keys_occurrences [Enumerable<KeyOccurrences>]
+    # @return [Array<KeyOccurrences>] a new array.
+    def self.merge_keys(keys_occurrences)
+      keys_occurrences.each_with_object({}) do |key_occurrences, results_by_key|
+        (results_by_key[key_occurrences.key] ||= []) << key_occurrences.occurrences
+      end.map do |key, all_occurrences|
+        occurrences = all_occurrences.flatten(1)
+        occurrences.sort_by!(&:path)
+        occurrences.uniq!
+        new(key: key, occurrences: occurrences)
+      end
+    end
+  end
+end

data/lib/i18n/processes/scanners/results/occurrence.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module I18n::Processes
+  module Scanners
+    module Results
+      # The occurrence of some key in a file.
+      #
+      # @note This is a value type. Equality and hash code are determined from the attributes.
+      class Occurrence
+        # @return [String] source path relative to the current working directory.
+        attr_reader :path
+
+        # @return [Integer] count of characters in the file before the occurrence.
+        attr_reader :pos
+
+        # @return [Integer] line number of the occurrence, counting from 1.
+        attr_reader :line_num
+
+        # @return [Integer] position of the start of the occurrence in the line, counting from 1.
+        attr_reader :line_pos
+
+        # @return [String] the line of the occurrence, excluding the last LF or CRLF.
+        attr_reader :line
+
+        # @return [String, nil] the value of the `default:` argument of the translate call.
+        attr_reader :default_arg
+
+        # @return [String, nil] the raw key (for relative keys and references)
+        attr_accessor :raw_key
+
+        # @param path        [String]
+        # @param pos         [Integer]
+        # @param line_num    [Integer]
+        # @param line_pos    [Integer]
+        # @param line        [String]
+        # @param raw_key     [String, nil]
+        # @param default_arg [String, nil]
+        # rubocop:disable Metrics/ParameterLists
+        def initialize(path:, pos:, line_num:, line_pos:, line:, raw_key: nil, default_arg: nil)
+          @path        = path
+          @pos         = pos
+          @line_num    = line_num
+          @line_pos    = line_pos
+          @line        = line
+          @raw_key     = raw_key
+          @default_arg = default_arg
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        def inspect
+          "Occurrence(#{@path}:#{@line_num}:#{@line_pos}:#{@pos}:#{@raw_key}:#{@default_arg})"
+        end
+
+        def ==(other)
+          other.path == @path && other.pos == @pos && other.line_num == @line_num && other.line == @line &&
+            other.raw_key == @raw_key && other.default_arg == @default_arg
+        end
+
+        def eql?(other)
+          self == other
+        end
+
+        def hash
+          [@path, @pos, @line_num, @line_pos, @line, @default_arg].hash
+        end
+      end
+    end
+  end
+end

data/lib/i18n/processes/scanners/ruby_ast_call_finder.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'ast'
+require 'set'
+module I18n::Processes::Scanners
+  class RubyAstCallFinder
+    include AST::Processor::Mixin
+
+    # @param receiver_messages [Set<Pair<[nil, AST::Node>, Symbol>>] The receiver-message pairs to look for.
+    def initialize(receiver_messages:)
+      super()
+      @message_receivers = receiver_messages.each_with_object({}) do |(receiver, message), t|
+        (t[message] ||= []) << receiver
+      end
+    end
+
+    # @param root_node [Parser::AST:Node]
+    # @yieldparam send_node [Parser::AST:Node]
+    # @yieldparam method_name [nil, String] the surrounding method's name.
+    def find_calls(root_node, &block)
+      @callback = block
+      process root_node
+    ensure
+      @callback = nil
+    end
+
+    # @param root_node (see #find_calls)
+    # @yieldparam (see #find_calls)
+    # @return [Array<block return values excluding nils>]
+    def collect_calls(root_node)
+      results = []
+      find_calls root_node do |send_node, method_name|
+        result = yield send_node, method_name
+        results << result if result
+      end
+      results
+    end
+
+    def on_def(node)
+      @method_name = node.children[0]
+      handler_missing node
+    ensure
+      @method_name = nil
+    end
+
+    def on_send(send_node)
+      receiver = send_node.children[0]
+      message  = send_node.children[1]
+      valid_receivers = @message_receivers[message]
+      # use `any?` because `include?` checks type equality, but the receiver is a Parser::AST::Node != AST::Node.
+      @callback.call(send_node, @method_name) if valid_receivers && valid_receivers.any? { |r| r == receiver }
+      # always invoke handler_missing to get nested translations in children
+      handler_missing send_node
+      nil
+    end
+
+    def handler_missing(node)
+      node.children.each { |child| process(child) if child.is_a?(::Parser::AST::Node) }
+      nil
+    end
+  end
+end

data/lib/i18n/processes/scanners/ruby_ast_scanner.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require 'i18n/processes/scanners/file_scanner'
+require 'i18n/processes/scanners/relative_keys'
+require 'i18n/processes/scanners/ruby_ast_call_finder'
+require 'parser/current'
+
+# rubocop:disable Metrics/AbcSize,Metrics/BlockNesting,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+# TODO: make this class more readable.
+
+module I18n::Processes::Scanners
+  # Scan for I18n.translate calls using whitequark/parser
+  class RubyAstScanner < FileScanner # rubocop:disable Metrics/ClassLength
+    include RelativeKeys
+    include AST::Sexp
+
+    MAGIC_COMMENT_PREFIX = /\A.\s*i18n-processes-use\s+/
+    RECEIVER_MESSAGES = [nil, AST::Node.new(:const, [nil, :I18n])].product(%i[t translate])
+
+    def initialize(**args)
+      super(args)
+      @parser = ::Parser::CurrentRuby.new
+      @magic_comment_parser = ::Parser::CurrentRuby.new
+      @call_finder = RubyAstCallFinder.new(
+        receiver_messages: config[:receiver_messages] || RECEIVER_MESSAGES
+      )
+    end
+
+    protected
+
+    # Extract all occurrences of translate calls from the file at the given path.
+    #
+    # @return [Array<[key, Results::KeyOccurrence]>] each occurrence found in the file
+    def scan_file(path)
+      @parser.reset
+      ast, comments = @parser.parse_with_comments(make_buffer(path))
+
+      results = @call_finder.collect_calls ast do |send_node, method_name|
+        send_node_to_key_occurrence(send_node, method_name)
+      end
+
+      magic_comments  = comments.select { |comment| comment.text =~ MAGIC_COMMENT_PREFIX }
+      comment_to_node = Parser::Source::Comment.associate_locations(ast, magic_comments).tap do |h|
+        # transform_values is only available in ActiveSupport 4.2+
+        h.each { |k, v| h[k] = v.first }
+      end.invert
+      results + (magic_comments.flat_map do |comment|
+        @parser.reset
+        associated_node = comment_to_node[comment]
+        @call_finder.collect_calls(
+          @parser.parse(make_buffer(path, comment.text.sub(MAGIC_COMMENT_PREFIX, '').split(/\s+(?=t)/).join('; ')))
+        ) do |send_node, _method_name|
+          # method_name is not available at this stage
+          send_node_to_key_occurrence(send_node, nil, location: associated_node || comment.location)
+        end
+      end)
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      raise ::I18n::Processes::CommandError.new(e, "Error scanning #{path}: #{e.message}")
+    end
+
+    # @param send_node [Parser::AST::Node]
+    # @param method_name [Symbol, nil]
+    # @param location [Parser::Source::Map]
+    # @return [nil, [key, Occurrence]] full absolute key name and the occurrence.
+    def send_node_to_key_occurrence(send_node, method_name, location: send_node.loc)
+      if (first_arg_node = send_node.children[2]) &&
+         (key = extract_string(first_arg_node))
+        if (second_arg_node = send_node.children[3]) &&
+           second_arg_node.type == :hash
+          if (scope_node = extract_hash_pair(second_arg_node, 'scope'))
+            scope = extract_string(scope_node.children[1],
+                                   array_join_with: '.', array_flatten: true, array_reject_blank: true)
+            return nil if scope.nil? && scope_node.type != :nil
+            key = [scope, key].join('.') unless scope == ''
+          end
+          default_arg = if (default_arg_node = extract_hash_pair(second_arg_node, 'default'))
+                          extract_string(default_arg_node.children[1])
+                        end
+        end
+        full_key = if send_node.children[0].nil?
+                     # Relative keys only work if called via `t()` but not `I18n.t()`:
+                     absolute_key(key, location.expression.source_buffer.name, calling_method: method_name)
+                   else
+                     key
+                   end
+        [full_key, range_to_occurrence(key, location.expression, default_arg: default_arg)]
+      end
+    end
+
+    # Extract a hash pair with a given literal key.
+    #
+    # @param node [AST::Node] a node of type `:hash`.
+    # @param key [String] node key as a string (indifferent symbol-string matching).
+    # @return [AST::Node, nil] a node of type `:pair` or nil.
+    def extract_hash_pair(node, key)
+      node.children.detect do |child|
+        next unless child.type == :pair
+        key_node = child.children[0]
+        %i[sym str].include?(key_node.type) && key_node.children[0].to_s == key
+      end
+    end
+
+    # If the node type is of `%i(sym str int false true)`, return the value as a string.
+    # Otherwise, if `config[:strict]` is `false` and the type is of `%i(dstr dsym)`,
+    # return the source as if it were a string.
+    #
+    # @param node [Parser::AST::Node]
+    # @param array_join_with [String, nil] if set to a string, arrays will be processed and their elements joined.
+    # @param array_flatten [Boolean] if true, nested arrays are flattened,
+    #     otherwise their source is copied and surrounded by #{}. No effect unless `array_join_with` is set.
+    # @param array_reject_blank [Boolean] if true, empty strings and `nil`s are skipped.
+    #      No effect unless `array_join_with` is set.
+    # @return [String, nil] `nil` is returned only when a dynamic value is encountered in strict mode
+    #     or the node type is not supported.
+    def extract_string(node, array_join_with: nil, array_flatten: false, array_reject_blank: false)
+      if %i[sym str int].include?(node.type)
+        node.children[0].to_s
+      elsif %i[true false].include?(node.type) # rubocop:disable Lint/BooleanSymbol
+        node.type.to_s
+      elsif node.type == :nil
+        ''
+      elsif node.type == :array && array_join_with
+        extract_array_as_string(
+          node,
+          array_join_with:    array_join_with,
+          array_flatten:      array_flatten,
+          array_reject_blank: array_reject_blank
+        ).tap do |str|
+          # `nil` is returned when a dynamic value is encountered in strict mode. Propagate:
+          return nil if str.nil?
+        end
+      elsif !config[:strict] && %i[dsym dstr].include?(node.type)
+        node.children.map do |child|
+          if %i[sym str].include?(child.type)
+            child.children[0].to_s
+          else
+            child.loc.expression.source
+          end
+        end.join
+      end
+    end
+
+    # Extract an array as a single string.
+    #
+    # @param array_join_with [String] joiner of the array elements.
+    # @param array_flatten [Boolean] if true, nested arrays are flattened,
+    #     otherwise their source is copied and surrounded by #{}.
+    # @param array_reject_blank [Boolean] if true, empty strings and `nil`s are skipped.
+    # @return [String, nil] `nil` is returned only when a dynamic value is encountered in strict mode.
+    def extract_array_as_string(node, array_join_with:, array_flatten: false, array_reject_blank: false)
+      children_strings = node.children.map do |child|
+        if %i[sym str int true false].include?(child.type) # rubocop:disable Lint/BooleanSymbol
+          extract_string child
+        else
+          # ignore dynamic argument in strict mode
+          return nil if config[:strict]
+          if %i[dsym dstr].include?(child.type) || (child.type == :array && array_flatten)
+            extract_string(child, array_join_with: array_join_with)
+          else
+            "\#{#{child.loc.expression.source}}"
+          end
+        end
+      end
+      if array_reject_blank
+        children_strings.reject! do |x|
+          # empty strings and nils in the scope argument are ignored by i18n
+          x == ''
+        end
+      end
+      children_strings.join(array_join_with)
+    end
+
+    def keys_relative_to_calling_method?(path)
+      /controllers|mailers/.match(path)
+    end
+
+    # @param raw_key [String]
+    # @param range [Parser::Source::Range]
+    # @param default_arg [String, nil]
+    # @return [Results::Occurrence]
+    def range_to_occurrence(raw_key, range, default_arg: nil)
+      Results::Occurrence.new(
+        path:        range.source_buffer.name,
+        pos:         range.begin_pos,
+        line_num:    range.line,
+        line_pos:    range.column,
+        line:        range.source_line,
+        raw_key:     raw_key,
+        default_arg: default_arg
+      )
+    end
+
+    # Create an {Parser::Source::Buffer} with the given contents.
+    # The contents are assigned a {Parser::Source::Buffer#raw_source}.
+    #
+    # @param path [String] Path to assign as the buffer name.
+    # @param contents [String]
+    # @return [Parser::Source::Buffer] file contents
+    def make_buffer(path, contents = read_file(path))
+      Parser::Source::Buffer.new(path).tap do |buffer|
+        buffer.raw_source = contents
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/AbcSize,Metrics/BlockNesting,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity

data/lib/i18n/processes/scanners/ruby_key_literals.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module I18n::Processes::Scanners
+  module RubyKeyLiterals
+    LITERAL_RE = /:?".+?"|:?'.+?'|:\w+/
+
+    # Match literals:
+    # * String: '', "#{}"
+    # * Symbol: :sym, :'', :"#{}"
+    def literal_re
+      LITERAL_RE
+    end
+
+    # remove the leading colon and unwrap quotes from the key match
+    # @param literal [String] e.g: "key", 'key', or :key.
+    # @return [String] key
+    def strip_literal(literal)
+      literal = literal[1..-1] if literal[0] == ':'
+      literal = literal[1..-2] if literal[0] == "'" || literal[0] == '"'
+      literal
+    end
+
+    VALID_KEY_CHARS = /(?:[[:word:]]|[-.?!:;À-ž])/
+    VALID_KEY_RE    = /^#{VALID_KEY_CHARS}+$/
+
+    def valid_key?(key)
+      key =~ VALID_KEY_RE && !key.end_with?('.')
+    end
+  end
+end