brandish 0.1.1

data/lib/brandish/processor/context.rb

@@ -0,0 +1,169 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Brandish
+  module Processor
+    # The state associated with all of the processors.  Since all processors
+    # are independant class instances, instance variables that are used in
+    # one processor does not affect another; however, shared state can be
+    # used through the context.
+    #
+    # The context also keeps track of the processors being used for the
+    # processor, and distributes the processing management throughout all of
+    # the processors.
+    class Context
+      # A "skip" construct.  This makes the node be skipped through processing
+      # for the rest of the processors.  This is automatically applied to all
+      # nodes that are {Parser::Node#update_prevented?}.
+      #
+      # Once the skip construct has been passed through the processing, it is
+      # automatically unwrapped, returning the original node.
+      Skip = Struct.new(:node)
+
+      extend Forwardable
+      # @!method <<(*processors)
+      #   Adds processors to the processor list.  This delegates to
+      #   {#processors}.
+      #
+      #   @return [<#call>]
+      # @!method push(*processors)
+      #   Adds processors to the processor list.  This delegates to
+      #   {#processors}.
+      #
+      #   @return [<#call>]
+      # @!method unshift(*processors)
+      #   Adds a processor to the start of the processor list.  This delegates
+      #   to {#processors}.
+      #
+      #   @return [<#call>]
+      delegate [:<<, :push, :unshift] => :@processors
+
+      # @!method [](key)
+      #   Sets a key on the context.  This gets an option that is used for all
+      #   processors on this context.
+      #
+      #   @param key [::Symbol, ::String] The key.
+      #   @return [::Object]
+      # @!method []=(key, value)
+      #   Sets a key on the context.  This sets an option that is used for all
+      #   processors on this context.
+      #
+      #   @param key [::Symbol, ::String] The key.
+      #   @param value [::Object] The value.
+      #   @return [::Object]
+      # @!method fetch(key, default = CANARY, &block)
+      #   Fetches a value at the given key, or provides a default if the key
+      #   doesn't exist.  If both a block and a default argument are given,
+      #   the block form takes precedence.
+      #
+      #   @overload fetch(key)
+      #     Attempts to retrieve a value at the given key.  If there is no
+      #     key-value pair at the given key, it raises an error.
+      #
+      #     @raise [KeyError] if the key isn't on the context.
+      #     @param key [::Symbol, ::String] The key.
+      #     @return [::Object] The value.
+      #
+      #  @overload fetch(key, default)
+      #    Attempts to retrieve a value at the given key.  If there is no
+      #    key-value pair at the given key, it returns the value given by
+      #    `default`.
+      #
+      #    @param key [::Symbol, ::String] The key.
+      #    @param default [::Object] The default value.
+      #    @return [::Object] The value, or the default value if there isn't
+      #      one.
+      #
+      #   @overload fetch(key, &block)
+      #     attempts to retrieve a value at the given key.  If there is no
+      #     key-value pair at the given key, it yields.
+      #
+      #     @yield if there is no corresponding key-value pair.
+      #     @param key [::Symbol, ::String] The key.
+      #     @return [::Object] The value, or the result of the block if there
+      #       isn't one.
+      delegate [:[], :[]=, :fetch] => :@options
+
+      # @!method merge(options)
+      #   Merges the given options into this context.
+      #
+      #   @param options [{::Symbol, ::String => ::Object}]
+      #   @return [void]
+      def_delegator :@options, :merge!, :merge
+
+      # The processors that are going to be run on an accept.  This can be
+      # a {Processor::Base} subclass, or any object that responds to `#call`.
+      #
+      # @return [<#call>]
+      attr_reader :processors
+
+      # The configuration for the build.  This is used for output directories
+      # and the like.
+      #
+      # @return [Configure]
+      attr_reader :configure
+
+      # The form that is being processed.
+      #
+      # @return [Configure::Form]
+      attr_reader :form
+
+      # Initialize the context, to set up the internal state.
+      def initialize(configure, form)
+        @processors = []
+        @configure = configure
+        @form = form
+        @descent = Processor::Descend.new(self)
+        @buffer = []
+        @options = {}
+      end
+
+      # Performs the processing of the given root node.  This should be a
+      # {Parser::Node::Root}.
+      #
+      # @param root [Parser::Node::Root]
+      # @return [::Object]
+      def process(root)
+        root = accept(root)
+        effective_processors.each { |p| p.postprocess(root) }
+      end
+
+      # Accepts a node.  This passes the node through all of the processors,
+      # as well as an instance of the {Processor::Descend} processor.
+      #
+      # @param node [Parser::Node] The node to process.
+      # @return [::Object]
+      def accept(node)
+        # Injects the node over all effective processors.  Every iteration will
+        # use the value returned by the last `process` method call, unless it
+        # is `nil`.
+        result = effective_processors.inject(node) { |n, p| accept_node_with(n, p) }
+        result.is_a?(Skip) ? result.node : result
+      end
+
+    private
+
+      def accept_node_with(node, processor)
+        case node
+        when Skip, nil
+          node
+        when Parser::Node
+          result = processor.call(node)
+          if result.is_a?(Parser::Node) && result.update_prevented?
+            Skip.new(result)
+          else
+            result
+          end
+        else
+          fail ProcessorError, "Unknown node type `#{node.class}'"
+        end
+      end
+
+      def effective_processors
+        [@descent] + @processors
+      end
+    end
+  end
+end

data/lib/brandish/processor/descend.rb

@@ -0,0 +1,32 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Brandish
+  module Processor
+    # A descent processor.  This allows the context to descend into the
+    # children of the node as needed.  This does *not* descend into block
+    # nodes by default, due to a design decision - that has to be handled by
+    # another processor.
+    #
+    # @api private
+    class Descend < Base
+      # Initializes the processor with the given context.  This *does not* adds
+      # the processor to the context, and sets the context for use on the
+      # processor.
+      #
+      # @param context [Context]
+      def initialize(context)
+        @context = context
+      end
+
+      # Processes the root node.  This updates the root node with an updated
+      # list of children that have been accepted.
+      #
+      # @param node [Parser::Node::Root]
+      # @return [Parser::Node::Root]
+      def process_root(node)
+        node.update(children: node.children.map { |c| accept(c) }.compact)
+      end
+    end
+  end
+end

data/lib/brandish/processor/inline.rb

@@ -0,0 +1,49 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Brandish
+  module Processor
+    # An inline-defined processor.  This allows processors to be defined easily
+    # within a block.  This is mostly used for configuration.
+    #
+    # @example
+    #   class RFC < Brandish::Processor::Inline
+    #     command! :rfc
+    #     pairs :number
+    #
+    #     perform do
+    #       number = @pairs.fetch("number")
+    #       "<a href='https://www.ietf.org/rfc/rfc#{number}.txt'>RFC #{number}</a>"
+    #     end
+    #   end
+    class Inline < Base
+      # Sets this processor as a command processor.  This includes
+      # {Command}, and passes the given names to 
+      # {NameFilter::ClassMethods#name}.
+      #
+      # @return [void]
+      def self.command!(*names)
+        include Command
+        name(*names)
+      end
+
+      # Sets this processor as a block processor.  This include {Block}, and
+      # passes the given names to {NameFilter::ClassMethods#name}.
+      #
+      # @return [void]
+      def self.block!(*names)
+        include Block
+        name(*names)
+      end
+
+      # Defines the `#perform` method with the given block.  This is only
+      # effective if one of {Command} or {Block} is included.  This takes the
+      # block passed to it and uses that to define the `#perform` method.
+      #
+      # @return [void]
+      def self.perform(&block)
+        define_method(:perform, &block)
+      end
+    end
+  end
+end

data/lib/brandish/processor/name_filter.rb

@@ -0,0 +1,67 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "set"
+
+module Brandish
+  module Processor
+    # A "name filter" for command and block nodes.  This provides helpers to
+    # filter out nodes that don't have the given name.  The class will keep
+    # an internal list of names that are allowed to be used for the node,
+    # and if the node matches, then it processes it.
+    #
+    # @api private
+    module NameFilter
+      # The class methods that are implemented on the including module.  This
+      # is extended onto the class.
+      module ClassMethods
+        # The name that is assumed from the class name.
+        #
+        # @return [::String]
+        def assumed_class_name
+          name
+            .gsub(/\A(?:.+::)?(.*?)\z/, "\\1")
+            .gsub(/(?<!\A)[A-Z]/) { |m| "-#{m}" }
+            .downcase
+        end
+
+        # A list of allowed names for the class.
+        #
+        # @return [::Set<::String>]
+        def allowed_names
+          @names ||= name ? Set.new : Set[assumed_class_name]
+        end
+
+        # If no names are given, it retrieves them using {#allowed_names};
+        # otherwise, it merges the names into the allowed names set.
+        #
+        # @param names [#to_s, <#to_s>] The names.
+        # @return [::Set<::String>] The allowed names.
+        def names(*names)
+          return allowed_names if names.none?
+          allowed_names.merge(Array(names).flatten.map(&:to_s))
+        end
+
+        alias_method :name, :names
+        alias_method :names=, :names
+        alias_method :name=, :names
+      end
+
+      # The instance methods on the including class.
+      module InstanceMethods
+        # (see ClassMethods#allowed_names)
+        def allowed_names
+          self.class.allowed_names
+        end
+      end
+
+      # Used as a hook for Ruby.
+      #
+      # @api private
+      def self.included(receiver)
+        receiver.extend         ClassMethods
+        receiver.send :include, InstanceMethods
+      end
+    end
+  end
+end

data/lib/brandish/processor/pair_filter.rb

@@ -0,0 +1,96 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Brandish
+  module Processor
+    # A filter for defining which pairs are accepted by the given command or
+    # block processor.  By default, all pairs are restricted; however, certain
+    # pairs can be whitelisted, or all pairs can be allowed.  The former helps
+    # with debugging.
+    module PairFilter
+      # A placehodler object to denote that all pairs are allowed in the pair
+      # set.  This is only inserted into the allowed pair set when
+      # {ClassMethods#unrestricted_pairs!} is called.
+      ALL = Object.new.freeze
+
+      # The class methods that are implemented on the including module.  This
+      # is extended onto the class.
+      module ClassMethods
+        # A set of allowed pairs that can be used with the command or block
+        # element.
+        #
+        # @return [::Set<::String>]
+        def allowed_pairs
+          @allowed_pairs ||= Set.new
+        end
+
+        # A list of all of the ancestors' pairs.  This includes the current
+        # classes' pairs.  This allows allowed pair inheritance.
+        #
+        # @return [::Set<::String>]
+        def ancestor_allowed_pairs
+          ancestors
+            .select { |a| a.respond_to?(:allowed_pairs) }
+            .map(&:allowed_pairs)
+            .inject(Set.new, :merge)
+        end
+
+        # Retrives or sets the pairs for the class.
+        #
+        # @overload pairs
+        #   Retrieves the current pairs.  This is the same as calling
+        #   {#allowed_pairs}.
+        #
+        #   @return [::Set<::String>]
+        # @overload pairs(*pairs)
+        #   Adds pairs to the current {#allowed_pairs}.
+        #
+        #   @param pairs [::String, ::Symbol, #to_s]
+        #   @return [void]
+        def pairs(*pairs)
+          return allowed_pairs if pairs.none?
+          allowed_pairs.merge(Array(pairs).flatten.map(&:to_s))
+        end
+        alias_method :pair, :pairs
+
+        # Adds {PairFilter::ALL} to the pair list, allowing all pairs to be
+        # used with the command or block.
+        #
+        # @return [void]
+        def unrestricted_pairs!
+          pairs PairFilter::ALL
+        end
+        alias_method :unrestricted_pairs, :unrestricted_pairs!
+      end
+
+      # The instance methods on the including class.
+      module InstanceMethods
+        # (see ClassMethods#ancestor_allowed_pairs)
+        def allowed_pairs
+          self.class.ancestor_allowed_pairs
+        end
+
+        # Asserts that the pairs given are all allowed.  This uses the
+        # `@pairs` and `@node` instance variables.
+        #
+        # @raise [PairError] If an invalid pair was given.
+        # @return [void]
+        def assert_valid_pairs
+          return if allowed_pairs.include?(PairFilter::ALL)
+          excessive = @pairs.keys - allowed_pairs
+          return unless excessive.any?
+          fail PairError.new("Unexpected pairs found " \
+            "(#{excessive.map(&:inspect).join(', ')})", @node.location)
+        end
+      end
+
+      # Used as a hook for Ruby.
+      #
+      # @api private
+      def self.included(receiver)
+        receiver.extend         ClassMethods
+        receiver.send :include, InstanceMethods
+      end
+    end
+  end
+end

data/lib/brandish/processors.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "brandish/processors/common"
+require "brandish/processors/all"
+require "brandish/processors/html"
+require "brandish/processors/latex"
+
+module Brandish
+  # All of the available processors provided by Brandish by default are defined
+  # under this module.  Under this module, there are a set of modules, all
+  # pertaining to either a format, `All`, or `Common`.  `All` processors are
+  # provided for all documents, regardless of format; `Common` processors are
+  # always abstract, and define a set of processors that are required to be
+  # implemented for all formats.  If a format does not provide a `Common`
+  # processor, it is considered a bug.
+  module Processors
+    # All of the format modules under the {Processors} module.  This is
+    # essentially all modules that aren't named `All` or `Common`.
+    #
+    # @return [<Module>]
+    def self.format_modules
+      (constants - [:All, :Common]).map { |c| Processors.const_get(c) }
+    end
+  end
+end

data/lib/brandish/processors/all.rb

@@ -0,0 +1,19 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "brandish/processors/all/embed"
+require "brandish/processors/all/if"
+require "brandish/processors/all/import"
+require "brandish/processors/all/literal"
+require "brandish/processors/all/verify"
+
+module Brandish
+  module Processors
+    # Processors designed for use with all formats.  This module does not
+    # implement the {Common} processors, since the common processors can be
+    # format-dependant.  All processors in this module are defined on the
+    # `:all` special format.
+    module All
+    end
+  end
+end