docks_app 0.0.1

data/lib/docks/parsers/stylus_parser.rb

@@ -0,0 +1,28 @@
+require_relative "base_parser.rb"
+
+module Docks
+  module Parsers
+    class Stylus < Sass
+      def initialize
+        @comment_pattern = /(?:\/\/|\/\*!?|\*\/?)/
+        @first_non_code_line_pattern = /[=+\.#\w\[&@]/
+        setup_regexes
+      end
+
+      def symbol_details_from_first_line(first_code_line)
+        first_code_line.strip!
+
+        type = case first_code_line
+          when /^[^:\(]*\([^\)]*\)$/ then Docks::Types::Symbol::MIXIN
+          when /\=/ then Docks::Types::Symbol::VARIABLE
+          when /(\.|\-\-)?(?:is|js)\-/ then Docks::Types::Symbol::STATE
+          when /\-\-(?:[a-zA-Z][\-_]?)*/ then Docks::Types::Symbol::VARIANT
+          else Docks::Types::Symbol::COMPONENT
+        end
+
+        name = first_code_line.match(/^\s*&?[@\.#]?\s*([^\s\(\:]*)/).captures.first
+        { name: name, symbol_type: type }
+      end
+    end
+  end
+end

data/lib/docks/process.rb

@@ -0,0 +1,60 @@
+module Docks
+  class Process
+    @@pattern_processors = { early: [], middle: [], late: [] }
+    @@pattern_library_processors = { early: [], middle: [], late: [] }
+
+    def self.process(item)
+      case item
+      when Containers::Symbol then item = process_symbol(item)
+      when Containers::Pattern then process_pattern(item)
+      when Containers::PatternLibrary then process_pattern_library(item)
+      end
+
+      item
+    end
+
+    def self.register_pattern_processor(hook = :middle, &block)
+      @@pattern_processors[hook] << block unless @@pattern_processors[hook].include?(block)
+    end
+
+    def self.register_pattern_library_processor(hook = :middle, &block)
+      @@pattern_library_processors[hook] << block unless @@pattern_library_processors[hook].include?(block)
+    end
+
+    private
+
+    def self.clean
+      @@pattern_processors = { early: [], middle: [], late: [] }
+      @@pattern_library_processors = { early: [], middle: [], late: [] }
+    end
+
+    def self.process_symbol(symbol)
+      # For when the initial symbol type was overwritten
+      if symbol.symbol_type != symbol.class.type
+        symbol = Containers.container_for(symbol.symbol_type).new(symbol.to_h)
+      end
+
+      # Allow tags to change the symbol's type
+      tags = symbol.tags
+      tags.each do |tag|
+        next unless tag.respond_to?(:process)
+        new_symbol = tag.process(symbol)
+        symbol = new_symbol if new_symbol.kind_of?(Containers::Symbol)
+      end
+
+      symbol
+    end
+
+    def self.process_pattern(pattern)
+      [:early, :middle, :late].each do |hook|
+        @@pattern_processors[hook].each { |processor| processor.call(pattern) }
+      end
+    end
+
+    def self.process_pattern_library(pattern_library)
+      [:early, :middle, :late].each do |hook|
+        @@pattern_library_processors[hook].each { |processor| processor.call(pattern_library) }
+      end
+    end
+  end
+end

data/lib/docks/processors.rb

@@ -0,0 +1,416 @@
+module Docks
+  module Processors
+    extend self
+
+    # Public: Processes the passed content by splitting it on commas,
+    # spaces, and pipes (and removing associated whitespace).
+    #
+    # content - An Array or String representing the parsed result.
+    #
+    # Examples
+    #
+    #   split_on_commas_spaces_and_pipes("String, Array | Object")
+    #   # => ["String", "Array", "Object"]
+    #
+    # Returns an Array of the split results.
+
+    def split_on_commas_spaces_and_pipes(content)
+      split_on_characters(content, [",", "|", "\s"])
+    end
+
+    def split_on_top_level_parens_commas_and_pipes(content)
+      return content unless content.kind_of?(String)
+
+      indexes = []
+      depth = 0
+
+      split_on = /[\|,]/
+      content.chars.each_with_index do |char, index|
+        if char == "("
+          depth += 1
+        elsif char == ")"
+          new_depth = [0, depth - 1].max
+
+          if new_depth == 0 && depth != 0
+            indexes << index
+          end
+
+          depth = new_depth
+        elsif split_on =~ char && depth == 0
+          indexes << index
+        end
+      end
+
+
+      result = []
+      start_index = 0
+
+      start_strip = /^\s*[,\|]*\s*/
+      end_strip = /\s*[,\|]*\s*$/
+      indexes.each do |index|
+        if index > start_index
+          item = content[start_index..index].gsub(start_strip, "").gsub(end_strip, "")
+          result << item if item.length > 0
+        end
+
+        start_index = index + 1
+      end
+
+      if start_index < content.length
+        result << content[start_index..-1].gsub(start_strip, "").gsub(end_strip, "")
+      end
+
+      result
+    end
+
+    # Public: Processes the passed content by splitting it on type-delimitting
+    # symbols ({/} to declare the type, ,/|/\s to separate them).
+    #
+    # content - An Array or String representing the parsed result.
+    #
+    # Examples
+    #
+    #   split_types("{String, Number |Object[]}")
+    #   # => [
+    #          OpenStruct.new(name: "String", array: false),
+    #          OpenStruct.new(name: "Number", array: false),
+    #          OpenStruct.new(name: "Object", array: true)
+    #        ]
+    #
+    # Returns an Array of types.
+
+    def split_types(content)
+      split_on_commas_spaces_and_pipes(content.gsub(/[\{\}]/, "").strip).map do |type|
+        array, type = if /\[\]/ =~ type
+          [true, type.split("[").first]
+        else
+          [false, type]
+        end
+
+        type = "Anything" if type == "*"
+
+        OpenStruct.new(name: type, array: array)
+      end
+    end
+
+    # Public: Processes the passed content splitting it on type-delimitting
+    # symbols ({/} to declare the type, ,/|/\s to separate them).
+    #
+    # content  - The String to break apart.
+    # split_on - The characters, passed as a single String or an Array of Strings,
+    #            on which the content string should be split. Defaults to "\,\s".
+    #
+    # Examples
+    #
+    #   split_on_characters("String, Array", "\s\,")
+    #   # => ["String", "Array"]
+    #
+    # Returns an Array with the split pieces.
+
+    def split_on_characters(content, split_on="\,\s")
+      return content unless content.kind_of?(String)
+
+      split_on = split_on.join("") if split_on.kind_of?(Array)
+      return content unless split_on.kind_of?(String)
+
+      content.split(/[#{split_on}]/).select { |piece| piece.length > 0 }
+    end
+
+    # Public: Processes the passed String by converting it to a
+    # boolean where any string other than one matching /false/
+    # will be considered true.
+    #
+    # content - A String representing the parsed result.
+    #
+    # Examples
+    #
+    #   stringy_boolean("  false ")
+    #   # => false
+    #
+    #   stringy_boolean("foo")
+    #   # => true
+    #
+    # Returns a boolean version of the content.
+
+    def stringy_boolean(content)
+      return false if content.nil?
+      return content unless content.kind_of?(String)
+      !content.include?("false")
+    end
+
+    CODE_BLOCK_INDICATOR = "```"
+    LIST_ITEM_INDICATOR = /^(?:\*|\-|\d+\.)/
+    HEADING_INDICATOR = /^#+/
+    HEADING_UNDERLINE_INDICATOR = /^[=\-]+/
+
+    # Public: Processes the passed content by joining it with line breaks as required.
+    # to create markdown-parsable paragraphs and code blocks.
+    #
+    # content - An Array representing the parsed result.
+    # join    - The string with which to join two different paragraphs together.
+    #
+    # Examples
+    #
+    #   join_with_smart_line_breaks(["One paragraph that", "spans two lines.", "And another!"])
+    #   # => "One paragraph that spans two lines.\n\nAnd another!"
+    #
+    #   join_with_smart_line_breaks(["One paragraph", "```html", "<p>A code block</p>", "```", "another paragraph."])
+    #   # => "One paragraph.\n\n```html\n<p>A code block</p>\n```\n\nanother paragraph"
+    #
+    # Returns the processed string.
+
+    def join_with_smart_line_breaks(content, join = "\n\n")
+      return content unless content.kind_of?(Array)
+
+      text = ""
+      in_code_block = false
+      in_list = false
+      at_start_of_paragraph = true
+
+      content.each_with_index do |line, index|
+        stripped_line = line.strip
+
+        if stripped_line.start_with?(CODE_BLOCK_INDICATOR)
+          # Either the start or end of a code block
+          if in_code_block
+            in_code_block = false
+            at_start_of_paragraph = true
+
+            text << "\n#{line}#{join}"
+          else
+            in_code_block = true
+            text << "#{join}#{line}"
+          end
+
+        elsif in_code_block || (in_list && stripped_line =~ LIST_ITEM_INDICATOR)
+          # Either:
+          # 1. In a code block — just keep appending lines, or
+          # 2. Last item was a list item and this item is directly below it,
+          #    so just add that line below.
+          text << "\n#{line}"
+
+        elsif stripped_line.length == 0
+          # Empty line — new paragraph
+          at_start_of_paragraph = true
+
+          text << join
+
+        elsif stripped_line =~ LIST_ITEM_INDICATOR && at_start_of_paragraph
+          # Line that looks like a list item and we're ready for a new paragraph
+          in_list = true
+          at_start_of_paragraph = false
+
+          text << line
+
+        elsif stripped_line =~ HEADING_INDICATOR
+          # Starts and ends a "## Header"-style heading
+          at_start_of_paragraph = true
+          text << "\n#{line}\n"
+
+        elsif stripped_line =~ HEADING_UNDERLINE_INDICATOR
+          # Ends a "Header\n======"-style heading
+          at_start_of_paragraph = true
+          text << "#{line}#{join}"
+
+        elsif content[index + 1] && content[index + 1].strip =~ HEADING_UNDERLINE_INDICATOR
+          # Start of a "Header\n======"-style heading
+          text << "\n#{line}\n"
+
+        elsif at_start_of_paragraph
+          # New line at the start of a regular paragraph
+          at_start_of_paragraph = false
+          in_list = false
+
+          text << line
+
+        else
+          # Line that isn't at the start of a paragraph — pin it to the previous line.
+          text << " #{stripped_line}"
+        end
+      end
+
+      text.strip!
+      text.gsub!(/\n{3,}/, "\n\n")
+      text.length > 0 ? text : nil
+    end
+
+    # Public: parses a string with names and optional parentheticals into an
+    # array of hashes with the name as the `name_key` and the parsed
+    # parenthetical options using the optional `default_for_parenthetical`.
+    #
+    # content     - The string with the name and optional parenthetical.
+    # name_key    - An optional Symbol representing the key that should be
+    #               used for the non-parenthetical portion. Defaults to :name.
+    # default_key - An optional Symbol to be used as the default key for an
+    #               unpaired item in the parentheses.
+    #
+    # Examples
+    #
+    #   name_and_parenthetical(':matches?', :setter)
+    #   # => [{setter: ':matches?'}]
+    #
+    #   name_and_parenthetical(':size (SIZE::LARGE)', :setter, :constant)
+    #   # => [{setter: ':size', constant: 'SIZE::LARGE'}]
+    #
+    #   name_and_parenthetical([':size (SIZE::LARGE)', ':checked?'], :setter, :constant)
+    #   # => [{setter: ':size', constant: 'SIZE::LARGE'}, {setter: ':checked?'}]
+    #
+    # Returns the parsed hash.
+
+    def name_and_parenthetical(content, name_key=:name, default_for_parenthetical=nil)
+      result = {}
+      match = content.match(/\s*(?<name>[^\(]*)(?:\s*\((?<paren>[^\)]*)\))?/)
+      result[name_key] = match[:name].strip
+
+      if (parenthetical = match[:paren]).nil?
+        result
+      else
+        result.merge(parenthetical_options(parenthetical, default_for_parenthetical))
+      end
+    end
+
+    # Public:
+    #
+    # content - A String of the parenthetical.
+    # default - An optional Symbol representing the key that should be used if
+    #           an un-paired value is provided.
+    #
+    # Examples
+    #
+    #   parenthetical_options('Activate with : foo , active : false')
+    #   # => {activate_with: 'foo', active: 'false'}
+    #
+    #   parenthetical_options('select, active : false, javascript action: $(this).text(1 + 1)', :demo_type)
+    #   # => {demo_type: 'select', active: 'false', javascript_action: '$(this).text(1 + 1)'}
+    #
+    # Returns the processed Hash.
+
+    def parenthetical_options(content, default=nil)
+      return content unless content.kind_of?(String)
+      result, default_only = {}, true
+      default = default.to_sym unless default.nil?
+      # Strip leading and trailing parentheses
+      content = content.strip.sub(/^\(/, '').sub(/\)$/, '')
+
+      # Get a leading, un-keyed value. This will be set to the default
+      # key (`default`), if it was passed
+      content.sub!(/\s*([^,]*),?\s*/) do |match|
+        if match.index(': ').nil?
+          result[default] = $1.strip unless default.nil?
+          ''
+        else
+          match
+        end
+      end
+
+      # Cycle over key value pairs and add to the return Hash
+      content.scan(/\s*(?<attribute>[^:]*):\s+(?<value>[^,]*),?\s*/).each do |match|
+        default_only = false
+        # Ensure that the key looks like a regular symbol
+        result[match[0].strip.downcase.gsub(/\s+/, '_').to_sym] = match[1].strip
+      end
+
+      result
+    end
+
+    # Public: Processes the passed content by yielding to the passed
+    # block in order to create a base hash, then adding any subsequent
+    # lines to the description (which can start on the first line — just
+    # set the description part as the returned hash's :description key.
+    # The description is then joined with smart line breaks.
+    #
+    # Yields the first line (item) of content.
+    #
+    # content - An Array of Strings representing the multiline description.
+    #
+    # Examples
+    #
+    #   multiline_description(['bar', 'baz']) { |first_line| { foo: first_line } }
+    #   # => { foo: 'bar', description: 'baz' }
+    #
+    #   multiline_description(['bar', 'Baz']) { |first_line| { foo: first_line, description: 'Already started!' } }
+    #   # => { foo: 'bar', description: "Already started!\n\nBaz" }
+    #
+    # Returns the processed Hash.
+
+    def multiline_description(content)
+
+      content = Array(content)
+      description = []
+      item = nil
+
+      content.each do |line|
+        if item.nil?
+          item = yield(line) if block_given?
+
+          if !item.kind_of?(Hash)
+            item = Hash.new
+            description << line
+          elsif !item[:description].nil?
+            description << item.delete(:description)
+          end
+        else
+          description << line
+        end
+      end
+
+      unless item.nil?
+        item[:description] = join_with_smart_line_breaks(description)
+        item
+      end
+    end
+
+    # Public: Processes the passed content by returning it if it's a valid
+    # demo type, and otherwise returning the default demo type.
+    #
+    # content - A string representing the desired demo type.
+    #
+    # Examples
+    #
+    #   ensure_valid_demo_type(Docks::Types::Demo::SELECT)
+    #   # => "select"
+    #
+    #   ensure_valid_demo_type("foo")
+    #   # => "none"
+    #
+    # Returns the processed string.
+
+    def ensure_valid_demo_type(content)
+      @demo_types ||= Docks::Types::Demo.constants.map { |const| Docks::Types::Demo.const_get(const) }
+      @demo_types.include?(content) ? content : Docks::Types::Demo::DEFAULT
+    end
+
+    # Public: Processes the passed content by splitting it on commas,
+    # spaces, and pipes (and removing associated whitespace).
+    #
+    # content - An Array or String representing the parsed result.
+    #
+    # Examples
+    #
+    #   CodeBlockWithLanguage.process([ "html - The markup.",
+    #                                   "<div class="foo">Bar</div>",
+    #                                   "<div class="bar">Baz</div>" ])
+    #   # => {language: "html", description: "The markup", code: "<div class=\"foo\">Bar</div>\n<div class=\"foo\">Bar</div>"}
+    #
+    #   CodeBlockWithLanguage.process([ "<div class="foo">Bar</div>",
+    #                                   "<div class="bar">Baz</div>" ])
+    #   # => {code: "<div class=\"foo\">Bar</div>\n<div class=\"foo\">Bar</div>"}
+    #
+    # Returns a Hash containing the language, description, and code block.
+
+    def code_block_with_language_and_description(content)
+      result = {}
+      content = Array(content)
+      possible_line_details = content.first.strip.split(/\s*\-\s*/, 2)
+
+      if Docks::Languages.extensions.include?(possible_line_details.first)
+        result[:language] = possible_line_details.first
+        result[:description] = possible_line_details.last if possible_line_details.length > 1
+        content.shift
+      end
+
+      result[:code] = content.join("\n")
+      result
+    end
+  end
+end

data/lib/docks/renderers/base_renderer.rb

@@ -0,0 +1,64 @@
+module Docks
+  module Renderers
+    class Base
+      def initialize; @cache = {} end
+
+      def render(template, locals = {})
+        raise NotImplementedError.new("You must provide a `render` method.")
+      end
+
+      def ivars=(ivars)
+        ivars.each do |ivar, value|
+          instance_variable_set("@#{ivar}".to_sym, value)
+        end
+      end
+
+      private
+
+      def normalize_content_and_locals(template, locals = {})
+        content = nil
+        layout = nil
+        must_be_partial = false
+
+        if template.kind_of?(Hash)
+          locals = template.fetch(:locals, {})
+          content = template.fetch(:inline, nil)
+          layout = template.fetch(:layout, nil) || nil # guard against false layouts
+
+          if template[:partial].nil?
+            template = template[:template]
+          else
+            template = template[:partial]
+            must_be_partial = true
+          end
+        else
+          layout = locals.delete(:layout)
+          layout = nil unless layout
+          locals = locals.delete(:locals) if locals.key?(:locals)
+        end
+
+        if content.nil?
+          options = {}
+          options[:must_be] = :partial if must_be_partial
+
+          found_template = Templates.search_for_template(template, options)
+          content = @cache[found_template] || File.read(found_template)
+          @cache[found_template] = content
+        end
+
+        if layout
+          found_layout = Templates.search_for_template(layout, must_be: :layout)
+          layout = @cache[found_layout] || File.read(found_layout)
+          @cache[found_layout] = layout
+        end
+
+        return content, layout, locals
+      end
+
+      def clean; @cache = {} end
+    end
+  end
+
+  def self.current_renderer; @current_renderer end
+  def self.current_renderer=(renderer); @current_renderer = renderer end
+end

data/lib/docks/renderers/common_features/capturable.rb

@@ -0,0 +1,69 @@
+module Docks
+  module Renderers
+    module Common
+
+      # Public: adds the required methods for template languages that support
+      # capturing and reusing blocks of content in the template.
+
+      module Capturable
+        @content_blocks = Hash.new
+
+        # Public: captures a block. Inclusions of this Mixin must override
+        # this method.
+        #
+        # block - The block of content to capture.
+        #
+        # Returns a String of the captured content.
+
+        def capture(&block)
+          raise NotImplementedError.new("You must implement a `capture` method.")
+        end
+
+        # Concatenates the `content` to the output buffer.
+        #
+        # content - The content to append.
+        #
+        # Returns the String of content passed.
+
+        def concat(content)
+          content
+        end
+
+        # Provides a named block to be reused later or, if only a name is
+        # provided, retrieves the captured content.
+        #
+        # name  - The name of the captured block
+        # block - The block of content to capture and store. If not provided,
+        #         the method will instead retrieve and return a previously
+        #         captured block named `name`, if one exists.
+        #
+        # Returns nothing (in the case of a block being provided) or the
+        # previously-captured block by the passed `name`.
+
+        def content_for(name, value = nil, &block)
+          @content_blocks ||= Hash.new
+
+          if block_given?
+            @content_blocks[name] = capture(&block)
+            nil
+          elsif !value.nil?
+            @content_blocks[name] = value
+            nil
+          else
+            @content_blocks[name]
+          end
+        end
+
+        # Checks whether a block named `name` has been captured.
+        #
+        # name - The block to check for.
+        #
+        # Returns a Boolean indicating whether the named block has been captured.
+
+        def content_for?(name)
+          !@content_blocks[name].nil?
+        end
+      end
+    end
+  end
+end

data/lib/docks/renderers/common_features/helperable.rb

@@ -0,0 +1,23 @@
+module Docks
+  module Renderers
+    module Common
+      module Helperable
+        def helpers(*helpers)
+          load_helpers = Module.new
+
+          helpers.each do |helper|
+            if helper.kind_of?(Module)
+              self.send(:extend, helper)
+            elsif File.exists?(helper)
+              load_helpers.module_eval(File.read(helper))
+            end
+          end
+
+          load_helpers.constants.each do |constant|
+            self.send(:extend, load_helpers.const_get(constant))
+          end
+        end
+      end
+    end
+  end
+end