tomdoc 0.1.0

data/lib/tomdoc/generators/console.rb

@@ -0,0 +1,68 @@
+module TomDoc
+  module Generators
+    class Console < Generator
+      def highlight(text)
+        pygments(text, '-l', 'ruby')
+      end
+
+      def write_scope_header(scope, prefix = '')
+        return if scope.tomdoc.to_s.empty?
+        write_method(scope, prefix)
+      end
+
+      def write_method(method, prefix = '')
+        write '-' * 80
+        write "#{prefix}#{method.name}#{args(method)}".bold, ''
+        write format_comment(method.tomdoc)
+      end
+
+      def args(method)
+        return '' if !method.respond_to?(:args)
+        if method.args.any?
+          '(' + method.args.join(', ') + ')'
+        else
+          ''
+        end
+      end
+
+      def format_comment(comment)
+        comment = comment.to_s
+
+        # Strip leading comments
+        comment.gsub!(/^# ?/, '')
+
+        # Example code
+        comment.gsub!(/(\s*Examples\s*(.+?)\s*Returns)/m) do
+          $1.sub($2, highlight($2))
+        end
+
+        # Param list
+        comment.gsub!(/^(\s*(\w+) +- )/) do
+          param = $2
+          $1.sub(param, param.green)
+        end
+
+        # true/false/nil
+        comment.gsub!(/(true|false|nil)/, '\1'.magenta)
+
+        # Strings
+        comment.gsub!(/('.+?')/, '\1'.yellow)
+        comment.gsub!(/(".+?")/, '\1'.yellow)
+
+        # Symbols
+        comment.gsub!(/(\s+:\w+)/, '\1'.red)
+
+        # Constants
+        comment.gsub!(/(([A-Z]\w+(::)?)+)/) do
+          if constant?($1.strip)
+            $1.split('::').map { |part| part.cyan }.join('::')
+          else
+            $1
+          end
+        end
+
+        comment
+      end
+    end
+  end
+end

data/lib/tomdoc/generators/html.rb

@@ -0,0 +1,42 @@
+module TomDoc
+  module Generators
+    class HTML < Generator
+      def highlight(text)
+        pygments(text, '-l', 'ruby', '-f', 'html')
+      end
+
+      def write_scope_header(scope, prefix)
+      end
+
+      def write_scope_footer(scope, prefix)
+      end
+
+      def write_class_methods(scope, prefix)
+        out = '<ul>'
+        out << super.to_s
+        write out
+      end
+
+      def write_instance_methods(scope, prefix)
+        out = ''
+        out << super.to_s
+        out << '</ul>'
+        write out
+      end
+
+      def write_method(method, prefix = '')
+        if method.args.any?
+          args = '(' + method.args.join(', ') + ')'
+        end
+        out = '<li>'
+        out << "<b>#{prefix}#{method.to_s}#{args}</b>"
+
+        out << '<pre>'
+        out << method.tomdoc.tomdoc
+        out << '</pre>'
+
+        out << '</li>'
+      end
+    end
+  end
+end

data/lib/tomdoc/method.rb

@@ -0,0 +1,21 @@
+module TomDoc
+  # A Method can be instance or class level.
+  class Method
+    attr_accessor :name, :comment, :args
+
+    def initialize(name, comment = '', args = [])
+      @name    = name
+      @comment = comment
+      @args    = args || []
+    end
+    alias_method :to_s, :name
+
+    def tomdoc
+      @tomdoc ||= TomDoc.new(@comment)
+    end
+
+    def inspect
+      "#{name}(#{args.join(', ')})"
+    end
+  end
+end

data/lib/tomdoc/scope.rb

@@ -0,0 +1,46 @@
+module TomDoc
+  # A Scope is a Module or Class.
+  # It may contain other scopes.
+  class Scope
+    include Enumerable
+
+    attr_accessor :name, :comment, :instance_methods, :class_methods
+    attr_accessor :scopes
+
+    def initialize(name, comment = '', instance_methods = [], class_methods = [])
+      @name = name
+      @comment = comment
+      @instance_methods = instance_methods
+      @class_methods = class_methods
+      @scopes = {}
+    end
+
+    def tomdoc
+      @tomdoc ||= TomDoc.new(@comment)
+    end
+
+    def [](scope)
+      @scopes[scope]
+    end
+
+    def keys
+      @scopes.keys
+    end
+
+    def each(&block)
+      @scopes.each(&block)
+    end
+
+    def to_s
+      inspect
+    end
+
+    def inspect
+      scopes = @scopes.keys.join(', ')
+      imethods = @instance_methods.inspect
+      cmethods = @class_methods.inspect
+
+      "<#{name} scopes:[#{scopes}] :#{cmethods}: ##{imethods}#>"
+    end
+  end
+end

data/lib/tomdoc/source_parser.rb

@@ -0,0 +1,145 @@
+module TomDoc
+  class SourceParser
+    # Converts Ruby code into a data structure.
+    #
+    # text - A String of Ruby code.
+    #
+    # Returns a Hash with each key a namespace and each value another
+    #   Hash or a TomDoc::Scope.
+    def self.parse(text)
+      new.parse(text)
+    end
+
+    attr_accessor :parser, :scopes, :options
+
+    # Each instance of SourceParser accumulates scopes with each
+    # parse, making it easy to parse an entire project in chunks but
+    # more difficult to parse disparate files in one go. Create
+    # separate instances for separate global scopes.
+    #
+    # Returns an instance of TomDoc::SourceParser
+    def initialize(options = {})
+      @options = {}
+      @parser  = RubyParser.new
+      @scopes  = {}
+    end
+
+    # Resets the state of the parser to a pristine one. Maintains options.
+    #
+    # Returns nothing.
+    def reset
+      initialize(@options)
+    end
+
+    # Converts Ruby code into a data structure. Note that at the
+    # instance level scopes accumulate, which makes it easy to parse
+    # multiple files in a single project but harder to parse files
+    # that have no connection.
+    #
+    # text - A String of Ruby code.
+    #
+    # Examples
+    #   @parser = TomDoc::SourceParser.new
+    #   files.each do |file|
+    #     @parser.parse(File.read(file))
+    #   end
+    #   pp @parser.scopes
+    #
+    # Returns a Hash with each key a namespace and each value another
+    #   Hash or a TomDoc::Scope.
+    def parse(text)
+      process(tokenize(sexp(text)))
+      @scopes
+    end
+
+    # Converts Ruby sourcecode into an AST.
+    #
+    # text - A String of Ruby source.
+    #
+    # Returns a Sexp representing the AST.
+    def sexp(text)
+      @parser.parse(text)
+    end
+
+    # Converts a tokenized Array of classes, modules, and methods into
+    # Scopes and Methods, adding them to the @scopes instance variable
+    # as it works.
+    #
+    # ast   - Tokenized Array produced by calling `tokenize`.
+    # scope - An optional Scope object for nested classes or modules.
+    #
+    # Returns nothing.
+    def process(ast, scope = nil)
+      case Array(ast)[0]
+      when :module, :class
+        name = ast[1]
+        new_scope = Scope.new(name, ast[2])
+
+        if scope
+          scope.scopes[name] = new_scope
+        elsif @scopes[name]
+          new_scope = @scopes[name]
+        else
+          @scopes[name] = new_scope
+        end
+
+        process(ast[3], new_scope)
+      when :imethod
+        ast.shift
+        scope.instance_methods << Method.new(*ast)
+      when :cmethod
+        ast.shift
+        scope.class_methods << Method.new(*ast)
+      when Array
+        ast.map { |a| process(a, scope) }
+      end
+    end
+
+    # Converts a Ruby AST-style Sexp into an Array of more useful tokens.
+    #
+    # node - A Ruby AST Sexp or Array
+    #
+    # Examples
+    #
+    #   [:module, :Math, "",
+    #     [:class, :Multiplexer, "# Class Comment",
+    #       [:cmethod,
+    #         :multiplex, "# Class Method Comment", [:text]],
+    #       [:imethod,
+    #         :multiplex, "# Instance Method Comment", [:text, :count]]]]
+    #
+    #   # In others words:
+    #   # [ :type, :name, :comment, other ]
+    #
+    # Returns an Array in the above format.
+    def tokenize(node)
+      case Array(node)[0]
+      when :module
+        name = node[1]
+        [ :module, name, node.comments, tokenize(node[2]) ]
+      when :class
+        name = node[1]
+        [ :class, name, node.comments, tokenize(node[3]) ]
+      when :defn
+        name = node[1]
+        args = args_for_node(node[2])
+        [ :imethod, name, node.comments, args ]
+      when :defs
+        name = node[2]
+        args = args_for_node(node[3])
+        [ :cmethod, name, node.comments, args ]
+      when :block
+        tokenize(node[1..-1])
+      when :scope
+        tokenize(node[1])
+      when Array
+        node.map { |n| tokenize(n) }.compact
+      end
+    end
+
+    # Given a method sexp, returns an array of the args.
+    def args_for_node(node)
+      Array(node)[1..-1].select { |arg| arg.is_a? Symbol }
+    end
+  end
+end

data/lib/tomdoc/tomdoc.rb

@@ -0,0 +1,133 @@
+module TomDoc
+  class InvalidTomDoc < RuntimeError
+    def initialize(doc)
+      @doc = doc
+    end
+
+    def message
+      @doc
+    end
+
+    def to_s
+      @doc
+    end
+  end
+
+  class TomDoc
+    attr_accessor :raw
+
+    def initialize(text)
+      @raw = text.to_s.strip
+    end
+
+    def to_s
+      @raw
+    end
+
+    def self.valid?(text)
+      new(text).valid?
+    end
+
+    def valid?
+      validate
+    rescue InvalidTomDoc
+      false
+    end
+
+    def validate
+      if !raw.include?('Returns')
+        raise InvalidTomDoc.new("No `Returns' statement.")
+      end
+
+      if tomdoc.split("\n\n").size < 2
+        raise InvalidTomDoc.new("No description section found.")
+      end
+
+      true
+    end
+
+    def tomdoc
+      clean = raw.split("\n").map do |line|
+        line =~ /^(\s*# ?)/ ? line.sub($1, '') : nil
+      end.compact.join("\n")
+
+      clean
+    end
+
+    def sections
+      tomdoc.split("\n\n")
+    end
+
+    def description
+      sections.first
+    end
+
+    def args
+      args = []
+      last_indent = nil
+
+      sections[1].split("\n").each do |line|
+        next if line.strip.empty?
+        indent = line.scan(/^\s*/)[0].to_s.size
+
+        if last_indent && indent > last_indent
+          args.last.description += line.squeeze(" ")
+        else
+          param, desc = line.split(" - ")
+          args << Arg.new(param.strip, desc.strip) if param && desc
+        end
+
+        last_indent = indent
+      end
+
+      args
+    end
+
+    def examples
+      if tomdoc =~ /(\s*Examples\s*(.+?)\s*(?:Returns|Raises))/m
+        $2.split("\n\n")
+      else
+        []
+      end
+    end
+
+    def returns
+      if tomdoc =~ /^\s*(Returns.+)/m
+        lines = $1.split("\n")
+        statements = []
+
+        lines.each do |line|
+          next if line =~ /^\s*Raises/
+          if line =~ /^\s+/
+            statements.last << line.squeeze(' ')
+          else
+            statements << line
+          end
+        end
+
+        statements
+      else
+        []
+      end
+    end
+
+    def raises
+      if tomdoc =~ /^\s*(Raises.+)/m
+        lines = $1.split("\n")
+        statements = []
+
+        lines.each do |line|
+          if line =~ /^\s+/
+            statements.last << line.squeeze(' ')
+          else
+            statements << line
+          end
+        end
+
+        statements
+      else
+        []
+      end
+    end
+  end
+end