brandish 0.1.1

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

@@ -0,0 +1,93 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Brandish
+  module Processors
+    module Common
+      class Asset < Processor::Base
+        # Common path operations used for asset processors.  This assumes
+        # a css-like dependency structure similar to HTML's.  These are not
+        # required to be used.
+        module Paths
+          # The asset path for this kind of asset.
+          #
+          # @abstract
+          # @return [::String]
+          def asset_kind_path
+            nil
+          end
+
+          # The extension for this kind of asset.  This defaults to no
+          # extension.
+          #
+          # @abstract
+          # @return [::String]
+          def asset_kind_extension
+            ""
+          end
+
+          # The load paths for this asset type.  This defaults to a pathset
+          # containing all of the sources, all of the sources' appended with
+          # {#asset_kind_path}, and all of the paths given by the 
+          # `:asset_load_paths` option value.
+          def asset_load_paths
+            return @asset_load_paths if @asset_load_paths
+
+            paths = PathSet.new
+            @context.configure.sources
+                    .each { |p| paths << p }
+                    .each { |p| paths << p / asset_kind_path }
+            @options.fetch(:asset_load_paths, []).each { |p| paths << p }
+            @asset_load_paths = paths
+          end
+
+          # The default output assets path.
+          #
+          # @return [::String]
+          def output_assets_path
+            @context.configure.output / asset_kind_path
+          end
+
+          # Converts the given uri into a pathname, using the host, the path,
+          # the query, and the fragment all as directories.  This turns the
+          # uri `https://example.com/some-path?waffles#test` into the path
+          # `example.com/some-path/waffles/test.<asset_kind_extension>`.
+          #
+          # @param uri [::URI] The uri to convert into a path.
+          # @return [::Pathname]
+          def uri_path(uri)
+            base = [uri.host,
+              (uri.path unless uri.path.empty?),
+              (uri.query if uri.query),
+              (uri.fragment if uri.fragment)].compact
+            ::Pathname.new(::File.join(*base)).sub_ext(asset_kind_extension)
+          end
+
+          # The file paths.  This returns a hash with three elements:
+          # `:file`, which is the given file name from the element;
+          # `:out`, which is the full output directory for outputting the
+          # asset file; and `:src`, which is similar to what the HTML src
+          # or href value would be for the asset.
+          #
+          # @return [{::Symbol => ::Pathname}]
+          def load_file_paths
+            file = load_asset_file
+            # The full path to the file itself.
+            path = asset_load_paths.find(file, @options)
+            output_path = @context.configure.output
+            # The relative path from the source asset directory.
+            asset_path = asset_load_paths.resolve(file)
+            # The "raw" output path.
+            raw_output_path =
+              @pairs.fetch("output") { asset_path.sub_ext(asset_kind_extension) }
+            # The actual output path of the file.
+            file_output_path = output_assets_path / raw_output_path
+            src_output_path = file_output_path.relative_path_from(output_path)
+
+            { file: path, out: file_output_path, src: src_output_path }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Brandish
+  module Processors
+    module Common
+      # A "group."  This is for grouping together elements for styling
+      # or logical purposes.  By default, this creates a block element.
+      #
+      # This takes no options.
+      #
+      # Pairs:
+      #
+      # - `"class"` - Optional.  See {#class_value}.
+      # - `"id"` - Optional.  See {#id_value}.
+      # - `"name"` - Optional.  See {#name_value}.
+      #
+      # @abstract
+      #   Implement {#perform} and register the processor with {.register}.
+      class Group < Processor::Base
+        include Processor::Block
+        pairs :class, :id, :name
+
+        # The class value of the group.  This can have a 1-to-1 correspondence
+        # to the destination source.  This works similarly to HTML's class
+        # attribute.  This uses the `"class"` pair.
+        #
+        # @return [::String]
+        def class_value
+          @pairs.fetch("class", "")
+        end
+
+        # The ID value of the group.  This can have a 1-to-1 correspondence
+        # to the destination source.  This works similarly to HTML's id
+        # attribute; especially the concept that it should be unique.  This
+        # uses the `"id"` pair.
+        #
+        # @return [::String, nil]
+        def id_value
+          @pairs["id"]
+        end
+
+        # The name value of the group.  This doesn't have a 1-to-1
+        # correspondence to the destination source.  This is used to provide
+        # an internal styling or grouping process.  This uses the `"name"`
+        # pair.
+        #
+        # @return [::String, nil]
+        def name_value
+          @pairs["name"]
+        end
+
+        # The body, accepted and flattened.  This essentially converts the
+        # contents into a string that can be used as the value for the group.
+        #
+        # @see #accept
+        # @see Parser::Node::Root#flatten
+        # @return [::String]
+        def accepted_body
+          accept(@body).flatten
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Brandish
+  module Processors
+    module Common
+      # A processor that defines the `header` command.  This creates a list
+      # internally of all of the headers in the document, to later be used to
+      # possibly create a table of contents, if needed.
+      #
+      # This takes no options.
+      #
+      # Pairs:
+      #
+      # - `"level"` - Optional.  Defaults to `1`.  The "level" of the header.
+      #   This should be a value between 1 and 6.
+      # - `"value"` - Required.  The name of the header.
+      # - `"id"` - Optional.  The ID of the header.  This is a unique value
+      #   to reference to this header.  If no value is given, it defaults
+      #   to a modified `"value"`.
+      #
+      # @abstract
+      #   Implement {#header_render}, and register the processor with
+      #   {.register}.
+      class Header < Processor::Base
+        include Processor::Command
+        pairs :level, :value, :id
+
+        # (see Processor::Base#setup)
+        def setup
+          super
+          @context[:headers] = []
+        end
+
+        # Handles the header.  This stores the {#header_data} in the context
+        # `:headers` key, and then calls {#header_render}.
+        #
+        # @return [Parser::Node::Text] The resulting header text.
+        def perform
+          @context[:headers] << header_data
+          header_render
+        end
+
+        # Renders the header for the format.  This should be implemented by the
+        # implementing format.
+        #
+        # @abstract
+        # @return [Parser::Node::Text] The resulting header text.
+        def header_render
+          fail ProcessorNotImplementedError,
+            "Please implement #{self.class}#header_render"
+        end
+
+        # The header data used for the internal `:headers` structure.
+        #
+        # @return [{::Symbol => ::Object}]
+        def header_data
+          { level: header_level, value: header_value, id: header_id }
+        end
+
+        # The header level.  This is an integer between 1 and 6.
+        #
+        # @return [Numeric]
+        def header_level
+          @pairs.fetch("level", "1").to_i
+        end
+
+        # The "value" of the header.  This is the contents or the name of the
+        # header.  This is required.
+        #
+        # @return [::String]
+        def header_value
+          @pairs.fetch("value")
+        end
+
+        # The "id" of the header.  This should be a unique value between all
+        # headers that specifies this exact header.
+        #
+        # @return [::String]
+        def header_id
+          @pairs.fetch("id") { header_value.downcase.gsub(/[^\w]|_/, "-") }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,127 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Brandish
+  module Processors
+    module Common
+      # Processes the text in the document with the given markup.  Markup
+      # support varies from format to format, from a lot, to none.  All
+      # supported markups are not included as a dependency on the Brandish
+      # gem; they must be used as a dependency for the using library or
+      # application.
+      #
+      # *All* formats *must* provide an `:escape` engine, that escapes the
+      # source for the target format.
+      #
+      # Options:
+      #
+      # - `:engine` - Required.  This is the markup engine to use.  The allowed
+      #   values for this option is dependant on the format.
+      # - `:options` - Optional.  This is the
+      #   options for the markup engine.  The actual type is dependant on the
+      #   markup engine.  The default values are dependant on the markup engine.
+      #
+      # @abstract
+      #   Implement engines using {.engine}, and register the processor using
+      #   {.register}.
+      class Markup < Processor::Base
+        # The engines defined for the subclass.  This should not be used on the
+        # parent class ({Common::Markup}).  This returns a key-value pair for
+        # the engines.  The key is the "name" of the format; this is used for
+        # the `:engine` option.  The value is a tuple containing two values:
+        # the default options, and a proc that takes two arguments to markup
+        # the text.
+        #
+        # @api private
+        # @return [{::Symbol => (::Object, ::Proc<::String, ::Object, ::String>)}]
+        def self.engines
+          @_engines ||= {}
+        end
+
+        # Defines an engine for use on the subclass.  This should not be used
+        # on the parent class ({Common::Markup}).  This takes the name of the
+        # engine, the default options for the engine, and the processor to
+        # perform the markup processor.
+        #
+        # If both a third argument and a block are provided, then the block
+        # takes precedence.
+        #
+        # @api private
+        # @param name [::Symbol] The name of the engine.  This isn't the actual
+        #   name of the markup; this is the name of the engine that processes
+        #   the markup.
+        # @param default [::Object] The default options for the engine.
+        # @param initializer [::Symbol, ::Proc, nil] The initializer for the
+        #   engine.  If this is `nil`, no initializer is called.  If this is
+        #   a Symbol, the method is called for initialization.  If this is a
+        #   Proc, it is called for initialization.
+        # @param processor [::Symbol, ::Proc] The processor for the
+        #   engine.  If this is a Symbol, the method is called for
+        #   processing.  If this is a Proc, it is called for processing.
+        # @return [void]
+        def self.engine(name, default, initializer, processor)
+          engines[name] = [default.freeze, initializer, processor]
+        end
+
+        # (see Processor::Base#setup)
+        def setup
+          super
+          initialize_engine
+        end
+
+        # (see Processor::Base#process_text)
+        def process_text(node)
+          node.update(value: markup(node.value))
+        end
+
+      private
+
+        def initialize_engine
+          @engine = find_engine
+
+          case @engine[1]
+          when ::Symbol then send(@engine[1])
+          when ::Proc   then @engine[1].call
+          when nil      then return
+          else
+            fail ProcessorError, "Unknown initializer `#{@engine[1].inspect}'"
+          end
+        end
+
+        def find_engine
+          engine = @options.fetch(:engine)
+
+          case engine
+          when ::Symbol
+            self.class.engines.fetch(engine)
+          when ::Proc
+            [{}, nil, engine]
+          else
+            fail ProcessorError, "Unknown engine `#{engine.inspect}'"
+          end
+        end
+
+        def engine_options
+          @_engine_options ||= _build_engine_options
+        end
+
+        def markup(value)
+          case @engine[2]
+          when ::Symbol then send(@engine[2], value, engine_options)
+          when ::Proc   then @engine[2].call(value, engine_options)
+          else
+            fail ProcessorError, "Unknown processor `#{@engine[2].inspect}'"
+          end
+        end
+
+        def _build_engine_options
+          if @engine[0].is_a?(::Hash)
+            @engine[0].merge(@options.fetch(:options, {}))
+          else
+            @options.fetch(:options) { @engine[0].dup }
+          end.freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "liquid"
+
+module Brandish
+  module Processors
+    module Common
+      # Outputs the result of processing the document.  Without this processor,
+      # the document is not output, and most other processors have no effect.
+      #
+      # Options:
+      #
+      # - `:template` - Optional.  The name of the template to use.  This
+      #   defaults to the format used.
+      #
+      # @abstract
+      #   Please implement {#find_path} and {#template_data}, and register
+      #   the processor with {.register}.
+      class Output < Processor::Base
+        # Sets up the path and template for the output processor.  It first
+        # attempts to find the output path, creating the directory to that
+        # path if needed.  Then, it builds up the template that will later then
+        # be used to render the data.
+        #
+        # @see Processor::Base#setup
+        # @return [void]
+        def setup
+          super
+
+          @path = find_path.tap { |p| p.dirname.mkpath }
+          template_option = @options.fetch(:template, @context.form.format.to_s)
+          template_path = ::Pathname.new(template_option).sub_ext(".liquid")
+          template_full = @context.configure.templates.find(template_path)
+          @template = ::Liquid::Template.parse(template_full.read)
+        end
+
+        # Postprocess the result of processing.  The given root should only
+        # have text children, and should respond successfully to `#flatten`.
+        # This will render the template, and write it out to the value given
+        # in `@path`.
+        #
+        # @see Processor::Base#postprocess
+        # @param root [Parser::Node::Root]
+        # @return [void]
+        def postprocess(root)
+          @root = root
+          value = @template.render!(template_data, strict_variables: true)
+          @path.open("wb") { |f| f.write(value) }
+        end
+
+        # Finds the output path.
+        #
+        # @abstract
+        # @return [::Pathname]
+        def find_path
+          fail ProcessorNotImplementedError,
+            "Please implement #{self.class}#find_path"
+        end
+
+        # A hash of data to pass to the template for rendering.  The keys
+        # should always be strings.
+        #
+        # @abstract
+        # @return [{::String => ::Object}]
+        def template_data
+          fail ProcessorNotImplementedError,
+            "Please implement #{self.class}#template_data"
+        end
+      end
+    end
+  end
+end