brandish 0.1.1

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

@@ -0,0 +1,95 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "hanami/helpers/html_helper"
+require "hanami/helpers/escape_helper"
+
+module Brandish
+  module Markup
+    module Redcarpet
+      # An HTML renderer for redcarpet.  This provides integrations with
+      # Brandish, as well as code highlighting.
+      class HTML < ::Redcarpet::Render::SmartyHTML
+        include Hanami::Helpers::HtmlHelper
+        include Hanami::Helpers::EscapeHelper
+
+        # The tags for each level of header.
+        #
+        # @return [<::Symbol>]
+        TAGS = %i(h1 h2 h3 h4 h5 h6).freeze
+
+        # Initialize the renderer with the given context and options.
+        #
+        # @param context [Processor::Context]
+        # @param options [{::Symbol => ::Object}]
+        # @option options [::Symbol] :highlight (:none) Which highlighter to
+        #   use.  Possible values are `:rouge`, `:coderay`, `:pygments`, and
+        #   `:none`.
+        def initialize(context, options)
+          @context = context
+          @highlighter = options.fetch(:highlight)
+          super(options)
+        end
+
+        # Creates a header with the given text and level.  If the text ends in
+        # `/#([\w-]+)/`, that is removed, and used as the ID for the header;
+        # otherwise, it is automagically assumed from the text.
+        #
+        # @param text [::String]
+        # @param level [::Numeric]
+        # @return [::String]
+        def header(text, level)
+          text, id = split_text(text)
+
+          html.tag(TAGS.fetch(level), raw(text), id: id).to_s
+        end
+
+        # Highlights a block of code.
+        #
+        # @param code [::String] The code to highlight
+        # @param language [::String, nil] The language that the code was in,
+        #   or nil if it was not or could not be provided.
+        # @return [::String]
+        def block_code(code, language)
+          basic_language = language || "unknown"
+          case @highlighter
+          when :rouge then rouge_highlight_code(code, language)
+          when :coderay then coderay_highlight_code(code, language)
+          when :pygments then pygments_highlight_code(code, language)
+          when :none
+            html.pre { html.code(code, class: "language-#{basic_language}") }
+          end.to_s
+        end
+
+      private
+
+        def split_text(text)
+          # So we don't match entity tags by accident (`&#00;`).
+          if (match = text.match(/\A(.*)(?<!&)#([\w-]+)\s*\z/))
+            [match[1], match[2]]
+          else
+            # Remove entity tags, they're not needed.
+            [text, text.downcase.gsub(/&(.+?);/, "").gsub(/\W+/, "-")]
+          end
+        end
+
+        def rouge_highlight_code(code, language)
+          lexer = (language && Rouge::Lexer.find_fancy(language, code)) ||
+                  Rouge::Lexers::PlainText
+          attributes = { class: "highlight language-#{lexer.tag}" }
+          html.pre do
+            code(raw(::Rouge.highlight(code, lexer, "html")), attributes)
+          end
+        end
+
+        def coderay_highlight_code(code, langauge)
+          CodeRay.scan(code, langauge.intern, css: :style).div
+        end
+
+        def pygments_highlight_code(code, language)
+          Pygments.highlight(code, lexer: language.intern)
+        end
+      end
+    end
+  end
+end

data/lib/brandish/parser.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "yoga"
+require "brandish/parser/main"
+require "brandish/parser/node"
+
+module Brandish
+  # Parses the document into a tree of nodes.  This is strictly an LL(0)
+  # recursive descent parser - even though the term `peek` is used, this is
+  # technically a shifted token that is acted upon.
+  #
+  # This constructs a tree that can then be walked or modified to construct
+  # an end product.
+  class Parser
+    include Yoga::Parser
+    include Parser::Main
+
+    def initialize(*)
+      super
+    end
+
+    undef_method :peek_out
+    undef_method :peek_out?
+  end
+end

data/lib/brandish/parser/main.rb

@@ -0,0 +1,237 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Brandish
+  class Parser
+    # The main parser for the document.  This constructs a tree
+    # of nodes that can be used to represent the original
+    # document.
+    module Main
+      # Parses the overall document.  This parses a sequence of
+      # elements until it reaches the `EOF` token.
+      #
+      # @return [Parser::Node]
+      def parse_document
+        body = collect(EOF_SYMBOL) { parse_document_element }
+        expect(EOF_SYMBOL)
+        Node::Root.new(children: body)
+      end
+
+      alias_method :parse_root, :parse_document
+
+      # Parses a single element in the docuemnt.  If the next token is a
+      # less-than sign, it calls {#parse_document_meta}; otherwise, it calls
+      # {#parse_document_text}.
+      #
+      # @return [Node] The node for the element.
+      def parse_document_element
+        peek?(LESS_THAN_SYMBOL) ? parse_document_meta : parse_document_text
+      end
+
+      # parses a "meta" element from the document.  In this sense, it is
+      # anything that doesn't correspond 1-to-1 to the destination document.
+      # If the next token after the less-than sign is an at-sign, it calls
+      # {#parse_document_command}; otherwise, it calls {#parse_document_block}.
+      #
+      # @return [Node]
+      def parse_document_meta(start = expect(LESS_THAN_SYMBOL))
+        name = expect(TEXT_SYMBOL)
+        parse_skip_space
+        arguments = collect(SLASH_OR_GREATER_THAN_SYMBOL) { parse_document_command_argument }
+        if peek?(SLASH_SYMBOL)
+          parse_document_command(start, name, arguments)
+        else
+          parse_document_block(start, name, arguments)
+        end
+      end
+
+      # Parses a document command.  This is essentially a message to the
+      # compiler about the document, to alter how the document is processed.
+      #
+      #     command ::= '<' TEXT *command-argument '/' '>'
+      #
+      # @param start [Scanner::Token] The starting element for the command.
+      # @param name [Scanner::Token] The name of the command.
+      # @param arguments [<Node::Pair>] The arguments to the command.
+      # @return [Node::Command] The command node.
+      def parse_document_command(start, name, arguments)
+        expect(SLASH_SYMBOL)
+        stop = expect(GREATER_THAN_SYMBOL)
+
+        Node::Command.new(name: name, arguments: arguments,
+          location: start.location.union(stop.location))
+      end
+
+      # Parses a document command argument.  This is an argument to a command.
+      # All arguments are key-value pairs.
+      #
+      #     command-argument ::= *space command-argument-key *space '=' *space command-argument-value *space
+      #
+      # @return [Node::Pair] The command argument.
+      def parse_document_command_argument
+        parse_skip_space
+        key = parse_document_command_argument_key
+        parse_skip_space
+        expect(EQUAL_SYMBOL)
+        parse_skip_space
+        value = parse_document_command_argument_value
+        parse_skip_space
+
+        Node::Pair.new(key: key, value: value)
+      end
+
+      # The key for the command argument.
+      #
+      #     command-argument-key ::= TEXT
+      #
+      # @return [Scanner::Token]
+      def parse_document_command_argument_key
+        expect(TEXT_SYMBOL)
+      end
+
+      # The value for the command argument.  This can be either a string, or
+      # a {Node::Text} with a single token.  If it's a string, it's parsed with
+      # {#parse_document_string}; otherwise, it grabs one token that's valid
+      # for a {Node::Text} node.
+      #
+      #     command-argument-value ::= string / TEXT
+      #
+      # @return [Node]
+      def parse_document_command_argument_value
+        if peek?(QUOTE_SYMBOL)
+          parse_document_string
+        else
+          Node::Text.new(tokens: [expect(Node::Text::TOKENS)])
+        end
+      end
+
+      # Parses a "block."  This is similar to a HTML tag in the sense that it
+      # has a name and a body; however, blocks do not have any sort of
+      # arguments to them.
+      #
+      #     block ::= '<' TEXT *command-argument '>' *element '</' TEXT '>'
+      #
+      # @param start [Scanner::Token] The starting element for the block.
+      # @param name [Scanner::Token] The name of the block.
+      # @param arguments [<Node::Pair>] The arguments to the block.
+      # @return [Node::Block]
+      def parse_document_block(start, name, arguments)
+        expect(GREATER_THAN_SYMBOL)
+        body = parse_document_block_body
+        expect(SLASH_SYMBOL)
+        match = expect(TEXT_SYMBOL)
+        stop = expect(GREATER_THAN_SYMBOL)
+
+        unless name.value == match.value
+          fail ParseError.new("Unexpected #{match.value.inspect}, expected" \
+            " #{name.value.inspect}", match.location)
+        end
+
+        Node::Block.new(name: name, body: body, arguments: arguments,
+          location: start.location.union(body.location, match.location,
+            stop.location, *arguments.map(&:location)))
+      end
+
+      # Parses the body of a block tag.  This keeps attempting to parse text
+      # and meta tags until it encounters the phrase `</`, at which point it
+      # will stop parsing and return to the parent.
+      #
+      # @return [Node::Root]
+      def parse_document_block_body
+        children = []
+        loop do
+          if peek?(LESS_THAN_SYMBOL)
+            start = expect(LESS_THAN_SYMBOL)
+            break if peek?(SLASH_SYMBOL)
+            children << parse_document_meta(start)
+          else
+            children << parse_document_text
+          end
+        end
+
+        Node::Root.new(children: children)
+      end
+
+      # Parses a "string."  This is a series of text encapulated by quotes.
+      # Strings can contain more characters than just regular text, but right
+      # now, strings are only used for command argument values.
+      #
+      #     string ::= '"' *(TEXT / SPACE / LINE / NUMERIC / ESCAPE / '<' / '>' / '=') '"'
+      #
+      # @return [Node::String]
+      def parse_document_string
+        start = expect(QUOTE_SYMBOL)
+        children = collect(QUOTE_SYMBOL) { expect(Node::String::TOKENS) }
+        stop = expect(QUOTE_SYMBOL)
+        location = start.location.union(stop.location)
+
+        Node::String.new(tokens: children, location: location)
+      end
+
+      # Parses a document for text.  This is just regular text tokens.  For a
+      # list of tokens that are allowed, see {Node::Text::TOKENS}.
+      #
+      #     text ::= *(TEXT / SPACE / LINE / NUMERIC / ESCAPE / '/' / '"' / '=')
+      #
+      # @return [Node::Text]
+      def parse_document_text
+        children = [expect(Node::Text::TOKENS)]
+        children << expect(Node::Text::TOKENS) while peek?(Node::Text::TOKENS)
+        Node::Text.new(tokens: children)
+      end
+
+      # Skips over nodes as long as they're space nodes.
+      #
+      # @return [void]
+      def parse_skip_space
+        expect(SPACE_SYMBOLS) while peek?(SPACE_SYMBOLS)
+      end
+
+      # A set containing the kind symbol for a quote.
+      #
+      # @return [::Set<::Symbol>]
+      QUOTE_SYMBOL = ::Set[:'"']
+
+      # A set containing the kind symbol for an equal sign.
+      #
+      # @return [::Set<::Symbol>]
+      EQUAL_SYMBOL = ::Set[:'=']
+
+      # A set containing the kind symbol for a less than symbol.
+      #
+      # @return [::Set<::Symbol>]
+      LESS_THAN_SYMBOL = ::Set[:<]
+
+      # A set containing the kind symbol for a greater than symbol.
+      #
+      # @return [::Set<::Symbol>]
+      GREATER_THAN_SYMBOL = ::Set[:>]
+
+      # A set containing the kind symbol for a forward slash symbol.
+      #
+      # @return [::Set<::Symbol>]
+      SLASH_SYMBOL = ::Set[:/]
+
+      # A set containing the kind symbols for a forward slash or a greater than
+      # symbol.
+      #
+      # @return [::Set<::Symbol>]
+      SLASH_OR_GREATER_THAN_SYMBOL = SLASH_SYMBOL | GREATER_THAN_SYMBOL
+
+      # A set containing the kind symbols for a text symbol.
+      #
+      # @return [::Set<::Symbol>]
+      TEXT_SYMBOL = ::Set[:TEXT]
+
+      # A set containing the kind symbols for a space symbol.
+      #
+      # @return [::Set<::Symbol>]
+      SPACE_SYMBOLS = ::Set[:SPACE, :LINE]
+
+      # A set containing the kind symbols for a eof symbol.
+      #
+      # @return [::Set<::Symbol>]
+      EOF_SYMBOL = ::Set[:EOF]
+    end
+  end
+end

data/lib/brandish/parser/node.rb

@@ -0,0 +1,89 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "brandish/parser/node/block"
+require "brandish/parser/node/command"
+require "brandish/parser/node/pair"
+require "brandish/parser/node/root"
+require "brandish/parser/node/text"
+require "brandish/parser/node/string"
+
+module Brandish
+  class Parser
+    # A parser node.  This is the base for all parser nodes.b  All parser
+    # nodes are frozen, and so cannot be mutated; all mutations need to be
+    # set up as a new node, that is then returned.
+    class Node
+      # The location of the node.
+      #
+      # @return [Location]
+      attr_reader :location
+
+      # Initialize the node with the given location.  This should be
+      # overwritten by a decending node, but all decending nodes should
+      # include a location.
+      #
+      # @param location [Location] The location.  See
+      #   {#location}.
+      def initialize(location:)
+        @location = location
+      end
+
+      # Pretty inspect.
+      #
+      # @return [::String]
+      def inspect
+        "#<#{self.class} location=#{@location}>"
+      end
+
+      # "Updates" the node with the given attributes.  All of the key-value
+      # pairs in the attributes are updated on the node by sending an update
+      # to the node.
+      #
+      # @example
+      #   node.update(some: true, value: true)
+      #   # this sends `update_some` and `update_value`, each with `true` as
+      #   # the argument.  These functions return a node similar to the
+      #   # original, but with the requested change.  This is functionally
+      #   # similar to this (with some minor differences):
+      #   node.update_some(true).update_value(true)
+      # @raise [NodeError] if an attribute key is passed that isn't updatable
+      #   for the node.
+      # @param attributes [{::Symbol, ::String => ::Object}] The attributes to
+      #   update, and the new values for them.
+      # @return [Node] The updated node, or `self` if no attributes are given.
+      def update(attributes)
+        attributes.inject(self) { |a, (n, v)| a.update_attribute(n, v) }
+      end
+
+      # Prevents all calls to {#update}.  This is used on nodes that should
+      # never be updated.  This is a stop-gap measure for incorrectly
+      # configured projects.  This, in line with all other methods, creates
+      # a duplicate node.
+      #
+      # @return [Node]
+      def prevent_update
+        node = dup
+        node.singleton_class.send(:undef_method, :update)
+        node
+      end
+
+      def update_prevented?
+        !respond_to?(:update)
+      end
+
+    protected
+
+      # Updates an attribute on the node.  This is used for {#update}.
+      #
+      # @param name [::Symbol, ::String] The name of the attribute.
+      # @param value [::Object] The value of the attribute.
+      def update_attribute(name, value)
+        return send(:"update_#{name}", value) if respond_to?(:"update_#{name}", true)
+
+        fail NodeError.new("Unable to update attribute #{name} on #{self}",
+          @location)
+      end
+    end
+  end
+end