distil 0.11.6 → 0.11.8

data/vendor/pdoc/test/unit/parser/test_fragment.rb

@@ -0,0 +1,80 @@
+require "test/unit"
+require "../../../lib/pdoc/parser/fragment"
+require "../../../lib/pdoc/error"
+
+class TestFragment < Test::Unit::TestCase
+  
+  def test_normalize_empty_fragment
+    fragment =<<EOF
+    /**
+    *
+    *
+    **/
+EOF
+    fragment = PDoc::Fragment.new(fragment, 0)
+    lines = fragment.normalize
+    assert_equal("", lines[0])
+    assert_equal("", lines[1])
+    assert_equal("", lines.last)
+  end
+  
+  def test_normalize_basic_fragment
+    fragment =<<EOF
+    /**
+    * foo
+    *   bar
+    **/
+EOF
+    fragment = PDoc::Fragment.new(fragment, 0)
+    lines = fragment.normalize
+    assert_equal("", lines[0])
+    assert_equal("foo", lines[1])
+    assert_equal("  bar", lines[2])
+    assert_equal("", lines.last)
+  end
+  
+  def test_normalize_broken_fragment
+    fragment =<<EOF
+    /**
+    * foo
+    *bar
+    **/
+EOF
+    assert_raise PDoc::Fragment::InconsistentPrefixError do
+      PDoc::Fragment.new(fragment, 0).normalize
+    end
+  end
+  
+  def test_empty_prefix
+    fragment =<<EOF
+/**
+foo
+  bar
+**/
+EOF
+    fragment = PDoc::Fragment.new(fragment, 0)
+    assert_equal("", fragment.prefix)
+  end
+  
+  def test_whitespace_prefix
+    fragment =<<EOF
+    /**
+  foo
+    bar
+  **/
+EOF
+    fragment = PDoc::Fragment.new(fragment, 0)
+    assert_equal("  ", fragment.prefix)
+  end
+
+  def test_mixed_prefix
+    fragment =<<EOF
+/**
+ * foo
+ *   bar
+ **/
+EOF
+    fragment = PDoc::Fragment.new(fragment, 0)
+    assert_equal(" * ", fragment.prefix)
+  end 
+end

data/vendor/pdoc/test/unit/parser_test_helper.rb

@@ -0,0 +1,62 @@
+require 'test/unit'
+
+require File.expand_path(File.join(File.dirname(__FILE__), "..", "..", "lib", "pdoc")) unless defined?(PDoc)
+
+class Treetop::Runtime::SyntaxNode 
+  def method_missing(method, *args)
+    raise "Node representing '#{text_value}' does not respond to '#{method}'"
+  end
+end
+
+module PDocTestHelper
+  def parse(input)
+    result = @parser.parse(input)
+    unless result
+      puts "\n" << @parser.terminal_failures.join("\n") << "\n"
+    end
+    assert !result.nil?
+    result
+  end
+  
+  def blank_line
+    "\n * \n "
+  end
+  
+  def parse_file(filename)
+    path = File.expand_path(File.join(File.dirname(__FILE__), "..", "fixtures", filename))
+    file = File.open(path){ |f| f.read }
+    file.gsub!(/\r\n/, "\n")
+    file = file.split("\n").map do |line|
+      line.gsub(/\s+$/, '')
+    end.join("\n")
+    parse(file)
+  end
+  
+  def assert_parsed(input)
+    assert !parse(input).nil?
+  end
+  
+  def assert_file_parsed(filename)
+    assert !parse_file(filename).nil?
+  end
+  
+  def assert_not_parsed(input)
+    assert @parser.parse(input).nil?
+  end
+end
+
+# Stolen from Rails
+unless :test.respond_to?(:to_proc)
+  class Symbol
+    # Turns the symbol into a simple proc, which is especially useful for enumerations. Examples:
+    #
+    #   # The same as people.collect { |p| p.name }
+    #   people.collect(&:name)
+    #
+    #   # The same as people.select { |p| p.manager? }.collect { |p| p.salary }
+    #   people.select(&:manager?).collect(&:salary)
+    def to_proc
+      Proc.new { |*args| args.shift.__send__(self, *args) }
+    end
+  end
+end

data/vendor/pdoc/test/unit/runner/basic_test.rb

@@ -0,0 +1,14 @@
+require File.expand_path(File.join(File.dirname(__FILE__), "..", "parser_test_helper"))
+
+class BasicTest < Test::Unit::TestCase
+  
+  def test_restores_original_dir
+    original_dir = Dir.pwd
+    puts "*** #{original_dir}"
+    PDoc::Runner.new("test/fixtures/test.txt",
+      :output    => 'test/output',
+      :templates => 'templates/html'
+    ).run
+    assert_equal original_dir, Dir.pwd
+  end
+end

data/vendor/pdoc/test/unit/templates/html_helpers_test.rb

@@ -0,0 +1,25 @@
+require File.expand_path(File.join(File.dirname(__FILE__), "..", "parser_test_helper"))
+require File.expand_path(File.join(File.dirname(__FILE__), *%w[.. .. .. templates html helpers]))
+
+class HtmlHelpersTest < Test::Unit::TestCase
+  include PDocTestHelper
+  # include EbnfExpression
+  
+  def setup
+    @helper = Object.new
+    class << @helper
+      attr_accessor :root
+      include PDoc::Generators::Html::Helpers::BaseHelper
+      include PDoc::Generators::Html::Helpers::LinkHelper
+      include PDoc::Generators::Html::Helpers::CodeHelper
+      
+      def path_to(foo)
+        '/some/path' # Not tested here, although it should
+      end
+    end
+  end
+  
+  def test_truth
+    assert true
+  end
+end

data/vendor/pdoc/vendor/albino.rb

@@ -0,0 +1,122 @@
+##
+# Wrapper for the Pygments command line tool, pygmentize.
+#
+# Pygments: http://pygments.org/
+#
+# Assumes pygmentize is in the path.  If not, set its location
+# with Albino.bin = '/path/to/pygmentize'
+#
+# Use like so:
+#
+#   @syntaxer = Albino.new('/some/file.rb', :ruby)
+#   puts @syntaxer.colorize
+#
+# This'll print out an HTMLized, Ruby-highlighted version
+# of '/some/file.rb'.
+#
+# To use another formatter, pass it as the third argument:
+#
+#   @syntaxer = Albino.new('/some/file.rb', :ruby, :bbcode)
+#   puts @syntaxer.colorize
+#
+# You can also use the #colorize class method:
+#
+#   puts Albino.colorize('/some/file.rb', :ruby)
+#
+# Another also: you get a #to_s, for somewhat nicer use in Rails views.
+#
+#   ... helper file ...
+#   def highlight(text)
+#     Albino.new(text, :ruby)
+#   end
+#
+#   ... view file ...
+#   <%= highlight text %>
+#
+# The default lexer is 'text'.  You need to specify a lexer yourself;
+# because we are using STDIN there is no auto-detect.
+#
+# To see all lexers and formatters available, run `pygmentize -L`.
+#
+# Chris Wanstrath // chris@ozmm.org
+#         GitHub // http://github.com
+#
+require 'open4'
+
+class Albino
+  @@bin = Rails.development? ? 'pygmentize' : '/usr/bin/pygmentize' rescue 'pygmentize'
+
+  def self.bin=(path)
+    @@bin = path
+  end
+
+  def self.colorize(*args)
+    new(*args).colorize
+  end
+
+  def initialize(target, lexer = :text, format = :html)
+    @target  = File.exists?(target) ? File.read(target) : target rescue target
+    @options = { :l => lexer, :f => format, :O => 'encoding=utf-8' }
+  end
+
+  def execute(command)
+    output = ''
+    Open4.popen4(command) do |pid, stdin, stdout, stderr|
+      stdin.puts @target
+      stdin.close
+      output = stdout.read.strip
+      [stdout, stderr].each { |io| io.close }
+    end
+    output
+  end
+
+  def colorize(options = {})
+    html = execute(@@bin + convert_options(options))
+    # Work around an RDiscount bug: http://gist.github.com/97682
+    html.to_s.sub(%r{</pre></div>\Z}, "</pre>\n</div>")
+  end
+  alias_method :to_s, :colorize
+
+  def convert_options(options = {})
+    @options.merge(options).inject('') do |string, (flag, value)|
+      string + " -#{flag} #{value}"
+    end
+  end
+end
+
+if $0 == __FILE__
+  require 'rubygems'
+  require 'test/spec'
+  require 'mocha'
+  begin require 'redgreen'; rescue LoadError; end
+
+  context "Albino" do
+    setup do
+      @syntaxer = Albino.new(__FILE__, :ruby)
+    end
+
+    specify "defaults to text" do
+      syntaxer = Albino.new(__FILE__)
+      syntaxer.expects(:execute).with('pygmentize -f html -l text').returns(true)
+      syntaxer.colorize
+    end
+
+    specify "accepts options" do
+      @syntaxer.expects(:execute).with('pygmentize -f html -l ruby').returns(true)
+      @syntaxer.colorize
+    end
+
+    specify "works with strings" do
+      syntaxer = Albino.new('class New; end', :ruby)
+      assert_match %r(highlight), syntaxer.colorize
+    end
+
+    specify "aliases to_s" do
+      assert_equal @syntaxer.colorize, @syntaxer.to_s
+    end
+
+    specify "class method colorize" do
+      assert_equal @syntaxer.colorize, Albino.colorize(__FILE__, :ruby)
+    end
+  end
+end

data/vendor/pdoc/website/html/documentation.html

@@ -0,0 +1,280 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
+   "http://www.w3.org/TR/html4/strict.dtd">
+
+<html lang="en">
+<head>
+	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+	<title>PDoc</title>
+	<meta name="generator" content="TextMate http://macromates.com/">
+	<meta name="author" content="Tobie Langel">
+	<!-- Date: 2008-02-25 -->
+	<link rel="stylesheet" href="/stylesheets/reset.css" type="text/css" media="screen" charset="utf-8">
+	<link rel="stylesheet" href="/stylesheets/main.css" type="text/css" media="screen" title="no title" charset="utf-8">
+	
+</head>
+<body>
+	<div id="wrapper">
+		<div id="header">
+			<h1><a href="/"><img src="/images/pdoc.jpg" alt="PDoc" /></a></h1>
+		</div>
+		<div id="navigation">
+			<ul>
+				<li><a href="/documentation.html">documentation</a></li>
+				<li><a href="http://github.com/tobie/pdoc/tree/master">source code</a></li>
+				<li><a href="http://prototype.lighthouseapp.com/projects/8889-pdoc/">bug tracker</a></li>
+				<li><a href="http://groups.google.com/group/pdoc">mailing list</a></li>
+			</ul>
+		</div>
+		<div id="content">
+<h1 id="documentation">Documentation</h1>
+
+<h2 id="comments">Comments</h2>
+
+<p>Documentation comments start with <code>/**</code> and end with <code>**/</code>. Each new line starts with <code>*</code>. </p>
+
+<pre><code>/** ...
+ *  ...
+ **/
+</code></pre>
+
+<h2 id="tags">Tags</h2>
+
+<p>The first line of a comment is reserved for tags. Tags are separated by a comma followed by whitespace (&#8220;, &#8220;). They can be either a tag name or a key / value pair separated by a colon and a space (<code>:</code>).</p>
+
+<p>Currently accepted tags are: <code>deprecated</code>, <code>section:</code>, <code>alias of:</code>, <code>related to:</code></p>
+
+<pre><code>/** deprecated, section: DOM, alias of: Element#descendantOf
+ *  Element#childOf(@element, className) -&gt; Element
+ *  ...
+ **/
+</code></pre>
+
+<h2 id="ebnf">EBNF</h2>
+
+<p>The lines directly following tags are reserved for the EBNF description of the documented object. Typically, there&#8217;s only one EBNF per documented object. However, some objects might require more than one.</p>
+
+<pre><code>/** 
+ *  Element#down(@element[, cssSelector][, index]) -&gt; Element | null
+ *  ...
+ **/
+
+/** 
+ *  Element#writeAttribute(@element, attribute[, value = true]) -&gt; Element
+ *  Element#writeAttribute(@element, attributes) -&gt; Element
+ *  ...
+ **/
+</code></pre>
+
+<h3 id="arguments">Arguments</h3>
+
+<p>For all methods, functions, etc. parentheses around the arguments are required even if no arguments are present.
+The syntax for arguments is as follows:</p>
+
+<h4 id="required_arguments">required arguments</h4>
+
+<pre><code>/** 
+ *  Event.stop(event) -&gt; Event
+ *  ...
+ **/
+</code></pre>
+
+<h4 id="optional_arguments">optional arguments</h4>
+
+<p>Optional arguments are surrounded by squared brackets (<code>[]</code>).</p>
+
+<pre><code>/** 
+ *  String#evalJSON([sanitize]) -&gt; Object | Array
+ *  ...
+ **/
+</code></pre>
+
+<p>A default value may be indicated using the equal sign (<code>=</code>).</p>
+
+<pre><code>/** 
+ *  String#evalJSON([sanitize = false]) -&gt; Object | Array
+ *  ...
+ **/
+</code></pre>
+
+<p>Note that the argument separating comas belong <em>inside</em> the brackets.</p>
+
+<pre><code>/** 
+ *  Event.findElement(event[, cssSelector]) -&gt; Element | null
+ *  ...
+ **/
+</code></pre>
+
+<p>Arguments can be described below the EBNF description using the following syntax:</p>
+
+<pre><code>- argumentName (acceptedTypes...): description.
+</code></pre>
+
+<p>For example (notice the 4 space indent in the last line): </p>
+
+<pre><code>/** 
+ *  Event.findElement(event[, cssSelector]) -&gt; Element | null
+ *  - event (Event): a native Event instance
+ *  - cssSelector (String): a optional CSS selector which uses
+ *      the same syntax found in regular CSS.
+ **/
+</code></pre>
+
+<h3 id="supported_ebnf_types">Supported EBNF types</h3>
+
+<h4 id="namespace">Namespace</h4>
+
+<pre><code>/** 
+ *  Ajax
+ *  ...
+ **/
+
+/** 
+ *  Prototype.Browser
+ *  ...
+ **/
+</code></pre>
+
+<h4 id="classes">Classes</h4>
+
+<p>Classes require a <code>class</code> prefix:</p>
+
+<pre><code>/** 
+ *  class Ajax.Base
+ *  ...
+ **/
+</code></pre>
+
+<p>Sub-classes can indicate their parent just like in the Ruby syntax:</p>
+
+<pre><code>/** 
+ *  class Ajax.Request &lt; Ajax.Base
+ *  ...
+ **/
+</code></pre>
+
+<p>Where <code>Ajax.Base</code> is the parent class and <code>Ajax.Request</code> the subclass.</p>
+
+<p>Included mixins are indicated like so:</p>
+
+<pre><code>/** 
+ *  class CustomHash
+ *  includes Enumerable, Comparable
+ **/
+</code></pre>
+
+<h4 id="mixins">Mixins</h4>
+
+<p>Mixins are indicated by a <code>mixin</code> prefix:</p>
+
+<pre><code>/** 
+ *  mixin Enumerable
+ *  ...
+ **/
+</code></pre>
+
+<h4 id="constructors">Constructors</h4>
+
+<p>Constructors require the <code>new</code> prefix and their arguments.</p>
+
+<pre><code>/** 
+ *  new Element(tagName[, attributes])
+ *  ...
+ **/
+
+/** 
+ *  new Foobar()
+ *  ...
+ **/
+</code></pre>
+
+<h4 id="klass_methods">Klass Methods</h4>
+
+<p>Klass methods are identified by a dot (<code>.</code>).</p>
+
+<pre><code>/** 
+ *  Array.from([iterable]) -&gt; Array
+ *  ...
+ **/
+</code></pre>
+
+<h4 id="instance_methods">Instance Methods</h4>
+
+<p>Instance methods are identified by the hash symbol (<code>#</code>).</p>
+
+<pre><code>/** 
+ *  Array#first() -&gt; Array element
+ *  ...
+ **/
+</code></pre>
+
+<h4 id="utilities">Utilities</h4>
+
+<p>Utilities are global functions starting with a dollar-sign (<code>$</code>).</p>
+
+<pre><code>/** 
+ *  $w(string) -&gt; Array
+ *  ...
+ **/
+</code></pre>
+
+<h4 id="methodized_methods">Methodized Methods</h4>
+
+<p>Methodized methods are methods which are both available as a class method and an instance method, in which case the first argument becomes the instance object itself. For example, all of <code>Element</code>&#8217;s instance methods are methodized and thus also available as class methods of <code>Element</code>. Methodized methods are indicated by prefixing their first argument with the <code>@</code> symbol.</p>
+
+<pre><code>/** 
+ *  Element#hide(@element) -&gt; Element
+ *  ...
+ **/
+</code></pre>
+
+<h4 id="klass_properties">Klass Properties</h4>
+
+<p>Klass properties are identified by a dot (<code>.</code>).</p>
+
+<pre><code>/** 
+ *  Ajax.Responders.responders -&gt; Array
+ *  ...
+ **/
+</code></pre>
+
+<h4 id="instance_properties">Instance Properties</h4>
+
+<p>Instance properties are identified by the hash symbol (<code>#</code>).</p>
+
+<pre><code>/** 
+ *  Ajax.Response#responseText -&gt; String
+ *  ...
+ **/
+</code></pre>
+
+<h4 id="constants">Constants</h4>
+
+<p>Constant must have their value specified using the equal sign (<code>=</code>).</p>
+
+<pre><code>/** 
+ *  Prototype.JSONFilter = /^\/\*-secure-([\s\S]*)\*\/\s*$/
+ *  ...
+ **/
+</code></pre>
+
+<h3 id="events">Events</h3>
+
+<p>Some methods can fire native or custom events. These are indicated below the arguments descriptions:</p>
+
+<pre><code>/** 
+ *  Ajax.Request#respondToReadyState(readyState) -&gt; undefined
+ *  - readyState (Number): a number from 0 to 4 corresponding to the state of the request.
+ *  fires ajax:created, ajax:completed
+ **/
+</code></pre>
+
+		</div>
+		<div id="sidebar">
+		
+		</div>
+		<div id="footer">
+			<p>&copy; 2008 Tobie Langel. PDoc logo &copy; 2008 Sam Stephenson.</p>
+		</div>
+	</div>
+</body>
+</html>

data/vendor/pdoc/website/html/index.html

@@ -0,0 +1,84 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
+   "http://www.w3.org/TR/html4/strict.dtd">
+
+<html lang="en">
+<head>
+	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+	<title>PDoc</title>
+	<meta name="generator" content="TextMate http://macromates.com/">
+	<meta name="author" content="Tobie Langel">
+	<!-- Date: 2008-02-25 -->
+	<link rel="stylesheet" href="/stylesheets/reset.css" type="text/css" media="screen" charset="utf-8">
+	<link rel="stylesheet" href="/stylesheets/main.css" type="text/css" media="screen" title="no title" charset="utf-8">
+	
+</head>
+<body>
+	<div id="wrapper">
+		<div id="header">
+			<h1><a href="/"><img src="/images/pdoc.jpg" alt="PDoc" /></a></h1>
+		</div>
+		<div id="navigation">
+			<ul>
+				<li><a href="/documentation.html">documentation</a></li>
+				<li><a href="http://github.com/tobie/pdoc/tree/master">source code</a></li>
+				<li><a href="/doc/index.html">rdoc</a></li>
+				<li><a href="http://prototype.lighthouseapp.com/projects/8889-pdoc/">bug tracker</a></li>
+				<li><a href="http://groups.google.com/group/pdoc">mailing list</a></li>
+			</ul>
+		</div>
+		<div id="content">
+			<h1>PDoc</h1>
+
+			<p>PDoc is an inline comment parser and JavaScript documentation generator written in Ruby. It is designed for documenting <a href="http://prototypejs.org">Prototype</a> and Prototype-based libraries.</p>
+
+			<p>PDoc uses <a href="http://treetop.rubyforge.org/">Treetop</a>, a Ruby-based DSL for text parsing and interpretation, and its own ActionView-inspired, ERB-based templating system for HTML generation. Other documentation generators (e.g., DocBook XML) are planned.</p>
+
+			<p>Unlike other inline-doc parsers, PDoc does not rely on the JavaScript source code at all; it only parses the comments. This approach, though slightly more verbose, is much better at generating consistent, reliable documentation, and avoids the headaches encountered when documenting highly dynamic languages.</p>
+
+			<h2>Installation</h2>
+
+			<p>PDoc depends on Rake, <a href="http://maruku.rubyforge.org/">Maruku</a>, and treetop, all of which can be obtained through RubyGems:</p>
+
+			<pre><code>gem install rake maruku treetop
+			</code></pre>
+
+			<p>Maruku is a more solid alternative to BlueCloth and is compatible with Ruby 1.9.1.</p>
+
+			<h2>Usage</h2>
+
+			<p>For hints on how to run PDoc on the command line, consult the built-in Rake tasks (in <code>Rakefile</code>) and the <code>PDoc::Runner</code> class (in <code>lib/pdoc/runner.rb</code>).</p>
+
+			<h2>How it works</h2>
+
+			<p>The process of turning inline PDoc comments into a human-friendly document has two phases.</p>
+
+			<h3>Parsing phase</h3>
+
+			<p>In this phase, the source files are scanned for PDoc comments, then parsed with the Ruby files generated from the Treetop language grammar. The product of this phase is a tree full of specialized classes, all of which inherit from <code>Treetop::Runtime::SyntaxNode</code>.</p>
+
+			<p>The root of the tree is an instance of <code>Documentation::Doc</code>. It comprises one or more instances of <code>Documentation::Section</code>; which in turn comprise language elements like namespaces, classes, constants, etc., all of which have class representations.</p>
+
+			<h3>Rendering phase</h3>
+
+			<p>Next, PDoc asks a <em>generator</em> how to translate this abstract tree into a hierarchical document. The default generator outputs organized HTML in a manner similar to <a href="http://rdoc.sourceforge.net/" title="RDoc - Document Generator for Ruby Source">RDoc</a>&#8217;s.</p>
+
+			<p>The HTML generator (<code>PDoc::Generators::Html</code>) has associated <em>templates</em> (in the <code>templates</code> directory) that accept syntax nodes and echo their metadata onto the page using <a href="http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/index.html" title="erb: Ruby Standard Library Documentation">ERB</a>. Templates are modular, so it&#8217;s quite easy to apply a custom &#8220;skin&#8221; to one&#8217;s documentation pages.</p>
+
+			<p>Furthermore, generators themselves are modular; PDoc can, theoretically, parse once and render to several different targets (HTML, <a href="http://www.docbook.org/" title="DocBook.org">DocBook XML</a>, CHM, PDF, even <a href="http://www.scriptdoc.org/" title="ScriptDoc.org: Dynamic Language Documentation">ScriptDoc</a>.) We hope many such generators will exist in the future.</p>
+			
+			<div id="twitter_div">
+				<h2 class="twitter-title">Twitter Updates</h2>
+				<ul id="twitter_update_list"></ul>
+			</div>
+		</div>
+		<div id="sidebar">
+		
+		</div>
+		<div id="footer">
+			<p>&copy; 2008 Tobie Langel. PDoc logo &copy; 2008 Sam Stephenson.</p>
+		</div>
+	</div>
+	<script type="text/javascript" src="http://twitter.com/javascripts/blogger.js"></script>
+	<script type="text/javascript" src="http://twitter.com/statuses/user_timeline/pdoc.json?callback=twitterCallback2&count=5"></script>
+</body>
+</html>