cabbage_doc 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 72c954cb92be482568747328289d2c65daf273a6
+  data.tar.gz: aafdefb0496f2a2152402c492b4cc8b4eb11ef77
+SHA512:
+  metadata.gz: 16cd85c66b78ad28fa3c2791e7df1922cd33160754148f0cf42b4861d66705e521d3421ed5ead623643f9a046ea802713c81b8a3f6d2292ac8e9b78955f82897
+  data.tar.gz: 5afa6dec9856b545e4c0ba4d4ce691b623dd153cc8dc45f11bae3e66ac10ee567d81950e8398b52ece74eab5459cdee6a372b90deac2092ebf9b5f14097c7d17

data/lib/cabbage_doc/action.rb

@@ -0,0 +1,86 @@
+module CabbageDoc
+  class Action
+    include Parser
+
+    METHODS = %w(GET POST PUT DELETE).freeze
+    METHODS_REGEXP = METHODS.join('|').freeze
+
+    attr_reader :label, :name, :description, :path, :method, :parameters, :examples
+
+    def initialize
+      @parameters = []
+      @examples = []
+    end
+
+    def parse(text)
+      @method, @path = parse_method_and_path(text)
+      return unless valid?
+
+      @name = parse_name(text)
+      @label = parse_label(text)
+      @description = parse_description(text)
+
+      @parameters, @examples = parse_parameters_and_examples(text)
+
+      valid?
+    end
+
+    def valid?
+      @method && @path
+    end
+
+    def param?(key)
+      @parameters.any? { |parameter| parameter.name =~ /#{key}/ }
+    end
+
+    private
+
+    # FIXME: get rid of this and optimize direct regex matches
+    def text_to_lines(text)
+      text.gsub(/\r\n?/, "\n").split(/\n/)[0..-2].map do |line|
+        line.strip!
+        line.slice!(0)
+        line.strip!
+        line if line.size > 0
+      end.compact
+    end
+
+    def parse_parameters_and_examples(text)
+      # FIXME: rewrite this to do a 'scan' with the right Regexp
+      parameters = []
+      examples = []
+
+      lines = text_to_lines(text)
+
+      lines.each do |line|
+        if parameter = Parameter.parse(line)
+          parameters << parameter
+        elsif example = Example.parse(line)
+          examples << example
+        end
+      end
+
+      [parameters, examples]
+    end
+
+    def parse_method_and_path(text)
+      m = text.match(/#\s*(#{METHODS_REGEXP}):\s*(.*?)$/)
+      [m[1].strip.upcase, m[2].strip] if m
+    end
+
+    def parse_name(text)
+      m = text.match(/def\s+(.*?)\s*#\s*#{MARKER}$/)
+      m[1].strip if m
+    end
+
+    def parse_label(text)
+      m = text.match(/#\s*Public:(.*?)$/)
+      m[1].strip if m
+    end
+
+    def parse_description(text)
+      m = text.match(/#\s*Description:(.*?)$/)
+      m[1].strip if m
+    end
+  end
+end

data/lib/cabbage_doc/authentication.rb

@@ -0,0 +1,54 @@
+module CabbageDoc
+  class Authentication
+    class << self
+      def new(request = nil)
+        super().tap do |auth|
+          yield(auth) if block_given?
+          Configuration.instance.authentication.call(auth, request)
+        end
+      end
+    end
+
+    attr_accessor :type,
+                  :username,
+                  :password,
+                  :token,
+                  :domain,
+                  :subdomain,
+                  :subdomains,
+                  :scheme,
+                  :path,
+                  :user_agent,
+                  :configurable,
+                  :verbose
+
+    def initialize
+      Configuration.instance.tap do |config|
+        @domain     = config.domain
+        @scheme     = config.scheme
+        @path       = config.path
+        @user_agent = config.title
+      end
+
+      @verbose = false
+      @subdomains = []
+      @configurable = []
+      @type = :basic
+    end
+
+    def valid?
+      case type
+      when :basic
+        username && password
+      when :token
+        !token.nil?
+      else
+        false
+      end
+    end
+
+    def configurable?
+      @configurable.any?
+    end
+  end
+end

data/lib/cabbage_doc/client.rb

@@ -0,0 +1,27 @@
+module CabbageDoc
+  class Client
+    include HTTParty
+
+    class << self
+      def new(auth)
+        Class.new(self) do |klass|
+          klass.headers "User-Agent" => auth.user_agent
+    
+          if auth.subdomain
+            klass.base_uri "#{auth.scheme}://#{auth.subdomain}.#{auth.domain}/#{auth.path}"
+          else
+            klass.base_uri "#{auth.scheme}://#{auth.domain}/#{auth.path}"
+          end
+
+          if auth.type == :basic
+            klass.basic_auth auth.username, auth.password
+          elsif auth.token
+            klass.headers "Authorization" => "#{auth.type.to_s.capitalize} #{auth.token}"
+          end
+
+          debug_output $stdout if auth.verbose
+        end
+      end
+    end
+  end
+end

data/lib/cabbage_doc/cloneable.rb

@@ -0,0 +1,9 @@
+require 'yaml'
+
+module CabbageDoc
+  module Cloneable
+    def clone
+      YAML.load(YAML.dump(self))
+    end
+  end
+end

data/lib/cabbage_doc/collection.rb

@@ -0,0 +1,67 @@
+require 'yaml'
+
+module CabbageDoc
+  class Collection
+    include Singleton
+    include Enumerable
+
+    FILENAME = "controllers.yml".freeze
+
+    def initialize
+      @_controllers = []
+    end
+
+    def <<(controller)
+      @_controllers << controller
+    end
+
+    def find_action(method, path)
+      action = nil
+
+      @_controllers.each do |controller|
+        action = controller.find_action(method, path)
+        break if action
+      end
+
+      action
+    end
+
+    def each
+      @_controllers.each do |controller|
+        yield controller
+      end
+    end
+
+    def parse!(filename)
+      text = File.read(filename) rescue nil
+      return false unless text
+
+      controller = Controller.parse(text)
+      return false unless controller
+
+      controllers = controller.eval(text)
+
+      @_controllers.concat(controllers)
+
+      controllers.any?
+    end
+
+    def clear!
+      @_controllers = []
+    end
+
+    def load!
+      @_controllers = YAML.load(File.read(filename)) rescue [] unless @_controllers.any?
+    end
+
+    def save!
+      open(filename, 'w') { |f| f.write(YAML.dump(@_controllers)) } rescue nil
+    end
+
+    private
+
+    def filename
+      @_filename ||= Path.join(Configuration.instance.root, FILENAME)
+    end
+  end
+end

data/lib/cabbage_doc/configuration.rb

@@ -0,0 +1,52 @@
+module CabbageDoc
+  class Configuration
+    include Singleton
+
+    DEFAULTS = {
+      version: 'v1',
+      path: 'api/v1',
+      title: 'Cabbage Doc',
+      scheme: 'https',
+      verbose: false
+    }.freeze
+
+    OPTIONAL_ATTRIBUTES = %i(welcome path scheme version title verbose authentication).freeze
+    REQUIRED_ATTRIBUTES = %i(domain controllers root).freeze
+    ATTRIBUTES          = (OPTIONAL_ATTRIBUTES + REQUIRED_ATTRIBUTES).freeze
+    CALLABLE_ATTRIBUTES = %i(controllers authentication).freeze
+
+    attr_accessor *ATTRIBUTES 
+
+    def initialize
+      DEFAULTS.each do |attr, value|
+        send(:"#{attr}=", value)
+      end
+    end
+
+    def validate!
+      validate_required!
+      validate_callable!
+      validate_root!
+    end
+
+    private
+
+    def validate_required!
+      REQUIRED_ATTRIBUTES.each do |attr|
+        raise ArgumentError, "#{attr} is required" unless send(attr)
+      end
+    end
+
+    def validate_callable!
+      CALLABLE_ATTRIBUTES.each do |attr|
+        if (value = send(attr)) && !value.respond_to?(:call)
+          raise ArgumentError, "#{attr} is not callable"
+        end
+      end
+    end
+
+    def validate_root!
+      raise ArgumentError, "#{root} directory doesn't exist" unless Dir.exists?(root)
+    end
+  end
+end

data/lib/cabbage_doc/controller.rb

@@ -0,0 +1,117 @@
+module CabbageDoc
+  class Controller
+    include Parser
+    include Cloneable
+
+    attr_reader :label, :klass, :name, :path, :actions
+
+    def initialize
+      @actions = []
+    end
+
+    def parse(text)
+      @label, @path, @klass = parse_label_path_and_class(text)
+      return false unless @label && @klass
+
+      @name = compose_name(klass)
+
+      @actions = parse_actions(text) unless template?
+
+      valid?
+    end
+
+    def valid?
+      @name && (actions? || template?)
+    end
+
+    def find_action(method, path)
+      @actions.detect do |action| 
+        action.method == method && action.path == path
+      end
+    end
+
+    def eval(text)
+      return [self] unless template?
+
+      templates = []
+
+      templates += parse_templates(@path)
+      templates += parse_templates(@label)
+
+      return [] unless templates.any?
+
+      count = templates.first[:values].count
+
+      (1..count).map do |i|
+        template_text = text.dup
+
+        templates.each do |template|
+          template_text.gsub!(template[:text], template[:values].shift.to_s)
+        end
+
+        self.class.parse(template_text)
+      end.compact
+    end
+
+    private
+
+    def compose_label(metadata, klass)
+      metadata[:label] || klass.sub(/Controller$/, '')
+    end
+
+    def compose_path(metadata, klass)
+      Path.join('/', Configuration.instance.path, metadata[:path] || compose_name(klass))
+    end
+
+    def compose_name(klass)
+      compose_label({}, klass).downcase
+    end
+
+    def parse_label_path_and_class(text)
+      klass = parse_class(text)
+      return unless klass
+
+      metadata = parse_metadata(text)
+
+      [compose_label(metadata, klass), compose_path(metadata, klass), klass]
+    end
+
+    def parse_actions(text)
+      actions = []
+
+      text.scan(/(#\s*Public:\s*.*?(#{Action::METHODS_REGEXP}):.*?def\s+.*?\s*#\s*#{MARKER})/m) do
+        actions << Action.parse($1.strip)
+      end 
+
+      actions.compact
+    end
+
+    def parse_class(text)
+      m = text.match(/class\s+(.*?)\s+?#\s+?#{MARKER}$/)
+      m[1].strip.split('<').first.strip if m
+    end
+
+    def parse_metadata(text)
+      m = text.match(/(#\s*Public:\s*.*?class\s+.*?\s*#\s*#{MARKER})/m)
+      return {} unless m
+
+      metadata = m[1].strip
+
+      {}.tap do |hash|
+        m = metadata.match(/#\s*Public:(.*?)$/)
+        hash[:label] = m[1].strip if m
+
+        m = metadata.match(/#\s*PATH:\s*\/(.*?)$/)
+        hash[:path] = m[1].strip if m
+      end
+    end
+
+    def actions?
+      @actions.any?
+    end
+
+    def template?
+      @path =~ /\/{.*?,.*?}/
+    end
+  end
+end

data/lib/cabbage_doc/customizer.rb

@@ -0,0 +1,9 @@
+require 'fileutils'
+
+module CabbageDoc
+  class Customizer
+    def perform
+      FileUtils.cp_r(Web::ROOT, Configuration.instance.root)
+    end
+  end
+end

data/lib/cabbage_doc/example.rb

@@ -0,0 +1,25 @@
+module CabbageDoc
+  class Example
+    include Parser
+
+    attr_reader :label, :params
+
+    def initialize
+      @params = {}
+    end
+
+    def parse(text)
+      m = text.match(/^(.*?)\s+-\s+(\(.*?\))$/)
+      return false unless m
+
+      @label = m[1].strip
+      @params = parse_option(m[2].strip)
+
+      valid?
+    end
+
+    def valid?
+      !@label.nil?
+    end
+  end
+end

data/lib/cabbage_doc/pacto_helper.rb

@@ -0,0 +1,27 @@
+module CabbageDoc
+  module PactoHelper
+    def pacto_enable!
+      WebMock.allow_net_connect!
+
+      Pacto.configure do |config|
+        config.contracts_path = Configuration.instance.root
+      end
+
+      Pacto.generate!
+    end
+
+    def pacto_disable!
+      Pacto.stop_generating!
+    end
+
+    def pacto_available?
+      require 'forwardable'
+      require 'pacto'
+
+      defined?(Pacto)
+    rescue LoadError => e
+      puts "WARNING: Pacto is not available."
+      false
+    end
+  end
+end

data/lib/cabbage_doc/parameter.rb

@@ -0,0 +1,72 @@
+module CabbageDoc
+  class Parameter
+    include Parser
+
+    TYPES = %i(numeric decimal integer string id enumeration array date time timestamp hash)
+
+    attr_reader :label, :name, :type, :type_label, :default, :values, :required
+
+    def initialize
+      @values = []
+    end
+
+    def parse(text)
+      m = text.match(/^(.*?\s+\(.*?\).*?)\s+-\s+(.*?)$/)
+      return false unless m
+
+      @name, @type_label, @required = parse_name_type_required(m[1].strip)
+      @type = @type_label.downcase.to_sym if @type_label
+
+      @required = !!@required
+
+      @label, @default, @values = parse_label_default_values(m[2].strip)
+      @values ||= []
+
+      valid?
+    end
+
+    def valid?
+      @type && TYPES.include?(@type)
+    end
+
+    private
+
+    def parse_label_default_values(text)
+      m = text.match(/^(.*?)\s*(\(.*?\))?$/)
+      return unless m
+
+      index, options = parse_options(text)
+
+      arr = [text[0..index-1].strip]
+
+      if options.any?
+        arr << options[:default]
+        arr << Array(options[:values])
+      end
+
+      arr
+    end
+
+    def parse_name_type_required(text)
+      text.split(/\s+/).map(&:strip).map do |component|
+        if component =~ /^\((.*?)\)$/
+          $1
+        elsif component =~ /\[required\]/i
+          true
+        else
+          component
+        end
+      end
+    end
+
+    def parse_options(text)
+      m = text.match(/:.*?\)$/)
+      return [0, {}] unless m
+
+      index = text.rindex('(')
+      return [0, {}] unless index
+      
+      [index, parse_option(text[index..-1].strip)]
+    end
+  end
+end

data/lib/cabbage_doc/params.rb

@@ -0,0 +1,59 @@
+module CabbageDoc
+  class Params
+    include Enumerable
+
+    def initialize(params, collection)
+      @_params = convert(params, collection)
+    end
+
+    def each
+      @_params.each do |k, v|
+        yield(k, v)
+      end
+    end
+
+    def delete(key)
+      @_params.delete(key)
+    end
+
+    def find(key)
+      @_params[key]
+    end
+
+    def valid?
+      @_params.any?
+    end
+
+    def to_hash
+      @_params
+    end
+
+    def to_query
+      @_params.map do |k, v|
+        if v.is_a?(Array)
+          v.map { |vv| "#{k}[]=#{CGI.escape(vv)}" }
+        else
+          "#{k}=#{CGI.escape(v)}"
+        end
+      end.flatten.join('&')
+    end
+
+    private
+
+    def convert(params, collection)
+      method = params['method']
+      action = params['action']
+
+      return {} unless action && method
+
+      action = collection.find_action(method, action)
+      return {} unless action
+
+      {}.tap do |hash|
+        params.each do |k, v|
+          hash[k] = v if action.param?(k.sub(/\[\]$/, ''))
+        end
+      end
+    end
+  end
+end

data/lib/cabbage_doc/parser.rb

@@ -0,0 +1,47 @@
+module CabbageDoc
+  module Parser
+    class << self
+      def included(base)
+        base.extend(ClassMethods)
+      end
+    end
+
+    module ClassMethods
+      def parse(text)
+        instance = new
+        instance if instance.parse(text)
+      end
+    end
+
+    def parse(text)
+      raise NotImplementedError
+    end
+
+    def parse_option(text)
+      m = text.match(/^\((.*?)\)$/)
+      return {} unless m
+
+      {}.tap do |hash|
+        m[1].split(/,/).map(&:strip).each do |o|
+          k, v = o.split(':').map(&:strip)
+          next unless k && v
+
+          v = v.split('|').map(&:strip)
+          v = v.first if v.size == 1
+
+          hash[k.to_sym] = v
+        end
+      end
+    end
+
+    def parse_templates(text)
+      templates = []
+
+      text.scan(/(\{(.*?)\})/) do
+        templates << { text: $1, values: $2.split(/,/).map(&:strip) }
+      end
+
+      templates
+    end
+  end
+end

data/lib/cabbage_doc/path.rb

@@ -0,0 +1,9 @@
+module CabbageDoc
+  class Path
+    class << self
+      def join(*args)
+        args.join('/').gsub(/\/+/, '/')
+      end
+    end
+  end
+end