tomdoc 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Tom Preston-Werner, Chris Wanstrath
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+Software), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,104 @@
+TomDoc
+======
+
+TomDoc is documentation for humans.  Using a few simple rules and zero 
+special syntax you can produce great looking documentation for both humans 
+and machines.
+
+Just follow these four easy steps:
+
+1. Describe your method
+2. Optionally list and describe its arguments
+3. Optionally list some examples
+4. Explain what your method returns
+
+Like this:
+
+    # Duplicate some text an abitrary number of times.
+    #
+    # text  - The String to be duplicated.
+    # count - The Integer number of times to duplicate the text.
+    #
+    # Examples
+    #   multiplex('Tom', 4)
+    #   # => 'TomTomTomTom'
+    #
+    # Returns the duplicated String.
+    def multiplex(text, count)
+      text * count
+    end
+
+See [the manual][man] or [the spec][spec] for a more in-depth
+analysis.
+
+
+tomdoc.rb
+---------
+
+This repository contains tomdoc.rb, a Ruby library for parsing
+TomDoc and generating pretty documentation from it.
+
+
+Installation
+------------
+
+    easy_install Pygments
+    gem install tomdoc
+
+tomdoc.rb has been tested with Ruby 1.8.7.
+
+
+Usage
+-----
+
+    $ tomdoc file.rb
+    # Prints colored documentation of file.rb.
+
+    $ tomdoc file.rb -n STRING
+    # Prints methods or classes in file.rb matching STRING.
+
+    $ tomdoc fileA.rb fileB.rb ...
+    # Prints colored documentation of multiple files.
+
+    $ tomdoc -f html file.rb
+    # Prints HTML documentation of file.rb.
+
+    $ tomdoc -i file.rb
+    # Ignore TomDoc validation, print any methods we find.
+
+    $ tomdoc -h
+    # Displays more options.
+
+
+Ruby API
+--------
+
+Fully TomDoc'd. Well, it will be.
+
+For now:
+
+    $ tomdoc lib/tomdoc/source_parser.rb
+
+
+Formats
+-------
+
+### Console
+
+    tomdoc lib/tomdoc/source_parser.rb -n token
+
+![pattern](http://img.skitch.com/20100408-mnyxuxb4xrrg5x4pnpsmuth4mu.png)
+
+### HTML
+
+    tomdoc -f html lib/tomdoc/source_parser.rb | browser
+
+or
+
+    tomdoc -f html lib/tomdoc/source_parser.rb > doc.html
+    open doc.html
+
+![html](http://img.skitch.com/20100408-dbhtc4mef2q3ygmn63csxgh14w.png)
+
+[man]: https://github.com/defunkt/tomdoc/blob/tomdoc.rb/man/tomdoc.5.ronn
+[spec]: https://github.com/defunkt/tomdoc/blob/tomdoc.rb/tomdoc.md

data/Rakefile

@@ -0,0 +1,80 @@
+require 'rake/testtask'
+
+def command?(command)
+  system("type #{command} > /dev/null 2>&1")
+end
+
+#
+# Manual
+#
+
+if command? :ronn
+  desc "Build and display the manual."
+  task :man => "man:build" do
+    exec "man man/tomdoc.5"
+  end
+
+  desc "Build and display the manual in your browser."
+  task "man:html" => "man:build" do
+    sh "open man/tomdoc.5.html"
+  end
+
+  desc "Build the manual"
+  task "man:build" do
+    sh "ronn -br5 --organization=MOJOMBO --manual='TomDoc Manual' man/*.ronn"
+  end
+end
+
+
+#
+# Tests
+#
+
+task :default => :test
+
+if command? :turn
+  desc "Run tests"
+  task :test do
+    suffix = "-n #{ENV['TEST']}" if ENV['TEST']
+    sh "turn test/*.rb #{suffix}"
+  end
+else
+  Rake::TestTask.new do |t|
+    t.libs << 'lib'
+    t.pattern = 'test/**/*_test.rb'
+    t.verbose = false
+  end
+end
+
+
+#
+# Development
+#
+
+desc "Drop to irb."
+task :console do
+  exec "irb -I lib -rtomdoc"
+end
+
+
+#
+# Gems
+#
+
+begin
+  require 'tomdoc/version'
+  require 'mg'
+  MG.new("tomdoc.gemspec")
+
+  desc "Push a new version to Gemcutter and publish docs."
+  task :publish => "gem:publish" do
+    require File.dirname(__FILE__) + '/lib/tomdoc/version'
+
+    sh "git tag v#{TomDoc::VERSION}"
+    sh "git push origin master --tags"
+    sh "git clean -fd"
+  end
+rescue LoadError
+  warn "mg not available."
+  warn "Install it with: gem i mg"
+end

data/bin/tomdoc

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require 'tomdoc'
+
+# Process options
+TomDoc::CLI.parse_options(ARGV)

data/lib/tomdoc.rb

@@ -0,0 +1,25 @@
+require 'pp'
+
+require 'ruby_parser'
+require 'colored'
+
+module TomDoc
+  autoload :Open3,        'open3'
+
+  autoload :CLI,          'tomdoc/cli'
+
+  autoload :Scope,        'tomdoc/scope'
+  autoload :Method,       'tomdoc/method'
+  autoload :Arg,          'tomdoc/arg'
+  autoload :TomDoc,       'tomdoc/tomdoc'
+
+  autoload :SourceParser, 'tomdoc/source_parser'
+  autoload :Generator,    'tomdoc/generator'
+
+  autoload :VERSION,      'tomdoc/version'
+
+  module Generators
+    autoload :Console, 'tomdoc/generators/console'
+    autoload :HTML,    'tomdoc/generators/html'
+  end
+end

data/lib/tomdoc/arg.rb

@@ -0,0 +1,14 @@
+module TomDoc
+  class Arg
+    attr_accessor :name, :description
+
+    def initialize(name, description = '')
+      @name = name.to_s.intern
+      @description = description
+    end
+
+    def optional?
+      @description.downcase.include? 'optional'
+    end
+  end
+end

data/lib/tomdoc/cli.rb

@@ -0,0 +1,150 @@
+require 'optparse'
+
+module TomDoc
+  class CLI
+    #
+    # DSL Magics
+    #
+
+    def self.options(&block)
+      block ? (@options = block) : @options
+    end
+
+    def options
+      OptionParser.new do |opts|
+        opts.instance_eval(&self.class.options)
+      end
+    end
+
+    def pp(*args)
+      require 'pp'
+      super
+    end
+
+
+    #
+    # Define Options
+    #
+
+    options do
+      @options = {}
+
+      self.banner = "Usage: tomdoc [options] FILE1 FILE2 ..."
+
+      separator " "
+      separator "Examples:"
+      separator <<example
+  $ tomdoc file.rb
+  # Prints colored documentation of file.rb.
+
+  $ tomdoc file.rb -n STRING
+  # Prints methods or classes in file.rb matching STRING.
+
+  $ tomdoc -f html file.rb
+  # Prints HTML documentation of file.rb.
+example
+
+      separator " "
+      separator "Options:"
+
+      on "-c", "--colored", "Pass -p, -s, or -t output to Pygments." do
+        ARGV.delete('-c') || ARGV.delete('--colored')
+        exec "#{$0} #{ARGV * ' '} | pygmentize -l ruby"
+      end
+
+      on "-t", "--tokens", "Parse FILE and print the tokenized form." do
+        sexp = SourceParser.new.sexp(argf.read)
+        pp SourceParser.new.tokenize(sexp)
+        exit
+      end
+
+      on "-s", "--sexp", "Parse FILE and print the AST's sexps." do
+        pp RubyParser.new.parse(argf.read).to_a
+        exit
+      end
+
+      on "-n", "--pattern=PATTERN",
+        "Limit results to strings matching PATTERN." do |pattern|
+
+        @options[:pattern] = pattern
+      end
+
+      on "-f", "--format=FORMAT",
+        "Parse FILE and print the TomDoc as FORMAT." do |format|
+
+        if format.to_s.downcase == "html"
+          puts Generators::HTML.new(@options).generate(argf.read)
+          exit
+        end
+      end
+
+      on "-i", "--ignore",
+        "Ignore validation, print all methods we find with comments.." do
+
+        @options[:validate] = false
+      end
+
+      separator " "
+      separator "Common Options:"
+
+      on "-v", "--version", "Print the version" do
+        puts "TomDoc v#{VERSION}"
+        exit
+      end
+
+      on "-h", "--help", "Show this message" do
+        puts self
+        exit
+      end
+
+      on_tail do
+        puts Generators::Console.new(@options).generate(argf.read)
+        exit
+      end
+
+      separator ""
+    end
+
+
+    #
+    # Actions
+    #
+
+    def self.parse_options(args)
+      new.parse_options(args)
+    end
+
+    def parse_options(args)
+      options.parse(args)
+    end
+  end
+end
+
+class OptionParser
+  # ARGF faker.
+  def argf
+    buffer = ''
+
+    ARGV.select { |arg| File.exists?(arg) }.each do |file|
+      buffer << File.read(file)
+    end
+
+    require 'stringio'
+    StringIO.new(buffer)
+  end
+end
+
+
+#
+# Main
+#
+
+# Help is the default.
+ARGV << '-h' if ARGV.empty? && $stdin.tty?
+
+# Process options
+TomDoc::CLI.parse_options(ARGV) if $stdin.tty?
+
+# Still here - process ARGF
+TomDoc::CLI.process_files(ARGF)
+

data/lib/tomdoc/generator.rb

@@ -0,0 +1,138 @@
+module TomDoc
+  class Generator
+    attr_reader :options, :scopes
+
+    # Creates a Generator.
+    #
+    # options - Optional Symbol-keyed Hash:
+    #             :validate - Whether or not to validate TomDoc.
+    #
+    # scopes - Optional Symbol-keyed Hash.
+    #
+    # Returns an instance of TomDoc::Generator
+    def initialize(options = {}, scopes = {})
+      @options = {
+        :validate => true
+      }
+      @options.update(options)
+
+      @scopes = {}
+      @buffer = ''
+    end
+
+    def self.generate(text_or_sexp)
+      new.generate(text_or_sexp)
+    end
+
+    def generate(text_or_sexp)
+      if text_or_sexp.is_a?(String)
+        sexp = SourceParser.parse(text_or_sexp)
+      else
+        sexp = text_or_sexp
+      end
+
+      process(sexp)
+    end
+
+    def process(scopes = {}, prefix = nil)
+      old_scopes = @scopes
+      @scopes = scopes
+      scopes.each do |name, scope|
+        write_scope(scope, prefix)
+        process(scope, "#{name}::")
+      end
+
+      @buffer
+    ensure
+      @scopes = old_scopes || {}
+    end
+
+    def write_scope(scope, prefix)
+      write_scope_header(scope, prefix)
+      write_class_methods(scope, prefix)
+      write_instance_methods(scope, prefix)
+      write_scope_footer(scope, prefix)
+    end
+
+    def write_scope_header(scope, prefix)
+    end
+
+    def write_scope_footer(scope, prefix)
+    end
+
+    def write_class_methods(scope, prefix = nil)
+      prefix ="#{prefix}#{scope.name}."
+
+      scope.class_methods.map do |method|
+        next if !valid?(method, prefix)
+        write_method(method, prefix)
+      end.compact
+    end
+
+    def write_instance_methods(scope, prefix = nil)
+      prefix = "#{prefix}#{scope.name}#"
+
+      scope.instance_methods.map do |method|
+        next if !valid?(method, prefix)
+        write_method(method, prefix)
+      end.compact
+    end
+
+    def write_method(method, prefix = '')
+    end
+
+    def write(*things)
+      things.each do |thing|
+        @buffer << "#{thing}\n"
+      end
+
+      nil
+    end
+
+    def pygments(text, *args)
+      out = ''
+
+      Open3.popen3("pygmentize", *args) do |stdin, stdout, stderr|
+        stdin.puts text
+        stdin.close
+        out = stdout.read.chomp
+      end
+
+      out
+    end
+
+    def constant?(const)
+      const = const.split('::').first if const.include?('::')
+      constant_names.include?(const.intern) || Object.const_defined?(const)
+    end
+
+    def constant_names
+      name = @scopes.name if @scopes.respond_to?(:name)
+      [ :Boolean, :Test, name ].compact + @scopes.keys
+    end
+
+    def valid?(object, prefix)
+      matches_pattern?(prefix, object.name) && valid_tomdoc?(object.tomdoc)
+    end
+
+    def matches_pattern?(prefix, name)
+      if pattern = options[:pattern]
+        # "-n hey" vs "-n /he.+y/"
+        if pattern =~ /^\/.+\/$/
+          pattern = pattern.sub(/^\//, '').sub(/\/$/, '')
+          regexp = Regexp.new(pattern)
+        else
+          regexp = Regexp.new(Regexp.escape(pattern))
+        end
+
+        regexp =~ name.to_s || regexp =~ prefix.to_s
+      else
+        true
+      end
+    end
+
+    def valid_tomdoc?(comment)
+      options[:validate] ? TomDoc.valid?(comment) : true
+    end
+  end
+end