textmate_grammar 0.0.0

data/lib/textmate_grammar/grammar_plugin.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+# @abstract Subclass GrammarLinter or GrammarTransform to implement a plugin
+class GrammarPlugin
+    # The options this plugin supports
+    # @return [Array<Symbol>] a list of symbols that represent keys that can
+    #   be read by the plugin
+    # @note the keys :grammar and :repository are reserved for passing grammar information
+    def self.options
+        []
+    end
+
+    # display the options as they would appear in the source
+    # @abstract override this to display the options as they would be entered into
+    #   source code
+    # @param indent [String] the spaces to indent each line width
+    # @param options [Hash] all options passed to the pattern
+    # @return [String] the options as a string
+    # @note each option should be prepended with +"\\n,#{indent}"+
+    # @note only display the options that are unique to this plugin
+    def self.display_options(indent, options) # rubocop:disable Lint/UnusedMethodArgument
+        raise "Internal error: display_options called with no provided options" if options.empty?
+
+        if self.options.empty?
+            raise "Internal error: display_options called on a plugin that provides no options"
+        end
+
+        raise "GrammarPlugin::options implemented but GrammarPlugin::display_options has not been"
+    end
+end
+
+# @abstract Subclass and override {#pre_lint} and/or {#post_lint}
+#   to implement a linter
+class GrammarLinter < GrammarPlugin
+    #
+    # Runs the linter on each pattern
+    #
+    # @param pattern [PatternBase, Symbol, Hash] the pattern to lint
+    # @param options [Hash] hash of any of the option keys provided by self.options.
+    #   options will only be populated when pattern is a PatternBase
+    #
+    # @return [Boolean] the result of the lint
+    def pre_lint(pattern, options = {}) # rubocop:disable Lint/UnusedMethodArgument
+        true
+    end
+
+    #
+    # Runs the linter on the entire grammar
+    #
+    # @param [Hash] grammar_hash The entire grammar
+    #
+    # @return [Boolean] the result og the lint
+    #
+    def post_lint(grammar_hash) # rubocop:disable Lint/UnusedMethodArgument
+        true
+    end
+end
+
+# @abstract Subclass and override {#pre_transform} and/or {#post_transform}
+#   to implement a transformation
+class GrammarTransform < GrammarPlugin
+    #
+    # Preforms the transformation on each pattern
+    #
+    # @param pattern [PatternBase, Symbol, Hash] the pattern to transform
+    # @param options [Hash] hash of any of the option keys provided by self.options.
+    #   options will only be populated when pattern is a PatternBase
+    #
+    # @return [PatternBase, Symbol, Hash] The transformed pattern. The return type should
+    #   match the type of pattern
+    #
+    # @note pattern should not be modified
+    #
+    def pre_transform(pattern, options) # rubocop:disable Lint/UnusedMethodArgument
+        pattern
+    end
+
+    #
+    # Performs the transformation on the whole grammar
+    #
+    # @param [Hash] grammar_hash The entire grammar
+    #
+    # @return [Hash] The transformed grammar
+    #
+    # @note grammar_hash should not be modified
+    #
+    def post_transform(grammar_hash)
+        grammar_hash
+    end
+end
+
+class Grammar
+    @@linters = []
+    @@transforms = {
+        before_pre_linter: [],
+        after_pre_linter: [],
+        before_post_linter: [],
+        after_post_linter: [],
+    }
+
+    #
+    # Register a linter plugin
+    #
+    # @param [GrammarLinter] linter the linter plugin
+    #
+    # @return [void] nothing
+    #
+    def self.register_linter(linter)
+        @@linters << linter
+    end
+
+    #
+    # Register a transformation plugin
+    #
+    # @param [GrammarTransform] transform the transformation plugin
+    # @param [Numeric] priority an optional priority
+    #
+    # @note The priority controls when a transformation runs in relation to
+    #  other events in addition to ordering transformations
+    #  priorities < 100 have their pre transform run before pre linters
+    #  priorities >= 100 have their pre transform run after pre linters
+    #  priorities >= 200 do not have their pre_transform function ran
+    #  priorities < 300 have their post transorm run before post linters
+    #  priorities >= 300 have their post transorm run before post linters
+    #
+    # @return [void] nothing
+    #
+    def self.register_transform(transform, priority = 150)
+        key = if priority < 100 then :before_pre_linter
+              elsif priority < 200 then :after_pre_linter
+              elsif priority < 300 then :before_post_linter
+              else :after_pre_linter
+              end
+
+        @@transforms[key] << {
+            priority: priority,
+            transform: transform,
+        }
+    end
+
+    #
+    # Gets all registered plugins
+    #
+    # @api private
+    #
+    # @return [Array<GrammarPlugin>] A list of all plugins
+    #
+    def self.plugins
+        @@linters + @@transforms.values.flatten.map { |v| v[:transform] }
+    end
+
+    #
+    # Removes a plugin whose classname matches plugin
+    #
+    # @param [#to_s] plugin The plugin name to remove
+    #
+    # @return [void]
+    #
+    def self.remove_plugin(plugin)
+        @@linters.delete_if { |linter| linter.class.to_s == plugin.to_s }
+        @@transforms[:before_pre_linter].delete_if { |t| t[:transform].class.to_s == plugin.to_s }
+        @@transforms[:after_pre_linter].delete_if { |t| t[:transform].class.to_s == plugin.to_s }
+        @@transforms[:before_post_linter].delete_if { |t| t[:transform].class.to_s == plugin.to_s }
+        @@transforms[:after_post_linter].delete_if { |t| t[:transform].class.to_s == plugin.to_s }
+    end
+end
+
+#
+# Filters a {PatternBase#original_arguments} to just the options required for a plugin
+#
+# @api private
+#
+# @param [GrammarPlugin] plugin The plugin to filter options
+# @param [PatternBase, Symbol, Hash] pattern the pattern with options to filter
+# @param [Hash] default the default options to supply to the plugin
+#
+# @return [Hash] the filtered options
+#
+def filter_options(plugin, pattern, default)
+    options = {}
+    if pattern.is_a? PatternBase
+        options = pattern.original_arguments.select { |k| plugin.class.options.include? k }
+    end
+    options.merge(default)
+end
+
+# load default linters and transforms
+Dir[File.join(__dir__, 'linters', '*.rb')].each { |file| require file }
+Dir[File.join(__dir__, 'transforms', '*.rb')].each { |file| require file }

data/lib/textmate_grammar/import_patterns.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'deep_clone'
+require 'yaml'
+require 'textmate_grammar/grammar_plugin'
+require 'textmate_grammar/util'
+require 'textmate_grammar/regex_operator'
+require 'textmate_grammar/regex_operators/concat'
+require 'textmate_grammar/tokens'
+
+# import Pattern, LegacyPattern, and PatternRange
+Dir[File.join(__dir__, 'pattern_variations', '*.rb')].each { |file| require file }
+# import .or(), .maybe(), .zeroOrMoreOf(), etc
+Dir[File.join(__dir__, 'pattern_extensions', '*.rb')].each { |file| require file }

data/lib/textmate_grammar/linters/flat_includes.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'textmate_grammar/util'
+
+#
+# Internal check, ensures that :includes is nil or a flat array
+#
+class FlatIncludes < GrammarLinter
+    #
+    # (see GrammarLinter#pre_lint)
+    #
+    def pre_lint(pattern, options)
+        return true unless pattern.is_a? PatternBase
+        return true if pattern.arguments[:includes].nil?
+
+        if pattern.arguments[:includes].is_a?(Array) &&
+           pattern.arguments[:includes].none? { |v| v.is_a? Array }
+            flat = true
+            pattern.arguments[:includes].map do |s|
+                flat = false unless pre_lint(s, options)
+            end
+            return flat
+        end
+
+        puts "The pattern `#{pattern.name}' does not have a flat includes array."
+        puts "This is an internal error"
+
+        false
+    end
+end
+
+Grammar.register_linter(FlatIncludes.new)

data/lib/textmate_grammar/linters/includes_then_tag_as.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'textmate_grammar/util'
+
+#
+# A pattern that has an includes cannot have any tag_as in @match
+#
+class IncludesThenTagAs < GrammarLinter
+    #
+    # Does pattern or any of its children / siblings have a tag_as
+    #
+    # @param [PatternBase, String] pattern the pattern to check
+    #
+    # @return [Boolean] if any of the patterns have a tag_as
+    #
+    def tag_as?(pattern)
+        return false unless pattern.is_a? PatternBase
+
+        pattern.each do |s|
+            puts s.arguments[:tag_as] if s.arguments[:tag_as]
+            return true if s.arguments[:tag_as]
+        end
+
+        false
+    end
+
+    #
+    # (see GrammarLinter#pre_lint)
+    #
+    def pre_lint(pattern, options)
+        return true unless pattern.is_a? PatternBase
+        return true if pattern.is_a? PatternRange
+
+        return false unless pre_lint(pattern.match, options)
+
+        return true unless pattern.arguments[:includes].is_a? Array
+        return true unless tag_as?(pattern.match)
+
+        name = pattern.name
+        puts "The pattern `#{name}' has both an includes argument and a match argument that,"
+        puts "it or a sub pattern has a tag_as argument."
+        puts "this is not supported"
+
+        true # TODO: fix issue
+    end
+end
+
+Grammar.register_linter(IncludesThenTagAs.new)

data/lib/textmate_grammar/linters/standard_naming.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+#
+# Checks for names to match expected naming format
+# see https://www.sublimetext.com/docs/3/scope_naming.html
+#
+
+class StandardNaming < GrammarLinter
+    # This is a summarization of the rules on the sublime text website for scope name
+    # process:
+    # 1. start at root
+    # 2. for each component in name
+    #    1. if there exists a key with that name
+    #       1. if the value is a hash: repeat with next component and that hash
+    #       2. otherwise return the value
+    #    2. else
+    #       1. if there exists a key of "*" return true, otherwise false
+    #
+    # to ease parsing, there should only every be one valid path
+    # if "a" exists, dont add "a.b" to the same key
+
+    # @return [Hash] a summarization of expected names
+    EXPECTED_NAMES = {
+        "comment" => {
+            "line" => true,
+            "block" => true,
+        }.freeze,
+        "constant" => {
+            "numeric" => true,
+            "language" => true,
+            "character" => {"escape" => true}.freeze,
+            "other" => true,
+        }.freeze,
+        "entity" => {
+            "name" => {
+                "class" => true,
+                "struct" => true,
+                "enum" => true,
+                "union" => true,
+                "trait" => true,
+                "interface" => true,
+                "impl" => true,
+                "type" => true,
+                "function" => true,
+                "namespace" => true,
+                "constant" => true,
+                "label" => true,
+                "section" => true,
+                "scope-resolution" => true,
+                "tag" => true,
+                "attribute-name" => true,
+                "other" => true,
+            }.freeze,
+            "other" => true,
+        }.freeze,
+        "invalid" => {
+            "illegal" => true,
+            "deprecated" => true,
+            "unknown" => true,
+        }.freeze,
+        "keyword" => {
+            "control" => true,
+            "operator" => true,
+            "other" => true,
+            "declaration" => true,
+        }.freeze,
+        "markup" => {
+            "heading" => true,
+            "list" => {
+                "numbered" => true,
+                "unnumbered" => true,
+            }.freeze,
+            "bold" => true,
+            "italic" => true,
+            "inline" => true,
+            "underline" => true,
+            "inserted" => true,
+            "deleted" => true,
+            "quote" => true,
+            "raw" => {
+                "inline" => true,
+                "block" => true,
+            }.freeze,
+            "other" => true,
+        }.freeze,
+        "meta" => {
+            "asm" => true,
+            "class" => true,
+            "struct" => true,
+            "enum" => true,
+            "union" => true,
+            "trait" => true,
+            "interface" => true,
+            "declaration" => true,
+            "impl" => true,
+            "initialization" => true,
+            "type" => true,
+            "qualified_type" => true,
+            "function" => true,
+            "parameter" => true,
+            "namespace" => true,
+            "using-namespace" => true,
+            "preprocessor" => true,
+            "conditional" => true,
+            "annotation" => true,
+            "path" => true,
+            "function-call" => true,
+            "block" => true,
+            "group" => true,
+            "braces" => true,
+            "parens" => true,
+            "brackets" => true,
+            "generic" => true,
+            "template" => true,
+            "tag" => true,
+            "paragraph" => true,
+            "string" => true,
+            "interpolation" => true,
+            "toc-list" => true,
+            "banner" => true,
+        }.freeze,
+        "punctuation" => {
+            "definition" => true,
+            "separator" => true,
+            "terminator" => true,
+            "accessor" => true,
+            "section" => true,
+            "vararg-ellipses" => true,
+        }.freeze,
+        "source" => true,
+        "storage" => {
+            "type" => true,
+            "modifier" => true,
+        }.freeze,
+        "string" => {
+            "quoted" => {
+                "single" => true,
+                "double" => true,
+                "other" => true,
+            }.freeze,
+            "unquoted" => true,
+            "regexp" => true,
+        }.freeze,
+        "support" => {
+            "constant" => true,
+            "function" => true,
+            "module" => true,
+            "type" => true,
+            "class" => true,
+            "other" => true,
+        }.freeze,
+        "text" => true,
+        "variable" => {
+            "other" => true,
+            "language" => true,
+            "function" => true,
+            "annotation" => true,
+            "parameter" => true,
+        }.freeze,
+    }.freeze
+
+    #
+    # Checks the tag keys at this level
+    #
+    # @param [Array<string>] tag an array of tag components
+    # @param [Numeric] index The index into tag to check
+    # @param [Hash] root the hash to check against
+    #
+    # @return [Boolean] If this is a valid tag
+    #
+    def recursive_check_tag(tag, index = 0, root = EXPECTED_NAMES)
+        if root.has_key?(tag[index])
+            next_part = root[tag[index]]
+            return recursive_check_tag(tag, index+1, next_part) if next_part.is_a? Hash
+
+            return [next_part, index, root]
+        elsif root.has_key? "*"
+            return [root["*"], index, root]
+        end
+
+        [false, index, root]
+    end
+
+    #
+    # Checks a tag for standard naming scheme
+    #
+    # @param [String] tag the tag to check
+    #
+    # @return [void] nothing
+    #
+    def check_tag(tag)
+        result, pos, root = recursive_check_tag(tag)
+        return if result
+
+        valid_prefix = (pos > 0) ? tag[0..(pos-1)].join(".") + "." : ""
+
+        puts "The prefix `#{tag[0..pos].join('.')}' does not follow the standard format"
+        puts "The expected prefixes at this level are:"
+        root.keys.each do |key|
+            if root[:key] == false
+                puts "- #{valid_prefix}#{key}"
+            else
+                puts "  #{valid_prefix}#{key}"
+            end
+        end
+    end
+
+    #
+    # Checks for names to match expected naming format
+    #
+    # @return [True] warnings to not return false
+    #
+    def pre_lint(pattern, _options)
+        return true unless pattern.is_a? PatternBase
+
+        pattern.each(true) do |pat|
+            next unless pat.arguments[:tag_as]
+
+            pat.arguments[:tag_as].split(" ").each { |tag| check_tag(tag.split(".")) }
+        end
+
+        true
+    end
+end
+
+Grammar.register_linter(StandardNaming.new)