brandish 0.1.1

data/lib/brandish/path_set.rb

@@ -0,0 +1,163 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Brandish
+  # A set of paths that can be searched for a certain file.  This is used for
+  # looking for certain files, like sources or templates.  This can allow
+  # Brandish to provide "default" files.
+  #
+  # Despite its name, the order in which the paths are added to the pathset
+  # are important.
+  class PathSet
+    extend Forwardable
+    include Enumerable
+
+    # @!method clear
+    # Removes all of the paths from this pathset.
+    #
+    # @return [void]
+    def_delegator :@paths, :clear
+
+    # @!method each(&block)
+    #   @overload each
+    #     Returns an enumerable over all of the paths in the pathset.
+    #
+    #     @return [::Enumerable<::Pathname>]
+    #   @overload each(&block)
+    #     Iterates over all of the paths in this pathset.
+    #
+    #     @yield path For each path in the pathset.
+    #     @yieldparam path [::Pathname] The path.
+    #     @return [void]
+    def_delegator :@paths, :each
+
+    # Initialize the pathset.
+    def initialize
+      @paths = []
+    end
+
+    # Adds a path to this pathset.
+    #
+    # @param path [::String, ::Pathname]
+    # @return [self]
+    def <<(path)
+      @paths << ::Pathname.new(path)
+    end
+
+    # Calls {#clear}, and then uses {#<<} to append the given path to the
+    # pathset, effectively replacing all of the paths in the pathset with the
+    # one given.
+    #
+    # @param path [::String, ::Pathname]
+    # @return [self]
+    def replace(path)
+      clear
+      self << path
+    end
+
+    # The default options for {#find} and {#find_all}.
+    #
+    # @return [{::Symbol => ::Object}]
+    DEFAULT_FIND_OPTIONS = { file: true, allow_absolute: false }.freeze
+
+    # "Resolves" a path.  This is resolved the exact same way that {#find}
+    # and {#find_all} are (with some slight variations), and so can be used
+    # as a sort of "name" for a certain path.
+    #
+    # @param path [::String, ::Pathname] The path to the file.
+    # @param options [{::Symbol => ::Object}] The options for resolution.
+    # @return [::Pathname] The resolved path.
+    def resolve(path, options = {})
+      options = DEFAULT_FIND_OPTIONS.merge(options)
+      path = ::Pathname.new(path)
+      if options[:allow_absolute]
+        path.cleanpath
+      else
+        ::Pathname.new(path.expand_path("/").to_s.gsub(%r{\A(/|\\)}, ""))
+      end
+    end
+
+    # Finds a file in the pathset.  If the file is returned, it is guarenteed
+    # to exist.  Relative paths, that do not expand out of the relative path,
+    # are handled like you would expect - the path is appended to one of the
+    # paths in the set, and checked for existance.  However, for a file that
+    # expands out of the relative path (e.g. `../a` or `a/../../b`), the
+    # behavior for expansion depends on the `allow_absolute` option.  If
+    # `allow_absolute` is false (default), the path is expanded against `/`
+    # before it is joind with the paths in the set (e.g. `../a`, against
+    # `/path/to`, with `allow_absolute=false`, expands to `/path/to/a`).
+    # If `allow_absolute` is true, it directly expanding against the path
+    # (e.g. `../a`, against `/path/to`, with `allow_absolute=true`, expands
+    # to `/path/a`).  `allow_absolute` should only be used if the given path
+    # is trusted.  Absolute paths are handled in a similar manner; if
+    # `allow_absolute=false`, for `/a` against `/path/to`, it expands to
+    # `/path/to/a`; with `allow_absolute=true`, for `/a` against `/path/to`,
+    # it expands to `/a`.
+    #
+    # @example
+    #   pathset
+    #   # => #<PathSet ...>
+    #   pathset.find("some/file")
+    #   # => #<Pathname /path/to/some/file>
+    #   pathset.find("not/real")
+    #   # !> NoFileError
+    #   pathset.find("/path/to/some/file")
+    #   # !> NoFileError
+    #   pathset.find("/path/to/some/file", allow_absolute: true)
+    #   # => #<Pathname /path/to/some/file>
+    #   pathset.find("../to/some/file")
+    #   # !> NoFileError
+    #   pathset.find("../to/some/file", allow_absolute: true)
+    #   # => #<Pathname /path/to/some/file>
+    # @raise [NoFileError] If no file could be found.
+    # @param short [::String, ::Pathname] The "short" path to resolve.
+    # @param options [{::Symbol => ::Object}] The options for finding.
+    # @option (see #find_all)
+    # @return [::Pathname] The full absolute path to the file.
+    def find(short, options = {})
+      find_all(short, options).next
+    rescue ::StopIteration
+      fail NoFileError, "Could not find `#{short}' in any of the given paths (paths: #{@paths})"
+    end
+
+    # Finds all versions of the short path name in the paths in the path
+    # sets.  If no block is given, it returns an enumerable; otherwise, if
+    # a block is given, it yields the joined path if it exists.
+    #
+    # @raise NoFileError If no file could be found.
+    # @param short [::String, ::Pathname] The "short" path to resolve.
+    # @param options [{::Symbol => ::Object}] The options for finding.
+    # @option options [Boolean] :allow_absolute (false)
+    # @option options [Boolean] :file (true) Whether or not the full path
+    #   must be a file for it to be considered existant.  This should be set
+    #   to true, because in most cases, it's the desired behavior.
+    # @yield [path] For every file that exists.
+    # @yieldparam path [::Pathname] The path to the file.  This is guarenteed
+    #   to exist.
+    # @return [void]
+    def find_all(short, options = {})
+      return to_enum(:find_all, short, options) unless block_given?
+      short = ::Pathname.new(short)
+      options = DEFAULT_FIND_OPTIONS.merge(options)
+
+      @paths.reverse.each do |path|
+        joined = path_join(path, short, options)
+        yield joined if (options[:file] && joined.file?) || joined.exist?
+      end
+
+      nil
+    end
+
+  private
+
+    def path_join(path, short, options)
+      if options[:allow_absolute]
+        short.expand_path(path)
+      else
+        ::Pathname.new(::File.join(path, short.expand_path("/")))
+      end
+    end
+  end
+end

data/lib/brandish/processor.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "brandish/processor/base"
+require "brandish/processor/context"
+require "brandish/processor/name_filter"
+require "brandish/processor/block"
+require "brandish/processor/command"
+require "brandish/processor/descend"
+
+module Brandish
+  # Processors for Brandish.  These just handle reshaping nodes so that they
+  # output nicely.  This can be used for things like including, bold tags,
+  # etc.
+  module Processor
+    # A structure containing all of the processors available.  This is a key
+    # value store, with the key being the format and the name, and the value
+    # being the actual processor.
+    #
+    # @return [{(::Symbol, ::Symbol) => Processor::Base}]
+    def self.all
+      @_processors ||= ::Hash.new
+    end
+
+    # Registers processors with the global registry.  This interns the format
+    # and name of the processor.  If the format and name pair already exists,
+    # it raises a {ProcessorError}.
+    #
+    # @example
+    #   Processor.register [:html, :stripper] => self
+    # @example
+    #   Processor.register [:all, :descend] => self
+    # @raise [ProcessorError] If one of the format and name pairs already
+    #   exists.
+    # @param map [{(::Symbol, ::Symbol) => Processor::Base}] The processors to
+    #   register.
+    # @return [void]
+    def self.register(map)
+      map.each do |(format, name), processor|
+        format, name = format.intern, name.intern
+        fail ProcessorError, "#{format}:#{name} already exists" \
+          if all.key?([format, name])
+        all[[format, name]] = processor
+      end
+    end
+  end
+end

data/lib/brandish/processor/base.rb

@@ -0,0 +1,144 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Brandish
+  module Processor
+    # A processor.  This responds to a set of methods that return updated
+    # versions of the nodes that are passed to them.  Processors are all
+    # initialized at the same time, with a context.  The processor is expected
+    # to add an object that responds to #call with arity matching `1` to the
+    # context using {Context#<<}.  The processor is allowed to add any number
+    # of objects to the context using this, if need be; by default, the
+    # processor just adds itself.
+    #
+    # @abstract
+    #   This class is not designed to be used and instantiated directly; this
+    #   just provides common behavior for a processor.  This class should be
+    #   subclassed and proper behavior defined on a subclass.
+    class Base
+      # (see Processor.register)
+      def self.register(map)
+        Processor.register(map)
+      end
+
+      # The context associated with this processor.
+      #
+      # @return [Context]
+      attr_reader :context
+
+      # Initializes the processor with the given context.  This adds the
+      # processor to the context, and sets the context for use on the
+      # processor.
+      #
+      # @param context [Context]
+      # @param options [::Object] The options for this processor.
+      def initialize(context, options = {})
+        @context = context
+        @context << self
+        @options = options
+        setup
+      end
+
+      # This is called by {#initialize}.  This allows subclasses to perform
+      # any nessicary setups without having to override {#initialize}.  This
+      # does nothing by default.
+      #
+      # @return [void]
+      def setup; end
+
+      # Processes the given node.  By default, it checks the classes of the
+      # inbound node, and maps them to `process_*` blocks.  If it doesn't
+      # match, an `ArgumentError` is thrown.
+      #
+      # If this function returns a `nil` value, the node should be ignored.
+      # {Context#accept} acknowledges this, and skips over the remaining
+      # processors once a processor returns a `nil` value for a node.
+      #
+      # @raise [::ArgumentError] if the node given isn't one of
+      #   {Parser::Node::Block}, {Parser::Node::Command}, {Parser::Node::Root},
+      #   or {Parser::Node::Text}.
+      # @param node [Parser::Node] A parser node to handle.
+      # @return [Parser::Node, nil] The result of processing.
+      def call(node)
+        _fix_result(_switch_node(node), node)
+      rescue LocationError then fail
+      rescue => e
+        fail BuildError.new("#{e.class}: #{e.message}", node.location,
+          e.backtrace)
+      end
+
+      # (see Context#accept)
+      def accept(node)
+        context.accept(node)
+      end
+
+      # Processes a block.  By default, this performs no modifications on the
+      # node, and returns the node itself.
+      #
+      # @param node [Parser::Node::Block]
+      # @return [::Object]
+      def process_block(node)
+        node
+      end
+
+      # Processes a command.  By default, this performs no modifications on the
+      # node, and returns the node itself.
+      #
+      # @param node [Parser::Node::Command]
+      # @return [::Object]
+      def process_command(node)
+        node
+      end
+
+      # Processes a root node.  By default, this performs no modifications on
+      # the node, and returns the node itself.
+      #
+      # @param node [Parser::Node::Root]
+      # @return [::Object]
+      def process_root(node)
+        node
+      end
+
+      # Processes a text node.  By default, this performs no modifications on
+      # the node, and returns the node itself.
+      #
+      # @param node [Parser::Node::Text]
+      # @return [::Object]
+      def process_text(node)
+        node
+      end
+
+      # An optional post-process.
+      #
+      # @param root [Parser::Node::Root]
+      # @return [void]
+      def postprocess(root); end
+
+    private
+
+      def _switch_node(node)
+        case node
+        when Parser::Node::Block   then process_block(node)
+        when Parser::Node::Command then process_command(node)
+        when Parser::Node::Root    then process_root(node)
+        when Parser::Node::Text    then process_text(node)
+        else
+          fail ArgumentError, "Expected node, got `#{node.class}'"
+        end
+      end
+
+      def _fix_result(result, node)
+        case result
+        when Parser::Node, nil
+          result
+        when ::String
+          Parser::Node::Text.new(value: result, location: node.location)
+                            .prevent_update
+        else
+          fail ArgumentError, "Unknown result type `#{result.class}' " \
+            "(given from #{self.class})"
+        end
+      end
+    end
+  end
+end

data/lib/brandish/processor/block.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Brandish
+  module Processor
+    # A block processor.  This is designed to act over a base to modify
+    # one specific block.  The block name itself is specified on the
+    # class, and the class provides logic to only modify block nodes with
+    # the same name.
+    module Block
+      # Ruby hook.
+      #
+      # @api private
+      # @return [void]
+      def self.included(base)
+        base.include Processor::NameFilter
+        base.include Processor::Pairfilter
+      end
+
+      # Processes the block.  If the node's name doesn't match the name for
+      # this class, it passes it on up to {Base#process_block}; otherwise,
+      # it passes it over to {#perform}.
+      #
+      # @param node [Parser::Node::Block]
+      # @return [::Object]
+      def process_block(node)
+        return super unless allowed_names.include?(node.name)
+        @node = node
+        @name = node.name
+        @pairs = node.pairs
+        @body = node.body
+
+        assert_valid_pairs
+        perform
+      end
+
+      # Performs the command adjustment.  This must be subclassed and
+      # overwritten.
+      #
+      # @abstract
+      # @return [::Object]
+      def perform
+        fail NotImplementedError, "Please implement #{self.class}#perform"
+      end
+    end
+  end
+end

data/lib/brandish/processor/command.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Brandish
+  module Processor
+    # A command processor.  This is designed to act over a base to modify
+    # one specific command.  The command name itself is specified on the
+    # class, and the class provides logic to only modify command nodes with
+    # the same name.
+    module Command
+      # Ruby hook.
+      #
+      # @api private
+      # @return [void]
+      def self.included(base)
+        base.include Processor::NameFilter
+        base.include Processor::PairFilter
+      end
+
+      # Processes the command.  If the node's name doesn't match the name for
+      # this class, it passes it on up to {Base#process_command}; otherwise,
+      # it passes it over to {#perform}.
+      #
+      # @param node [Parser::Node::Command]
+      # @return [::Object]
+      def process_command(node)
+        return super unless allowed_names.include?(node.name)
+        @node = node
+        @name = node.name
+        @pairs = node.pairs
+        @body = nil
+        
+        assert_valid_pairs
+        perform
+      end
+
+      # Performs the command adjustment.  This must be subclassed and
+      # overwritten.
+      #
+      # @abstract
+      # @return [::Object]
+      def perform
+        fail NotImplementedError, "Please implement #{self.class}#perform"
+      end
+    end
+  end
+end