brandish 0.1.1

data/lib/brandish/configure/dsl.rb

@@ -0,0 +1,135 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "pathname"
+require "brandish/configure/dsl/form"
+
+module Brandish
+  class Configure
+    # The DSL for configuration files for Brandish.  This is used to construct
+    # a configure object.
+    class DSL
+      # Creates a new DSL object with the given configuration object, and
+      # yields it.
+      #
+      # @param configure [Configure] The configuration instance.
+      # @return [DSL]
+      def self.call(configure = Configure.new)
+        DSL.new(configure).tap { |t| yield t }
+      end
+
+      # Creates a DSL object with the given configuration object.
+      #
+      # @param configure [Configure]
+      def initialize(configure = Configure.new)
+        @configure = configure
+      end
+
+      # Sets a given option key to a value.  The name is interned, making it
+      # a symbol.
+      #
+      # @param name [::Symbol, #intern] The name of the option key.
+      # @param value [::Object] The option value.
+      # @return [void]
+      def set(name, value)
+        @configure.options[name.intern] = value
+      end
+      alias_method :[]=, :set
+
+      # Retrives a given option key.  The name is interned, making it a symbol.
+      #
+      # @param name [::Symbol, #intern] The name of the option key.
+      # @return [::Object] The option value.
+      def get(name)
+        @configure.options.fetch(name)
+      end
+      alias_method :[], :get
+
+      # Sets the root path of the Brandish project.  This is where all of the
+      # important files are located.  Very rarely should this be set to
+      # anything other than `"."`.
+      #
+      # @param root [::String, ::Pathname] The new root.
+      # @return [void]
+      def root=(root)
+        path = _expand_path(root, Dir.pwd)
+        self[:root] = path
+      end
+
+      # Retrieves the root path of the Brandish project.  This is where all of
+      # the important files are located.  Very rarely should this be set to
+      # anything other than `"."`.
+      #
+      # @return [::Pathname] The full path to the root.
+      def root
+        self[:root]
+      end
+
+      alias_method :root_path=, :root=
+      alias_method :root_path, :root
+
+      # Sets the output directory of the Brandish project.  This is where all
+      # of the outputs are placed.  This is normally `"./output"`.
+      #
+      # @param output [::String, ::Pathname] The path to the output directory.
+      # @return [void]
+      def output=(output)
+        path = _expand_path(output, root)
+        self[:output] = path
+      end
+
+      # Retrieves the output directory of the Brandish project.  This is where all
+      # of the outputs are placed.  This is normally `"./output"`.
+      #
+      # @return [::Pathname] The full path to the output.
+      def output
+        self[:output]
+      end
+
+      alias_method :output_path=, :output=
+      alias_method :output_path, :output
+
+      # Retrives the source directories of the Brandish project.  This is where
+      # all of the sources are located.  This is normally `"./source"`.
+      #
+      # @return [::Pathname] The full path to the sources.
+      def sources
+        self[:sources]
+      end
+
+      alias_method :source_paths, :sources
+
+      # Retrieves the template directory of the Brandish project.  This is
+      # where all of the templates are placed.  This is normally `"./template"`.
+      #
+      # @return [::Pathname] The full path to the template.
+      def templates
+        self[:templates]
+      end
+
+      alias_method :template_paths, :templates
+
+      # Creates a new form for the configuration object.  This takes arguments
+      # and a block.  The block is yielded the form instance.
+      #
+      # @see DSL::Form
+      # @see Configure::Form
+      # @param (see DSL::Form#instance)
+      # @yield [form]
+      # @return [void]
+      def form(*arguments)
+        instance = DSL::Form.new(*arguments)
+        yield instance
+        form = Configure::Form.new(*instance.data)
+        @configure.forms << form
+        form
+      end
+
+    private
+
+      def _expand_path(path, directory)
+        ::Pathname.new(path).expand_path(::Pathname.new(directory))
+      end
+    end
+  end
+end

data/lib/brandish/configure/dsl/form.rb

@@ -0,0 +1,136 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Brandish
+  class Configure
+    class DSL
+      # Constructs a form for use with the configure instance.  A form is
+      # basically a format and name pair; different forms can have different
+      # entries, formats, and processors.
+      class Form
+        # The name of the form.  This defaults to a random value.  Do not
+        # rely on the name unless it is set.
+        #
+        # @return [::String]
+        attr_writer :name
+
+        # The entry for the form.  This is the file that begins the parsing
+        # for the form.
+        #
+        # @return [::String]
+        attr_writer :entry
+
+        # Initialize the form DSL.  This sets up the initial format and name,
+        # and intializes the instance variables.
+        #
+        # @param format [::Symbol] The format.
+        # @param name [::String, nil] The name of the form.
+        def initialize(format, name = nil)
+          @name = name || _generate_form_name
+          @format = format
+          @entry = "index.br"
+          @processors = []
+        end
+
+        # Adds a processor for use for the form.  The order that this is called
+        # is important.
+        #
+        # @example
+        #   config.form :html do |form|
+        #     form.use :literal # Can expand to either "html:literal" or "all:literal"
+        #                       # in that order.
+        #     form.use "all:literal" # Only expands to "all:literal"
+        #     form.use Brandish::Processors::All::Literal # allowed too
+        #     form.use do
+        #       # also allowed
+        #     end
+        #   end
+        # @overload use(name, options = {})
+        #   @param name [::String, ::Symbol, <::Symbol>, ::Class] The name of the
+        #     processor.  If the processor is a symbol, it is assumed to be the
+        #     name of the processor; the format is guessed to be either
+        #     the format of the form, or `:all`.  If the processor is a string,
+        #     and it contains a colon, it is assumed to be the name of the
+        #     processor in the form `<format>:<name>`; if it doesn't contain
+        #     the colon, it is treated as a symbol.  If it is an array, it is
+        #     assumed to be a pair containing the name of the process.  If it
+        #     is a class, it is assumed to be a processor, and is used directly.
+        #   @param options [{::Object => ::Object}] The options for the
+        #     processor.  The allowed values for the options are dependant on
+        #     the processor.
+        # @overload use(options = {}, &block)
+        #   @param options [{::Object => ::Object}] The options for the
+        #     processor.  The allowed values for the options are dependant on
+        #     the processor.
+        #   @yield into a new class; this allows a processor to be defined
+        #     without having a named class.
+        # @return [void]
+        def use(*arguments)
+          processor = options = nil
+
+          if block_given?
+            options = arguments[0]
+            processor = Class.new(Brandish::Processor::Base, &::Proc.new)
+          else
+            name = arguments[0]
+            options = arguments[1]
+            processor = _guess_processor_name(name)
+          end
+
+          @processors << [processor, options || {}]
+        end
+        alias_method :process, :use
+        alias_method :processor, :use
+        alias_method :define, :use
+
+        # The data from this form.  This is used to create the actual form that
+        # is used in the configuration.
+        #
+        # @return [(::String, ::Symbol, ::String, <(::String, ::String, ::Hash)>]
+        def data
+          [@name, @format, @entry, @processors]
+        end
+
+      private
+
+        def _generate_form_name
+          processor_names = @processors.map { |p| p[0..1].join(":") }.join(".")
+          "#{@format}.#{processor_names}"
+        end
+
+        def _guess_processor_name(name)
+          case name
+          when ::String then _guess_processor_name_string(name)
+          when ::Symbol then _guess_processor_name_symbol(name)
+          when ::Array  then _guess_processor_name_array(name)
+          when ::Class  then name # They're providing a class that can be used.
+          else
+            fail ::ArgumentError, "Unknown type given for name `#{name}`"
+          end
+        end
+
+        def _guess_processor_name_string(name)
+          parts = name.split(":")
+
+          case parts
+          when 1 then _guess_processor_name_symbol(name)
+          when 2 then _guess_processor_name_array(parts)
+          else
+            _guess_processor_name_array([parts[0], parts[1..-1].join(":")])
+          end
+        end
+
+        def _guess_processor_name_symbol(name)
+          default = [@format, name]
+          allowed = [default, [:all, name]]
+          which = allowed.find { |a| Processor.all.key?(a) } || default
+          _guess_processor_name_array(which)
+        end
+
+        def _guess_processor_name_array(name)
+          name.map(&:intern)
+        end
+      end
+    end
+  end
+end

data/lib/brandish/configure/form.rb

@@ -0,0 +1,32 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "pry"
+require "pry-rescue"
+
+module Brandish
+  class Configure
+    # A form used for building.
+    Form = Struct.new(:name, :format, :entry, :processors) do
+      # Builds the form.  This takes a configure object, and builds the
+      # form based on that.
+      #
+      # @see Configure#roots
+      # @see Processor::Context
+      # @see Processor
+      # @param configure [Configure] The configuration object for this build.
+      # @return [void]
+      def build(configure)
+        context = Processor::Context.new(configure, self)
+        root = configure.roots[configure.sources.find(entry)]
+
+        processors.each do |(processor, options)|
+          klass = processor.is_a?(::Array) ? Processor.all.fetch(processor) : processor
+          klass.new(context, options)
+        end
+
+        context.process(root)
+      end
+    end
+  end
+end

data/lib/brandish/errors.rb

@@ -0,0 +1,65 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Brandish
+  # An error that originates from the library for a library-specific reason.
+  # All libraries errors inherit from this class.
+  class Error < ::StandardError; end
+
+  # The file could not be found.
+  class NoFileError < Error; end
+
+  # An error that is created when there is a problem with scanning the
+  # document.
+  class ScanError < Error; end
+
+  # An error that occurs with setting up a processor.  This has no location
+  # information because this error occurs independant of a document.
+  class ProcessorError < Error; end
+
+  # The processor has not been implemented.
+  class ProcessorNotImplementedError < ProcessorError; end
+
+  # This should never be used directly.  This is an error that is tied to
+  # a location; as such, it provides an initalizer for providing a location.
+  #
+  # @api private
+  class LocationError < Error
+    # The location of the error in a file.
+    #
+    # @return [Location]
+    attr_reader :location
+
+    # Initialize the error with the given location and message.
+    def initialize(message, location = Location.default, bt = caller[1..-1])
+      @location = location
+      super(message)
+      set_backtrace(bt)
+    end
+  end
+
+  # An error that occurs when parsing.  This is for unexpected tokens.
+  class ParseError < LocationError; end
+
+  # An error that is created when there is an issue interacting with a parser
+  # node.
+  class NodeError < ParseError; end
+
+  # An error occured during a build.
+  class BuildError < LocationError; end
+
+  # An error occurred while building in a processor.  This includes location
+  # information from the original node.
+  class ProcessorBuildError < BuildError; end
+
+  # An error occurred while verifying the build.  This includes location
+  # information for the invalid node.
+  class VerificationBuildError < ProcessorBuildError; end
+
+  # An error occurred with a part of a command or block node, in which a pair
+  # was not included.
+  class PairError < ProcessorBuildError; end
+
+  # The syntax used for the styling was invalid.
+  class ElementSyntaxError < ProcessorBuildError; end
+end

data/lib/brandish/execute.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Brandish
+  # Executes a string of code in the instance of the class.
+  #
+  # @api private
+  class Execute
+    # Initialize the execution context.
+    #
+    # @param context [{::Symbol, ::String => ::Object}] The context.  The keys
+    #   are set as instance variables on the class, with the values being the
+    #   instance variable's respective value.
+    def initialize(context)
+      context.each { |k, v| instance_variable_set(:"@#{k}", v) }
+    end
+
+    # Executes the given code in the context of the class.
+    #
+    # @param code [::String] The code to execute.
+    # @return [::Object]
+    def exec(code)
+      instance_exec(code)
+    end
+  end
+end

data/lib/brandish/markup.rb

@@ -0,0 +1,10 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Brandish
+  # Markup modules for use with the {Processors::Common::Markup} processor.
+  # This is only to provide certain integrations with Brandish.
+  module Markup
+    autoload :Redcarpet, "brandish/markup/redcarpet"
+  end
+end

data/lib/brandish/markup/redcarpet.rb

@@ -0,0 +1,14 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "brandish/markup/redcarpet/html"
+require "brandish/markup/redcarpet/format"
+
+module Brandish
+  module Markup
+    # The Redcarpet format.  This is used with the
+    # {Processors::Common::Markup} processor.
+    module Redcarpet
+    end
+  end
+end

data/lib/brandish/markup/redcarpet/format.rb

@@ -0,0 +1,127 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "pry"
+
+module Brandish
+  module Markup
+    module Redcarpet
+      # Formats text with Redcarpet.  This is extracted into a seperate object
+      # in order to provide highlighting properties.  This is
+      # format-independant.
+      #
+      # This class can take the following options:
+      #
+      # - All Markdown extension options that are listed on
+      #   <https://github.com/vmg/redcarpet>, e.g. `:no_intra_emphasis`,
+      #   `:tables`, etc.
+      # - All HTML formatter options that are listed on
+      #   <https://github.com/vmg/redcarpet>, e.g. `:filter_html`,
+      #   `:no_images`, etc.
+      # - `:highlight` - Optional.  The highlighting engine to use.  Can be
+      #   one of `:rouge`, `:coderay`, `:pygments`, and `:none`.  Remember to
+      #   include the requisite highlighting engine in your Gemfile.  They
+      #   will automatically be required as needed.  Defaults to `:none`.
+      class Format
+        # The options that are passed over to the markdown engine.  These
+        # are extracted from the options that are passed to the markup engine.
+        #
+        # @return [<::Symbol>]
+        MARKDOWN_OPTIONS = %i(
+          no_intra_emphasis tables fenced_code_blocks autolink
+          disable_indented_code_blocks strikethrough lax_spacing
+          space_after_headers superscript underline quote footnotes
+        ).freeze
+
+        # The default options for the markdown engine as passed by this markup
+        # engine.
+        #
+        # @return [{::Symbol => ::Object}]
+        MARKDOWN_DEFAULTS = {
+          fenced_code_blocks: true, tables: true, autolink: true,
+          strikethrough: true, superscript: true, underline: true,
+          footnotes: true, space_after_headers: true
+        }.freeze
+
+        # The options that are passed over to the formatting engine.  These are
+        # Extracted from the options that are passed to the markup engine.
+        #
+        # @return [<::Symbol>]
+        FORMAT_OPTIONS = %i(
+          filter_html no_images no_links no_styles escape_html safe_links_only
+          with_toc_data hard_wrap xhtml prettify link_attributes highlight
+        ).freeze
+
+        # The default options for the formatting engine as passed by this
+        # markup engine.
+        #
+        # @return [{::Symbol => ::Object}]
+        FORMAT_DEFAULTS = { highlight: :none }.freeze
+
+        # The highlighting engines that are supported by this markup engine.
+        # The key is the value passed by the `:highlight` option, and the value
+        # is the require file name.  If the value is `nil`, no requirement
+        # is performed.
+        #
+        # @return [{::Symbol => ::Object, nil}]
+        HIGHLIGHTERS = {
+          rouge: "rouge", coderay: "coderay", pygments: "pygments",
+          none: nil
+        }.freeze
+
+        # The formating engines that can be used by this markup engine.
+        #
+        # @return [{::Symbol => ::Class}]
+        FORMATTERS = { html: HTML }.freeze
+
+        # Initialize the markup engine for Redcarpet.  For the available
+        # options, see {Format}.
+        #
+        # @param options [::Hash]
+        def initialize(options)
+          @context = options.fetch(:context)
+          @format = options.fetch(:format)
+          @markdown_options = MARKDOWN_DEFAULTS
+                              .merge(extract_options(MARKDOWN_OPTIONS, options))
+          @formatter_options = FORMAT_DEFAULTS
+                               .merge(extract_options(FORMAT_OPTIONS, options))
+          @highlight = @formatter_options[:highlight]
+          load_highlighter
+          load_engine
+        end
+
+        # Renders the given text using the engine.
+        #
+        # @param string [::String] The value to render.
+        # @return [::String] The rendered value.
+        def render(string)
+          @engine.render(string)
+        end
+
+      private
+
+        def load_highlighter
+          file = HIGHLIGHTERS.fetch(@highlight)
+          require file if file
+        rescue ::KeyError
+          fail ProcessorError, "Unknown highlighter `#{@highlight}`"
+        end
+
+        def load_engine
+          begin
+            formatter = FORMATTERS.fetch(@format)
+          rescue ::KeyError
+            fail ProcessorError, "Unsupported format `#{@format}`"
+          end
+
+          renderer = formatter.new(@context, @formatter_options)
+          @engine = ::Redcarpet::Markdown.new(renderer, @markdown_options)
+        end
+
+        def extract_options(keys, options)
+          keys.zip(options.values_at(*keys)).select!(&:last).to_h
+        end
+      end
+    end
+  end
+end