brandish 0.1.1

data/lib/brandish/processors/all/comment.rb

@@ -0,0 +1,29 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Brandish
+  module Processors
+    module All
+      # Adds a `<comment>` tag.  This ignores all of the elements inside of
+      # it, effectively  removing it from the output.
+      #
+      # This processor takes no options, nor any pairs.
+      #
+      # @example
+      #   Congratulations!  You've won $1,000!
+      #   <comment>Before taxes, anyway.</comment>
+      class Comment < Processor::Base
+        include Processor::Block
+        self.names = %i(comment ignore)
+        register %i(all comment) => self
+
+        # Returns nil, removing the node and its children from the tree.
+        #
+        # @return [nil]
+        def process
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/brandish/processors/all/embed.rb

@@ -0,0 +1,56 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Brandish
+  module Processors
+    module All
+      # Provides a block that allows Ruby code to be executed within it.
+      #
+      # Options:
+      #
+      # - `:really` - Optional.  If this isn't the exact value `true`, this
+      #   processor is never added to the context, preventing embed blocks from
+      #   being used.
+      #
+      # This takes no specific pairs; however, the embedded execution context
+      # has access to all of the pairs that are passed to the element.
+      #
+      # @note
+      #   This is **very dangerous** - ONLY USE IF YOU TRUST THE SOURCE.  This
+      #   processor provides no sandboxing by default.
+      class Embed < Processor::Base
+        include Processor::Block
+        self.names = %i(embed ruby)
+        register %i(all embed) => self
+        unrestricted_pairs!
+
+        # (see Processor::Base#initlaize)
+        def initialize(context, options = {})
+          super if true.equal?(options[:really])
+        end
+
+        # Creates a {Brandish::Execute} instance and executes the code.  This
+        # returns the return value of the code executed; therefore, if the
+        # code returns a string value, it is added to the output; otherwise,
+        # if it returns a nil value, it is ignored.  Those are the only two
+        # values that should be returned; others will be rejected.
+        #
+        # @return [::String, nil]
+        def perform
+          Execute.new(execute_context).exec(@body.flatten)
+        end
+
+        # The context that is passed to {Brandish::Execute#initialize}.  This
+        # provides the context, the "pairs" that were passed to the block, the
+        # options that were passed to the processor, the format that it is
+        # being executed in, and the form name.
+        #
+        # @return [{::Symbol => ::Object}]
+        def execute_context
+          { context: @context, pairs: @pairs, options: @options,
+            format: @context.form.format, form: @context.form.name }
+        end
+      end
+    end
+  end
+end

data/lib/brandish/processors/all/if.rb

@@ -0,0 +1,109 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Brandish
+  module Processors
+    module All
+      # Provides both an `if` and an `unless` block into the output.  The
+      # processor takes one option: `:embed`.  If embed _is_ `true` (using
+      # strict equalivalence `equal?`), then the if statement takes a single
+      # pair, named `"condition"`.  This condition is executed using
+      # {Brandish::Execute}, and if it is true, and if it is an `if` block,
+      # the contents are included; otherwise, if it is false, and if it is
+      # an `unless` block, the contents are included; otherwise, they are
+      # ignored.  If embed is `false`, the block can take multiple pairs, and
+      # each pair is matched to a name.  If the pair's value equals the matched
+      # name's value, then the condition is true.  If the condition is true,
+      # and the block is an `if` block, the contents are included; otherwise,
+      # if it is false, and if it is an `unless` block, the contents are
+      # included; otherwise, they are not.  The pair conditions that are
+      # matched by default are `"format"` and `"form"`.  If pairs are included
+      # that are not provided, it errors.
+      #
+      # Options:
+      #
+      # - `:embed` - Optional.  Whether or not the condition should be
+      #   treaded like an embedded condition.  This must be set to the exact
+      #   value of `true` for it to be accepted.
+      #
+      # Pairs:
+      #
+      # - `"condition"` - Optional.  The embedded condition for the `if` or
+      #   `unless` block.  Only applies if the `:embed` option is set.
+      # - `"format"` - Optional.  If this is provided, and the `:embed` option
+      #   is not set, it is added as a condition.
+      # - `"form"` - Optional.  If this is provided, and the `:embed` option
+      #   is not set, it is added as a condition.
+      #
+      # @example non-embed
+      #   <if format="html">
+      #     <import file="html-style" />
+      #   </if>
+      # @example embed
+      #   <if condition="@format == :html">
+      #     <import file="html-style" />
+      #   </if>
+      # @note
+      #   Using the `:embed` option is **very dangerous** - ONLY USE IF YOU
+      #   TRUST THE SOURCE.  `:embed` provides no sandboxing by default.  This
+      #   is why its value _must_ be set to be `true` exactly, and not
+      #   any other value.
+      class If < Processor::Base
+        include Processor::Block
+        self.names = [:if, :unless]
+        register %i(all if) => self
+        unrestricted_pairs!
+
+        # If {#meets_conditions?} is true, this accepts the body of the block
+        # for processing; otherwise, it returns `nil`, effectively causing
+        # the body to be ignored.
+        #
+        # @return [Parser::Node, nil]
+        def perform
+          accept(@body) if meets_conditions?
+        end
+
+        # If the name of this block is `"if"`, and all of the conditions are
+        # matched as outlined in the class direction, then this returns
+        # `true`; otherwise, if the name of this block is `"if"`, and any of
+        # the conditions are not matched as outlined in the class description,
+        # then this returns `false`; otherwise, if the name of this block is
+        # anything else (i.e. `"unless"`), and all of the conditions are
+        # matched as outlined in the class description, then this returns
+        # `false`; otherwise, if any of the conditions are not matched as
+        # outlined in the class description, then this returns `true`.
+        #
+        # @return [::Boolean]
+        def meets_conditions?
+          @name == "if" ? match_conditions : !match_conditions
+        end
+
+      private
+
+        def match_conditions
+          true.equal?(@options[:embed]) ? exec_condition : pair_condition
+        end
+
+        def exec_condition
+          context = Brandish::Execute.new(execute_context)
+          context.exec(@pairs.fetch("condition"))
+        end
+
+        def execute_context
+          { context: @context, pairs: @pairs, options: @options,
+            format: @context.form.format, form: @context.form.name }
+        end
+
+        def pair_condition
+          @pairs.all? { |k, v| match_pair.fetch(k.to_s).to_s == v.to_s }
+        end
+
+        def match_pair
+          @_match_pair ||= {
+            "format" => @context.form.format, "form" => @context.form.name
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/brandish/processors/all/import.rb

@@ -0,0 +1,95 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "open-uri"
+
+module Brandish
+  module Processors
+    module All
+      # "Imports" another file into this current file.  This takes the file,
+      # parses it, and inserts it directly into the position that the import
+      # was placed.  By default, this forces the file to be in the source
+      # directory, doing some awkward joining to make it work.  This takes
+      # one pair - `"name"`, `"link"`, or `"file"` - which contains the name of
+      # the file to import.  It takes two options:  `:absolute_allowed`, which
+      # allows imports to be outside of the source directory; and
+      # `:remote_allowed`, which allows remote files to be imported, using any
+      # of the protocols supported by open-uri.
+      #
+      # For local file imports, if no extensions were provided, an extension
+      # of `.br` is automatically added.  For remote files, extensions are
+      # always required.
+      #
+      # Imports are handled as if the entire imported file was copy and pasted
+      # into the source document.
+      #
+      # Options:
+      #
+      # - `:absolute_allowed` - Optional.  Despite its name, if this value is
+      #   `true`, imports can be used with any file that is outside of the
+      #   source directory.  Otherwise, the files will be forced to be inside
+      #   the source directory, as if the source directory is the root of the
+      #   file system.
+      # - `:remote_allowed` - Optional.  Whether remote imports should be
+      #   allowed.
+      #
+      # Pairs:
+      #
+      # - `"src"`, `"file"`, `"name"`, or `"link"` - Required.  These all do the
+      #   same thing - it provides the name of the file to import.
+      #
+      # @example local file
+      #   <import file="some-file" />
+      # @example remote file
+      #   <import link="http://example.org/some-file.br" />
+      # @example absolute local file
+      #   <import file="/opt/brandish/sources/html" />
+      # @note
+      #   Be careful when using `:remote_allowed` - this can cause possible
+      #   security issues if the remote is not trusted.
+      class Import < Processor::Base
+        include Processor::Command
+        register %i(all import) => self
+        pairs :src, :file, :name, :link
+
+        # Accepts the root node of the parsed file, processing the result as
+        # if it were an extension of the original source tree.
+        #
+        # @return [Parser::Node]
+        def perform
+          accept(parse_file)
+        end
+
+      private
+
+        def load_file
+          file = @pairs["src"] || @pairs["file"] || @pairs["name"] ||
+                 @pairs["link"]
+          return file if file
+          fail PairError.new("Expected one of src, file, name, or link, " \
+            "got nothing", @node.location)
+        end
+
+        def parse_file
+          load_file =~ /\A(https?|ftp):/ ? parse_remote_file : parse_local_file
+        end
+
+        def parse_remote_file
+          fail_remote_file unless @options[:remote_allowed]
+          open(load_file) { |io| @context.configure.parse_from(io, file) }
+        end
+
+        def fail_remote_file
+          fail PairError.new("Remote file given, but not supported", @node.location)
+        end
+
+        def parse_local_file
+          file = ::Pathname.new(load_file)
+          file = file.sub_ext(".br") unless load_file =~ /\.(.+?)\z/
+          path = @context.configure.sources.find(file)
+          @context.configure.roots[path]
+        end
+      end
+    end
+  end
+end

data/lib/brandish/processors/all/literal.rb

@@ -0,0 +1,42 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Brandish
+  module Processors
+    module All
+      # Takes the contents of the block, and outputs it, without any
+      # processing.  This is used to bypass any text processing processors
+      # that are being used.  This does nothing for command or block elements
+      # in the literal block, and the existance of such elements will cause
+      # errors.
+      #
+      # Because of the way the parser works, the original source text
+      # information is discarded for command and block elements, since they
+      # are unneeded for building the nodes.  This means that it is not
+      # possible to reconstruct, from only the AST, the original text without
+      # slight variances (which we don't want).  (The other option would be
+      # to use the location information to grab it from the file itself, but
+      # as of right now, location information is unreliable.)  This is why
+      # the literal tag cannot contain other command or block elements.
+      #
+      # This processor takes no options, nor any pairs.
+      #
+      # @example
+      #   <l>**Test**</l> this.
+      #   # => "**Test** this."
+      class Literal < Processor::Base
+        include Processor::Block
+        self.names = %i(literal raw l)
+        register %i(all literal) => self
+
+        # Preforms the literalizing of the body.  Right now, this just uses
+        # {Parser::Node::Root#flatten}.
+        #
+        # @return [::String]
+        def perform
+          @body.flatten
+        end
+      end
+    end
+  end
+end

data/lib/brandish/processors/all/verify.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Brandish
+  module Processors
+    module All
+      # This does nothing to the tree.  This just "verifies" that there are
+      # no remaining blocks or commands in the node tree, as they shouldn't be.
+      # This is highly recommended, as most Output processors are unable to
+      # handle the remaining blocks or commands.
+      #
+      # This processor takes no options.
+      class Verify < Processor::Base
+        register %i(all verify) => self
+
+        # Processes a block.  This always fails by design.
+        #
+        # @param node [Parser::Node::Block]
+        # @raise BuildError
+        def process_block(node)
+          fail VerificationBuildError.new(error_message(node), node.location)
+        end
+
+        # Processes a command.  This always fails by design.
+        #
+        # @param node [Parser::Node::Command]
+        # @raise BuildError
+        def process_command(node)
+          fail VerificationBuildError.new(error_message(node), node.location)
+        end
+
+      private
+
+        def error_message(node)
+          "Unexpected command or block element `#{node.name}' at " \
+            "#{node.location}; try adding #{suggested_processor(node)} to " \
+            "your `brandish.config.rb' file"
+        end
+
+        def suggested_processor(node)
+          "`form.use #{node.name.intern.inspect}' or " \
+            "`form.use #{"all:#{node.name}".inspect}'"
+        end
+      end
+    end
+  end
+end

data/lib/brandish/processors/common.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "brandish/processors/common/group"
+require "brandish/processors/common/header"
+require "brandish/processors/common/markup"
+require "brandish/processors/common/output"
+require "brandish/processors/common/style"
+
+module Brandish
+  module Processors
+    # Common processors.  These are processors that are required to be
+    # implemented for all formats, but are processors that can be implemented
+    # as an {All} processor.
+    #
+    # @abstract
+    module Common
+    end
+  end
+end

data/lib/brandish/processors/common/asset.rb

@@ -0,0 +1,118 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "brandish/processors/common/asset/paths"
+
+module Brandish
+  module Processors
+    module Common
+      # Allows assets to be included in the documents.  This is similar to the
+      # markup processor in that it uses a concept of _engines_ in order to
+      # power different kinds of assets.
+      #
+      # Options:
+      #
+      # - `:asset_load_paths` - Optional.  The load paths for the asset
+      #   processor.  These are used to resolve the asset file names, and are
+      #   passed directly to the {PathSet} created.
+      #
+      # Pairs:
+      #
+      # - `"src"`, `"file"`, `"name"`, or `"link"` - Required.  At least one
+      #   of these options are required.  They all perform the same function.
+      #   This defines the name or path of the asset to add or process.
+      # - `"type"` - Required.  The type of the asset to process.  This defines
+      #   how the asset is handled.
+      #
+      # @abstract
+      #   Implement engines using {.engine} and register the processor using
+      #   {.register}.
+      class Asset < Processor::Base
+        include Processor::Command
+        include Processor::Block
+        include Asset::Paths
+        pairs :src, :file, :name, :link, :type
+
+        # The engines defined for the subclass.  This should not be used on the
+        # parent class ({Common::Asset}).  This returns a key-value pair for
+        # the engines.  The key is the "name" of the format; this is used for
+        # the `"type" pair.  The value is a tuple containing two values:
+        # the syntax of the block/command options, and a proc that takes no
+        # arguments to include the asset.
+        #
+        # @api private
+        # @return [{::String => (::Symbol, ::Proc<void>)}]
+        def self.engines
+          @_engines ||= {}
+        end
+
+        # Defines an engine for use on the subclass.  This should not be used
+        # on the parent class ({Common::Asset}).  This takes the name of the
+        # engine, the syntax for the engine, and the processor to
+        # perform the asset processor.
+        #
+        # If both a third argument and a block are provided, then the block
+        # takes precedence.
+        #
+        # @api private
+        # @param name [::String] The name of the engine.  This is used for the
+        #   value of the `"type"` pair.
+        # @param syntax [::Symbol] The syntax type for the engine.  If it's
+        #   `:command`, the element should be a command node.  If it's
+        #   `:block`, the element should be a block node.  If it's `:all` or
+        #   `:_`, it can be either.
+        # @param symbol [::Symbol, nil] The method to call to add the
+        #   asset.
+        # @return [void]
+        def self.engine(name, syntax, symbol = nil, &block)
+          block ||= proc { send(symbol) }
+          engines[name.to_s] = [syntax, block]
+        end
+
+        # Adds the asset.  If the engine cannot be found, it returns
+        # `nil`, effectively ignoring the node.  This helps enable cross-format
+        # support without the use of `if` nodes.  This always returns `nil`,
+        # because outputting the asset is up to the {Common::Output}
+        # processor for the inclusion of the asset.
+        #
+        # @return [nil]
+        def perform
+          return unless (engine = find_engine)
+          syntax, block = engine
+          fail_syntax_error(syntax) if syntax == :block && !@body ||
+                                       syntax == :command && @body
+          instance_exec(&block)
+          nil
+        end
+
+        # Finds the value for the asset file.  This tries four different
+        # pairs before giving up: `"src"`, `"file"`, `"name"`, and `"link"`.
+        # If none of these could be found, it fails.
+        #
+        # @return [::String]
+        def load_asset_file
+          file = @pairs["src"] || @pairs["file"] || @pairs["name"] ||
+                 @pairs["link"]
+          return file if file
+          fail PairError.new("Expected one of src, file, name, or link, " \
+            "got nothing", @node.location)
+        end
+
+      private
+
+        def fail_syntax_error(syntax)
+          fail ElementSyntaxError.new("Incorrect syntax used for " \
+            "#{@pairs['type']} (a #{syntax} type)", @node.location)
+        end
+
+        def find_engine
+          type = @pairs.fetch("type")
+            .gsub(/(?<=[\w])([A-Z])/) { |m| "-#{m}" }
+            .downcase
+          return [] unless self.class.engines.key?(type)
+          self.class.engines.fetch(type)
+        end
+      end
+    end
+  end
+end