[ { "path": ".gitignore", "content": "*.gem\n*.rbc\n.bundle\n.config\n.yardoc\nGemfile.lock\nInstalledFiles\n_yardoc\ncoverage\ndoc/\nlib/bundler/man\npkg\nrdoc\nspec/reports\ntest/tmp\ntest/version_tmp\ntmp\n" }, { "path": "CHANGES.md", "content": "CHANGES\n=======\n\n0.8 (2011-06-19)\n----------------\n\nhttps://github.com/rtomayko/rocco/compare/0.7...0.8\n\n0.7 (2011-05-22)\n----------------\n\nhttps://github.com/rtomayko/rocco/compare/0.6...0.7\n\n0.6 (2011-03-05)\n----------------\n\nThis release brought to you almost entirely\nby [mikewest](http://github.com/mikewest).\n\n### Features\n\n* Added `-t`/`--template` CLI option that allows you to specify a Mustache\n template that ought be used when rendering the final documentation.\n (Issue #16)\n\n* More variables in templates:\n * `docs?`: True if `docs` contains text of any sort, False if it's empty.\n * `code?`: True if `code` contains text of any sort, False if it's empty.\n * `empty?`: True if both `code` and `docs` are empty. False otherwise.\n * `header?`: True if `docs` contains _only_ a HTML header. False otherwise.\n\n* Test suite! (Run `rake test`)\n\n* Autodetect file's language if Pygments is installed locally (Issue #19)\n\n* Autopopulate comment characters for known languages (Issue #20)\n\n* Correctly parse block comments (Issue #22)\n\n* Stripping encoding definitions from Ruby and Python files in the same\n way we strip shebang lines (Issue #21)\n\n* Adjusting section IDs to contain descriptive test from headers. A header\n section's ID might be `section-Header_text_goes_here` for friendlier URLs.\n Other section IDs will remain the same (`section-2` will stay\n `section-2`). (Issue #28)\n\n### Bugs Fixed\n\n* Docco's CSS changed: we updated Rocco's HTML accordingly, and pinned\n the CSS file to Docco's 0.3.0 tag. (Issues #12 and #23)\n\n* Fixed code highlighting for shell scripts (among others) (Issue #13)\n\n* Fixed buggy regex for comment char stripping (Issue #15)\n\n* Specifying UTF-8 encoding for Pygments (Issue #10)\n\n* Extensionless file support (thanks to [Vasily Polovnyov][vast] for the\n fix!) (Issue #24)\n\n* Fixing language support for Pygments webservice (Issue #11)\n\n* The source jumplist now generates correctly relative URLs (Issue #26)\n\n* Fixed an issue with using mustache's `template_path=` incorrectly.\n\n[vast]: https://github.com/vast\n\n0.5\n---\n\nRocco 0.5 emerged from the hazy mists, complete and unfettered by history.\n" }, { "path": "COPYING", "content": "Copyright (c) 2010 Ryan Tomayko \n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to\ndeal in the Software without restriction, including without limitation the\nrights to use, copy, modify, merge, publish, distribute, sublicense, and/or\nsell copies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL\nTHE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER \nIN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\nCONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n" }, { "path": "Gemfile", "content": "source :rubygems\n\ngemspec\n" }, { "path": "LICENSE", "content": "Copyright (c) 2010-2014 Ryan Tomayko \n\nPermission is hereby granted, free of charge, to any person\nobtaining a copy of this software and associated documentation\nfiles (the \"Software\"), to deal in the Software without\nrestriction, including without limitation the rights to use,\ncopy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following\nconditions:\n\nThe above copyright notice and this permission notice shall be\nincluded in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES\nOF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\nNONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT\nHOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,\nWHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR\nOTHER DEALINGS IN THE SOFTWARE.\n" }, { "path": "README", "content": "\n\n ___ ___ ___ ___ ___\n /\\ \\ /\\ \\ /\\ \\ /\\ \\ /\\ \\\n /::\\ \\ /::\\ \\ /::\\ \\ /::\\ \\ /::\\ \\\n /::\\:\\__\\ /:/\\:\\__\\ /:/\\:\\__\\ /:/\\:\\__\\ /:/\\:\\__\\\n \\;:::/ / \\:\\/:/ / \\:\\ \\/__/ \\:\\ \\/__/ \\:\\/:/ /\n |:\\/__/ \\::/ / \\:\\__\\ \\:\\__\\ \\::/ /\n \\|__| \\/__/ \\/__/ \\/__/ \\/__/\n\n\n\n Rocco is a quick-and-dirty, literate-programming-style documentation\n generator for Ruby. See the Rocco generated docs for more information:\n\n \n\n\n Rocco is a port of, and borrows heavily from, Docco -- the original\n quick-and-dirty, hundred-line-long, literate-programming-style\n documentation generator in CoffeeScript:\n\n \n\n\n N O L O N G E R M A I N T A I N E D\n\n This repository is archived and no longer actively maintained by\n @rtomayko as of 2017-11-08. Issues and PRs documenting current\n issues have been intentionally left open for informational purposes.\n" }, { "path": "Rakefile", "content": "$LOAD_PATH.unshift 'lib'\n\nrequire 'rake/testtask'\nrequire 'rake/clean'\n\ntask :default => [:sup, :docs, :test]\n\ndesc 'Holla'\ntask :sup do\n verbose do\n lines = File.read('README').split(\"\\n\")[0,12]\n lines.map! { |line| line[15..-1] }\n puts lines.join(\"\\n\")\n end\nend\n\ndesc 'Run tests (default)'\nRake::TestTask.new(:test) do |t|\n t.test_files = FileList['test/suite.rb']\n t.ruby_opts = ['-rubygems'] if defined? Gem\nend\n\n# Bring in Rocco tasks\nrequire 'rocco/tasks'\nRocco::make 'docs/'\n\ndesc 'Build rocco docs'\ntask :docs => :rocco\ndirectory 'docs/'\n\ndesc 'Build docs and open in browser for the reading'\ntask :read => :docs do\n sh 'open docs/lib/rocco.html'\nend\n\n# Make index.html a copy of rocco.html\nfile 'docs/index.html' => 'docs/lib/rocco.html' do |f|\n cp 'docs/lib/rocco.html', 'docs/index.html', :preserve => true\nend\ntask :docs => 'docs/index.html'\nCLEAN.include 'docs/index.html'\n\n# Alias for docs task\ntask :doc => :docs\n\n# GITHUB PAGES ===============================================================\n\ndesc 'Update gh-pages branch'\ntask :pages => ['docs/.git', :docs] do\n rev = `git rev-parse --short HEAD`.strip\n Dir.chdir 'docs' do\n sh \"git add *.html\"\n sh \"git commit -m 'rebuild pages from #{rev}'\" do |ok,res|\n if ok\n verbose { puts \"gh-pages updated\" }\n sh \"git push -q o HEAD:gh-pages\"\n end\n end\n end\nend\n\n# Update the pages/ directory clone\nfile 'docs/.git' => ['docs/', '.git/refs/heads/gh-pages'] do |f|\n sh \"cd docs && git init -q && git remote add o ../.git\" if !File.exist?(f.name)\n sh \"cd docs && git fetch -q o && git reset -q --hard o/gh-pages && touch .\"\nend\nCLOBBER.include 'docs/.git'\n\n# PACKAGING =================================================================\n\nif defined?(Gem)\n SPEC = eval(File.read('rocco.gemspec'))\n\n def package(ext='')\n \"pkg/rocco-#{SPEC.version}\" + ext\n end\n\n desc 'Build packages'\n task :package => %w[.gem .tar.gz].map {|e| package(e)}\n\n desc 'Build and install as local gem'\n task :install => package('.gem') do\n sh \"gem install #{package('.gem')}\"\n end\n\n directory 'pkg/'\n\n file package('.gem') => %w[pkg/ rocco.gemspec] + SPEC.files do |f|\n sh \"gem build rocco.gemspec\"\n mv File.basename(f.name), f.name\n end\n\n file package('.tar.gz') => %w[pkg/] + SPEC.files do |f|\n sh \"git archive --format=tar HEAD | gzip > #{f.name}\"\n end\nend\n\n# GEMSPEC ===================================================================\n\nfile 'rocco.gemspec' => FileList['{lib,test,bin}/**','Rakefile'] do |f|\n version = File.read('lib/rocco.rb')[/VERSION = '(.*)'/] && $1\n date = Time.now.strftime(\"%Y-%m-%d\")\n spec = File.\n read(f.name).\n sub(/s\\.version\\s*=\\s*'.*'/, \"s.version = '#{version}'\")\n parts = spec.split(\" # = MANIFEST =\\n\")\n files = `git ls-files`.\n split(\"\\n\").sort.reject{ |file| file =~ /^\\./ }.\n map{ |file| \" #{file}\" }.join(\"\\n\")\n parts[1] = \" s.files = %w[\\n#{files}\\n ]\\n\"\n spec = parts.join(\" # = MANIFEST =\\n\")\n spec.sub!(/s.date = '.*'/, \"s.date = '#{date}'\")\n File.open(f.name, 'w') { |io| io.write(spec) }\n puts \"#{f.name} #{version} (#{date})\"\nend\n" }, { "path": "bin/rocco", "content": "#!/usr/bin/env ruby\n#/ Usage: rocco [-l ] [-c ] [-o ] ...\n#/ Generate literate-programming-style documentation for Ruby source s.\n#/\n#/ Options:\n#/ -l, --language= The Pygments lexer to use to highlight code\n#/ -c, --comment-chars=\n#/ The string to recognize as a comment marker\n#/ -o, --output= Directory where generated HTML files are written\n#/ -t, --template= The file to use as template when rendering HTML\n#/ -d, --docblocks Parse Docblock @annotations in comments\n#/ --help Show this help message\n\nrequire 'optparse'\nrequire 'fileutils'\nrequire 'rocco'\n\n# Write usage message to stdout and exit.\ndef usage(stream=$stderr, status=1)\n stream.puts File.readlines(__FILE__).\n grep(/^#\\//).\n map { |line| line.sub(/^#. ?/, '') }.\n join\n exit status\nend\n\n# Like `Kernel#abort` but writes a note encouraging the user to consult\n# `rocco --help` for more information.\ndef abort_with_note(message=nil)\n $stderr.puts message if message\n abort \"See `rocco --help' for usage information.\"\nend\n\n# Parse command line options, aborting if anything goes wrong.\noutput_dir = '.'\nsources = []\noptions = {}\nARGV.options { |o|\n o.program_name = File.basename($0)\n o.on(\"-o\", \"--output=DIR\") { |dir| output_dir = dir }\n o.on(\"-l\", \"--language=LANG\") { |lang| options[:language] = lang }\n o.on(\"-c\", \"--comment-chars=CHARS\") { |chars| options[:comment_chars] = Regexp.escape(chars) }\n o.on(\"-t\", \"--template=TEMPLATE\") { |template| options[:template_file] = template }\n o.on(\"-d\", \"--docblocks\") { options[:docblocks] = true }\n o.on(\"-s\", \"--stylesheet=STYLESHEET\") { |stylesheet| options[:stylesheet] = stylesheet }\n o.on_tail(\"-h\", \"--help\") { usage($stdout, 0) }\n o.parse!\n} or abort_with_note\n\n# Use http://pygments.appspot.com in case `pygmentize(1)` isn't available.\nunless ENV['PATH'].split(':').any? { |dir| File.exist?(\"#{dir}/pygmentize\") }\n unless options[:webservice]\n $stderr.puts \"pygmentize not in PATH; using pygments.appspot.com instead\"\n options[:webservice] = true\n end\nend\n\n# Eat sources from ARGV.\nsources << ARGV.shift while ARGV.any?\n\n# Make sure we have some files to work with.\nif sources.empty?\n abort_with_note \"#{File.basename($0)}: no input s given\"\nend\n\n# Run each file through Rocco and write output.\nsources.each do |filename|\n rocco = Rocco.new(filename, sources, options)\n dest = filename.sub(Regexp.new(\"#{File.extname(filename)}$\"),\".html\")\n dest = File.join(output_dir, dest) if output_dir != '.'\n puts \"rocco: #{filename} -> #{dest}\"\n FileUtils.mkdir_p File.dirname(dest)\n File.open(dest, 'wb') { |fd| fd.write(rocco.to_html) }\nend\n" }, { "path": "lib/rocco/comment_styles.rb", "content": "class Rocco\n module CommentStyles\n C_STYLE_COMMENTS = {\n :single => \"//\",\n :multi => { :start => \"/**\", :middle => \"*\", :end => \"*/\" },\n :heredoc => nil\n }\n\n COMMENT_STYLES = {\n \"bash\" => { :single => \"#\", :multi => nil },\n \"c\" => C_STYLE_COMMENTS,\n \"coffee-script\" => {\n :single => \"#\",\n :multi => { :start => \"###\", :middle => nil, :end => \"###\" },\n :heredoc => nil\n },\n \"cpp\" => C_STYLE_COMMENTS,\n \"csharp\" => C_STYLE_COMMENTS,\n \"css\" => {\n :single => nil,\n :multi => { :start => \"/**\", :middle => \"*\", :end => \"*/\" },\n :heredoc => nil\n },\n \"html\" => {\n :single => nil,\n :multi => { :start => '' },\n :heredoc => nil\n },\n \"java\" => C_STYLE_COMMENTS,\n \"js\" => C_STYLE_COMMENTS,\n \"lua\" => {\n :single => \"--\",\n :multi => nil,\n :heredoc => nil\n },\n \"php\" => C_STYLE_COMMENTS,\n \"python\" => {\n :single => \"#\",\n :multi => { :start => '\"\"\"', :middle => nil, :end => '\"\"\"' },\n :heredoc => nil\n },\n \"rb\" => {\n :single => \"#\",\n :multi => { :start => '=begin', :middle => nil, :end => '=end' },\n :heredoc => \"<<-\"\n },\n \"scala\" => C_STYLE_COMMENTS,\n \"scheme\" => { :single => \";;\", :multi => nil, :heredoc => nil },\n \"xml\" => {\n :single => nil,\n :multi => { :start => '' },\n :heredoc => nil\n },\n }\n end\nend\n" }, { "path": "lib/rocco/layout.mustache", "content": "\n\n\n \n {{ title }}\n \n\n\n
\n
\n {{#sources?}}\n
\n Jump To …\n
\n
\n {{#sources}}\n {{ basename }}\n {{/sources}}\n
\n
\n
\n {{/sources?}}\n \n \n \n \n \n \n \n \n {{#sections}}\n \n \n \n \n {{/sections}}\n

{{ title }}

\n
\n \n
\n {{{ docs }}}\n 		\n 
{{{ code }}}
\n
\n
\n\n" }, { "path": "lib/rocco/layout.rb", "content": "require 'mustache'\nrequire 'pathname'\n\nclass Rocco::Layout < Mustache\n self.template_path = \"#{File.dirname(__FILE__)}/..\"\n\n def initialize(doc, stylesheet, file=nil)\n @doc = doc\n @stylesheet = stylesheet\n if not file.nil?\n Rocco::Layout.template_file = file\n end\n end\n\n def title\n File.basename(@doc.file)\n end\n\n def stylesheet\n @stylesheet\n end\n\n def file\n @doc.file\n end\n\n def sections\n num = 0\n @doc.sections.map do |docs,code|\n code ||= ''\n is_header = /^(.+)<\\/h.>$/.match( docs )\n header_text = is_header && is_header[1].split.join(\"_\")\n num += 1\n {\n :docs => docs,\n :docs? => !docs.empty?,\n :header? => is_header,\n\n :code => code,\n :code? => !code.empty?,\n\n :empty? => ( code.empty? && docs.empty? ),\n :section_id => is_header ? header_text : num\n }\n end\n end\n\n def sources?\n @doc.sources.length > 1\n end\n\n def sources\n currentpath = Pathname.new( File.dirname( @doc.file ) )\n @doc.sources.sort.map do |source|\n htmlpath = Pathname.new( source.sub( Regexp.new( \"#{File.extname(source)}$\"), \".html\" ) )\n\n {\n :path => source,\n :basename => File.basename(source),\n :url => htmlpath.relative_path_from( currentpath )\n }\n end\n end\nend\n" }, { "path": "lib/rocco/tasks.rb", "content": "#### Rocco Rake Tasks\n#\n# To use the Rocco Rake tasks, require `rocco/tasks` in your `Rakefile`\n# and define a Rake task with `rocco_task`. In its simplest form, `rocco_task`\n# takes the path to a destination directory where HTML docs should be built:\n#\n# require 'rocco/tasks'\n#\n# desc \"Build Rocco Docs\"\n# Rocco::make 'docs/'\n#\n# This creates a `:rocco` rake task, which can then be run with:\n#\n# rake rocco\n#\n# It's a good idea to guard against Rocco not being available, since your\n# Rakefile will fail to load otherwise. Consider doing something like this,\n# so that your Rakefile will still work\n#\n# begin\n# require 'rocco/tasks'\n# Rocco::make 'docs/'\n# rescue LoadError\n# warn \"#$! -- rocco tasks not loaded.\"\n# task :rocco\n# end\n#\n# It's also possible to pass a glob pattern:\n#\n# Rocco::make 'html/', 'lib/thing/**/*.rb'\n#\n# Or a list of glob patterns:\n#\n# Rocco::make 'html/', ['lib/thing.rb', 'lib/thing/*.rb']\n#\n# Finally, it is also possible to specify which Pygments language you would\n# like to use to highlight the code, as well as the comment characters for the\n# language in the `options` hash:\n#\n# Rocco::make 'html/', 'lib/thing/**/*.rb', {\n# :language => 'io',\n# :comment_chars => '#'\n# }\n#\n\n# Might be nice to defer this until we actually need to build docs but this\n# will have to do for now.\nrequire 'rocco'\n\n# Reopen the Rocco class and add a `make` class method. This is a simple bit\n# of sugar over `Rocco::Task.new`. If you want your Rake task to be named\n# something other than `:rocco`, you can use `Rocco::Task` directly.\nclass Rocco\n def self.make(dest='docs/', source_files='lib/**/*.rb', options={})\n Task.new(:rocco, dest, source_files, options)\n end\n\n # `Rocco::Task.new` takes a task name, the destination directory docs\n # should be built under, and a source file pattern or file list.\n class Task\n include Rake::DSL if defined?(Rake::DSL)\n\n def initialize(task_name, dest='docs/', sources='lib/**/*.rb', options={})\n @name = task_name\n @dest = dest[-1] == ?/ ? dest : \"#{dest}/\"\n @sources = FileList[sources]\n @options = options\n\n # Make sure there's a `directory` task defined for our destination.\n define_directory_task @dest\n\n # Run over the source file list, constructing destination filenames\n # and defining file tasks.\n @sources.each do |source_file|\n dest_file = source_file.sub(Regexp.new(\"#{File.extname(source_file)}$\"), \".html\")\n define_file_task source_file, \"#{@dest}#{dest_file}\"\n\n # If `rake/clean` was required, add the generated files to the list.\n # That way all Rocco generated are removed when running `rake clean`.\n CLEAN.include \"#{@dest}#{dest_file}\" if defined? CLEAN\n end\n end\n\n # Define the destination directory task and make the `:rocco` task depend\n # on it. This causes the destination directory to be created if it doesn't\n # already exist.\n def define_directory_task(path)\n directory path\n task @name => path\n end\n\n # Setup a `file` task for a single Rocco output file (`dest_file`). It\n # depends on the source file, the destination directory, and all of Rocco's\n # internal source code, so that the destination file is rebuilt when any of\n # those changes.\n #\n # You can run these tasks directly with Rake:\n #\n # rake docs/foo.html docs/bar.html\n #\n # ... would generate the `foo.html` and `bar.html` files but only if they\n # don't already exist or one of their dependencies was changed.\n def define_file_task(source_file, dest_file)\n prerequisites = [@dest, source_file] + rocco_source_files\n file dest_file => prerequisites do |f|\n verbose { puts \"rocco: #{source_file} -> #{dest_file}\" }\n rocco = Rocco.new(source_file, @sources.to_a, @options)\n FileUtils.mkdir_p(File.dirname(dest_file))\n File.open(dest_file, 'wb') { |fd| fd.write(rocco.to_html) }\n end\n task @name => dest_file\n end\n\n # Return a `FileList` that includes all of Roccos source files. This causes\n # output files to be regenerated properly when someone upgrades the Rocco\n # library.\n def rocco_source_files\n libdir = File.expand_path('../..', __FILE__)\n FileList[\"#{libdir}/rocco.rb\", \"#{libdir}/rocco/**\"]\n end\n\n end\nend\n" }, { "path": "lib/rocco.rb", "content": "# **Rocco** is a Ruby port of [Docco][do], the quick-and-dirty,\n# hundred-line-long, literate-programming-style documentation generator.\n#\n# Rocco reads Ruby source files and produces annotated source documentation\n# in HTML format. Comments are formatted with [Markdown][md] and presented\n# alongside syntax highlighted code so as to give an annotation effect.\n# This page is the result of running Rocco against [its own source file][so].\n#\n# Most of this was written while waiting for [node.js][no] to build (so I\n# could use Docco!). Docco's gorgeous HTML and CSS are taken verbatim.\n# The main difference is that Rocco is written in Ruby instead of\n# [CoffeeScript][co] and may be a bit easier to obtain and install in\n# existing Ruby environments or where node doesn't run yet.\n#\n# Install Rocco with Rubygems:\n#\n# gem install rocco\n#\n# Once installed, the `rocco` command can be used to generate documentation\n# for a set of Ruby source files:\n#\n# rocco lib/*.rb\n#\n# The HTML files are written to the current working directory.\n#\n# [no]: http://nodejs.org/\n# [do]: http://jashkenas.github.com/docco/\n# [co]: http://coffeescript.org/\n# [md]: http://daringfireball.net/projects/markdown/\n# [so]: http://github.com/rtomayko/rocco/blob/master/lib/rocco.rb#commit\n\n#### Prerequisites\n\n# We'll need a Markdown library. Try to load one if not already established.\nunless defined?(Markdown)\n markdown_libraries = %w[redcarpet rdiscount bluecloth]\n begin\n require markdown_libraries.shift\n rescue LoadError => boom\n retry if markdown_libraries.any?\n raise\n end\nend\n\n# We use [{{ mustache }}](http://defunkt.github.com/mustache/) for\n# HTML templating.\nrequire 'mustache'\n\n# We use `Net::HTTP` to highlight code via \nrequire 'net/http'\n\n# Code is run through [Pygments](http://pygments.org/) for syntax\n# highlighting. If it's not installed, locally, use a webservice.\nunless ENV['PATH'].split(':').any? { |dir| File.executable?(\"#{dir}/pygmentize\") }\n warn \"WARNING: Pygments not found. Using webservice.\"\nend\n\n#### Public Interface\n\n# `Rocco.new` takes a source `filename`, an optional list of source filenames\n# for other documentation sources, an `options` hash, and an optional `block`.\n# The `options` hash respects three members:\n#\n# * `:language`: specifies which Pygments lexer to use if one can't be\n# auto-detected from the filename. _Defaults to `ruby`_.\n#\n# * `:comment_chars`, which specifies the comment characters of the\n# target language. _Defaults to `#`_.\n#\n# * `:template_file`, which specifies a external template file to use\n# when rendering the final, highlighted file via Mustache. _Defaults\n# to `nil` (that is, Mustache will use `./lib/rocco/layout.mustache`)_.\n#\n# * `:stylesheet`, which specifies the css stylesheet to use for each\n# rendered template. _Defaults to `http://jashkenas.github.com/docco/resources/docco.css`\n# (the original docco stylesheet)\nclass Rocco\n VERSION = '0.8.2'\n\n def initialize(filename, sources=[], options={})\n @file = filename\n @sources = sources\n\n # When `block` is given, it must read the contents of the file using\n # whatever means necessary and return it as a string. With no `block`,\n # the file is read to retrieve data.\n @data = if block_given? then yield else File.read(filename) end\n\n @options = {\n :language => 'ruby',\n :comment_chars => '#',\n :template_file => nil,\n :stylesheet => 'http://jashkenas.github.io/docco/resources/linear/docco.css'\n }.merge(options)\n\n # If we detect a language\n if \"text\" != detect_language\n # then assign the detected language to `:language`, and look for\n # comment characters based on that language\n @options[:language] = detect_language\n @options[:comment_chars] = generate_comment_chars\n\n # If we didn't detect a language, but the user provided one, use it\n # to look around for comment characters to override the default.\n elsif @options[:language]\n @options[:comment_chars] = generate_comment_chars\n\n # If neither is true, then convert the default comment character string\n # into the comment_char syntax (we'll discuss that syntax in detail when\n # we get to `generate_comment_chars()` in a moment.\n else\n @options[:comment_chars] = { :single => @options[:comment_chars], :multi => nil }\n end\n\n # Turn `:comment_chars` into a regex matching a series of spaces, the\n # `:comment_chars` string, and the an optional space. We'll use that\n # to detect single-line comments.\n @comment_pattern = Regexp.new(\"^\\\\s*#{@options[:comment_chars][:single]}\\s?\")\n\n # `parse()` the file contents stored in `@data`. Run the result through\n # `split()` and that result through `highlight()` to generate the final\n # section list.\n @sections = highlight(split(parse(@data)))\n end\n\n # The filename as given to `Rocco.new`.\n attr_reader :file\n\n # The merged options array\n attr_reader :options\n\n # A list of two-tuples representing each *section* of the source file. Each\n # item in the list has the form: `[docs_html, code_html]`, where both\n # elements are strings containing the documentation and source code HTML,\n # respectively.\n attr_reader :sections\n\n # A list of all source filenames included in the documentation set. Useful\n # for building an index of other files.\n attr_reader :sources\n\n # Generate HTML output for the entire document.\n require 'rocco/layout'\n def to_html\n Rocco::Layout.new(self, @options[:stylesheet], @options[:template_file]).render\n end\n\n # Helper Functions\n # ----------------\n\n # Returns `true` if `pygmentize` is available locally, `false` otherwise.\n def pygmentize?\n @_pygmentize ||= ENV['PATH'].split(':').\n any? { |dir| File.executable?(\"#{dir}/pygmentize\") }\n end\n\n # If `pygmentize` is available, we can use it to autodetect a file's\n # language based on its filename. Filenames without extensions, or with\n # extensions that `pygmentize` doesn't understand will return `text`.\n # We'll also return `text` if `pygmentize` isn't available.\n #\n # We'll memoize the result, as we'll call this a few times.\n def detect_language\n @_language ||=\n if pygmentize?\n %x[pygmentize -N #{@file}].strip.split('+').first\n else\n \"text\"\n end\n end\n\n # Given a file's language, we should be able to autopopulate the\n # `comment_chars` variables for single-line comments. If we don't\n # have comment characters on record for a given language, we'll\n # use the user-provided `:comment_char` option (which defaults to\n # `#`).\n #\n # Comment characters are listed as:\n #\n # { :single => \"//\",\n # :multi_start => \"/**\",\n # :multi_middle => \"*\",\n # :multi_end => \"*/\" }\n #\n # `:single` denotes the leading character of a single-line comment.\n # `:multi_start` denotes the string that should appear alone on a\n # line of code to begin a block of documentation. `:multi_middle`\n # denotes the leading character of block comment content, and\n # `:multi_end` is the string that ought appear alone on a line to\n # close a block of documentation. That is:\n #\n # /** [:multi][:start]\n # * [:multi][:middle]\n # ...\n # * [:multi][:middle]\n # */ [:multi][:end]\n #\n # If a language only has one type of comment, the missing type\n # should be assigned `nil`.\n #\n # At the moment, we're only returning `:single`. Consider this\n # groundwork for block comment parsing.\n require 'rocco/comment_styles'\n include CommentStyles\n\n def generate_comment_chars\n @_commentchar ||=\n if COMMENT_STYLES[@options[:language]]\n COMMENT_STYLES[@options[:language]]\n else\n { :single => @options[:comment_chars], :multi => nil, :heredoc => nil }\n end\n end\n\n # Internal Parsing and Highlighting\n # ---------------------------------\n\n # Parse the raw file data into a list of two-tuples. Each tuple has the\n # form `[docs, code]` where both elements are arrays containing the\n # raw lines parsed from the input file, comment characters stripped.\n def parse(data)\n sections, docs, code = [], [], []\n lines = data.split(\"\\n\")\n\n # The first line is ignored if it is a shebang line. We also ignore the\n # PEP 263 encoding information in python sourcefiles, and the similar ruby\n # 1.9 syntax.\n lines.shift if lines[0] =~ /^\\#\\!/\n lines.shift if lines[0] =~ /coding[:=]\\s*[-\\w.]+/ &&\n [ \"python\", \"rb\" ].include?(@options[:language])\n\n # To detect both block comments and single-line comments, we'll set\n # up a tiny state machine, and loop through each line of the file.\n # This requires an `in_comment_block` boolean, and a few regular\n # expressions for line tests. We'll do the same for fake heredoc parsing.\n in_comment_block = false\n in_heredoc = false\n single_line_comment, block_comment_start, block_comment_mid, block_comment_end =\n nil, nil, nil, nil\n if not @options[:comment_chars][:single].nil?\n single_line_comment = Regexp.new(\"^\\\\s*#{Regexp.escape(@options[:comment_chars][:single])}\\\\s?\")\n end\n if not @options[:comment_chars][:multi].nil?\n block_comment_start = Regexp.new(\"^\\\\s*#{Regexp.escape(@options[:comment_chars][:multi][:start])}\\\\s*$\")\n block_comment_end = Regexp.new(\"^\\\\s*#{Regexp.escape(@options[:comment_chars][:multi][:end])}\\\\s*$\")\n block_comment_one_liner = Regexp.new(\"^\\\\s*#{Regexp.escape(@options[:comment_chars][:multi][:start])}\\\\s*(.*?)\\\\s*#{Regexp.escape(@options[:comment_chars][:multi][:end])}\\\\s*$\")\n block_comment_start_with = Regexp.new(\"^\\\\s*#{Regexp.escape(@options[:comment_chars][:multi][:start])}\\\\s*(.*?)$\")\n block_comment_end_with = Regexp.new(\"\\\\s*(.*?)\\\\s*#{Regexp.escape(@options[:comment_chars][:multi][:end])}\\\\s*$\")\n if @options[:comment_chars][:multi][:middle]\n block_comment_mid = Regexp.new(\"^\\\\s*#{Regexp.escape(@options[:comment_chars][:multi][:middle])}\\\\s?\")\n end\n end\n if not @options[:comment_chars][:heredoc].nil?\n heredoc_start = Regexp.new(\"#{Regexp.escape(@options[:comment_chars][:heredoc])}(\\\\S+)$\")\n end\n lines.each do |line|\n # If we're currently in a comment block, check whether the line matches\n # the _end_ of a comment block or the _end_ of a comment block with a\n # comment.\n if in_comment_block\n if block_comment_end && line.match(block_comment_end)\n in_comment_block = false\n elsif block_comment_end_with && line.match(block_comment_end_with)\n in_comment_block = false\n docs << line.match(block_comment_end_with).captures.first.\n sub(block_comment_mid || '', '')\n else\n docs << line.sub(block_comment_mid || '', '')\n end\n # If we're currently in a heredoc, we're looking for the end of the\n # heredoc, and everything it contains is code.\n elsif in_heredoc\n if line.match(Regexp.new(\"^#{Regexp.escape(in_heredoc)}$\"))\n in_heredoc = false\n end\n code << line\n # Otherwise, check whether the line starts a heredoc. If so, note the end\n # pattern, and the line is code. Otherwise check whether the line matches\n # the beginning of a block, or a single-line comment all on it's lonesome.\n # In either case, if there's code, start a new section.\n else\n if heredoc_start && line.match(heredoc_start)\n in_heredoc = $1\n code << line\n elsif block_comment_one_liner && line.match(block_comment_one_liner)\n if code.any?\n sections << [docs, code]\n docs, code = [], []\n end\n docs << line.match(block_comment_one_liner).captures.first\n elsif block_comment_start && line.match(block_comment_start)\n in_comment_block = true\n if code.any?\n sections << [docs, code]\n docs, code = [], []\n end\n elsif block_comment_start_with && line.match(block_comment_start_with)\n in_comment_block = true\n if code.any?\n sections << [docs, code]\n docs, code = [], []\n end\n docs << line.match(block_comment_start_with).captures.first\n elsif single_line_comment && line.match(single_line_comment)\n if code.any?\n sections << [docs, code]\n docs, code = [], []\n end\n docs << line.sub(single_line_comment || '', '')\n else\n code << line\n end\n end\n end\n sections << [docs, code] if docs.any? || code.any?\n normalize_leading_spaces(sections)\n end\n\n # Normalizes documentation whitespace by checking for leading whitespace,\n # removing it, and then removing the same amount of whitespace from each\n # succeeding line. That is:\n #\n # def func():\n # \"\"\"\n # Comment 1\n # Comment 2\n # \"\"\"\n # print \"omg!\"\n #\n # should yield a comment block of `Comment 1\\nComment 2` and code of\n # `def func():\\n print \"omg!\"`\n def normalize_leading_spaces(sections)\n sections.map do |section|\n if section.any? && section[0].any?\n leading_space = section[0][0].match(\"^\\s+\")\n if leading_space\n section[0] =\n section[0].map{ |line| line.sub(/^#{leading_space.to_s}/, '') }\n end\n end\n section\n end\n end\n\n # Take the list of paired *sections* two-tuples and split into two\n # separate lists: one holding the comments with leaders removed and\n # one with the code blocks.\n def split(sections)\n docs_blocks, code_blocks = [], []\n sections.each do |docs,code|\n docs_blocks << docs.join(\"\\n\")\n code_blocks << code.map do |line|\n tabs = line.match(/^(\\t+)/)\n tabs ? line.sub(/^\\t+/, ' ' * tabs.captures[0].length) : line\n end.join(\"\\n\")\n end\n [docs_blocks, code_blocks]\n end\n\n # Take a list of block comments and convert Docblock @annotations to\n # Markdown syntax.\n def docblock(docs)\n docs.map do |doc|\n doc.split(\"\\n\").map do |line|\n line.match(/^@\\w+/) ? line.sub(/^@(\\w+)\\s+/, '> **\\1** ')+\" \" : line\n end.join(\"\\n\")\n end\n end\n\n # Take the result of `split` and apply Markdown formatting to comments and\n # syntax highlighting to source code.\n def highlight(blocks)\n docs_blocks, code_blocks = blocks\n\n # Pre-process Docblock @annotations.\n docs_blocks = docblock(docs_blocks) if @options[:docblocks]\n\n # Combine all docs blocks into a single big markdown document with section\n # dividers and run through the Markdown processor. Then split it back out\n # into separate sections.\n markdown = docs_blocks.join(\"\\n\\n##### DIVIDER\\n\\n\")\n docs_html = process_markdown(markdown).split(/\\n*
DIVIDER<\\/h5>\\n*/m)\n\n # Combine all code blocks into a single big stream with section dividers and\n # run through either `pygmentize(1)` or \n span, espan = '', ''\n if @options[:comment_chars][:single]\n front = @options[:comment_chars][:single]\n divider_input = \"\\n\\n#{front} DIVIDER\\n\\n\"\n divider_output = Regexp.new(\n [ \"\\\\n*\",\n span,\n Regexp.escape(CGI.escapeHTML(front)),\n ' DIVIDER',\n espan,\n \"\\\\n*\"\n ].join, Regexp::MULTILINE\n )\n else\n front = @options[:comment_chars][:multi][:start]\n back = @options[:comment_chars][:multi][:end]\n divider_input = \"\\n\\n#{front}\\nDIVIDER\\n#{back}\\n\\n\"\n divider_output = Regexp.new(\n [ \"\\\\n*\",\n span, Regexp.escape(CGI.escapeHTML(front)), espan,\n \"\\\\n\",\n span, \"DIVIDER\", espan,\n \"\\\\n\",\n span, Regexp.escape(CGI.escapeHTML(back)), espan,\n \"\\\\n*\"\n ].join, Regexp::MULTILINE\n )\n end\n\n code_stream = code_blocks.join(divider_input)\n\n code_html =\n if pygmentize?\n highlight_pygmentize(code_stream)\n else\n highlight_webservice(code_stream)\n end\n\n # Do some post-processing on the pygments output to split things back\n # into sections and remove partial `
` blocks.\n    code_html = code_html.\n      split(divider_output).\n      map { |code| code.sub(/\\n?
/m, '') }.\n      map { |code| code.sub(/\\n?<\\/pre><\\/div>\\n/m, '') }\n\n    # Lastly, combine the docs and code lists back into a list of two-tuples.\n    docs_html.zip(code_html)\n  end\n\n  # Convert Markdown to classy HTML.\n  def process_markdown(text)\n    Markdown.new(text, :smart).to_html\n  end\n\n  # We `popen` a read/write pygmentize process in the parent and\n  # then fork off a child process to write the input.\n  def highlight_pygmentize(code)\n    code_html = nil\n    open(\"|pygmentize -l #{@options[:language]} -O encoding=utf-8 -f html\", 'r+') do |fd|\n      pid =\n        fork {\n          fd.close_read\n          fd.write code\n          fd.close_write\n          exit!\n        }\n      fd.close_write\n      code_html = fd.read\n      fd.close_read\n      Process.wait(pid)\n    end\n\n    code_html\n  end\n\n  # Pygments is not one of those things that's trivial for a ruby user to install,\n  # so we'll fall back on a webservice to highlight the code if it isn't available.\n  def highlight_webservice(code)\n    url = URI.parse 'http://pygments.appspot.com/'\n    options = { 'lang' => @options[:language], 'code' => code}\n    Net::HTTP.post_form(url, options).body\n  end\nend\n\n# And that's it.\n"
  },
  {
    "path": "rocco.gemspec",
    "content": "# rocco.gemspec\n#\n# To update this file's version, date, and file list, change the VERSION\n# constant in lib/rocco.rb and run `rake rocco.gemspec`.\n\nGem::Specification.new do |s|\n  s.specification_version = 2 if s.respond_to? :specification_version=\n  s.required_rubygems_version = Gem::Requirement.new(\">= 0\") if s.respond_to? :required_rubygems_version=\n\n  s.name = 'rocco'\n  s.version = '0.8.2'\n  s.date = '2011-08-27'\n\n  s.description = \"Docco in Ruby\"\n  s.summary     = s.description\n\n  s.authors = [\"Ryan Tomayko\", \"Mike West\"]\n  s.email   = [\"r@tomayko.com\", \"\"]\n\n  s.licenses = ['MIT']\n\n  # = MANIFEST =\n  s.files = %w[\n    CHANGES.md\n    COPYING\n    README\n    Rakefile\n    bin/rocco\n    lib/rocco.rb\n    lib/rocco/comment_styles.rb\n    lib/rocco/layout.mustache\n    lib/rocco/layout.rb\n    lib/rocco/tasks.rb\n    rocco.gemspec\n    test/fixtures/issue10.iso-8859-1.rb\n    test/fixtures/issue10.utf-8.rb\n    test/helper.rb\n    test/suite.rb\n    test/test_basics.rb\n    test/test_block_comment_styles.rb\n    test/test_block_comments.rb\n    test/test_comment_normalization.rb\n    test/test_commentchar_detection.rb\n    test/test_descriptive_section_names.rb\n    test/test_docblock_annotations.rb\n    test/test_heredoc.rb\n    test/test_language_detection.rb\n    test/test_reported_issues.rb\n    test/test_skippable_lines.rb\n    test/test_source_list.rb\n  ]\n  # = MANIFEST =\n\n  s.executables = [\"rocco\"]\n\n  s.test_files = s.files.select {|path| path =~ /^test\\/.*_test.rb/}\n  s.add_dependency 'redcarpet', '~> 1.17'\n  s.add_dependency 'mustache'\n\n  s.has_rdoc = false\n  s.homepage = \"http://rtomayko.github.com/rocco/\"\n  s.require_paths = %w[lib]\n  s.rubygems_version = '1.1.1'\nend\n"
  },
  {
    "path": "test/fixtures/issue10.iso-8859-1.rb",
    "content": "# hello wrld\n"
  },
  {
    "path": "test/fixtures/issue10.utf-8.rb",
    "content": "# hello ąćęłńóśźż\n"
  },
  {
    "path": "test/helper.rb",
    "content": "rootdir = File.expand_path('../../lib', __FILE__)\n$LOAD_PATH.unshift \"#{rootdir}/lib\"\n\nrequire 'test/unit'\nbegin; require 'turn'; rescue LoadError; end\nbegin\n  require 'rdiscount'\nrescue LoadError\n  if !defined?(Gem)\n    require 'rubygems'\n    retry\n  end\nend\nrequire 'rocco'\n\ndef roccoize( filename, contents, options = {} )\n  Rocco.new( filename, [ filename ], options ) {\n    contents\n  }\nend\n"
  },
  {
    "path": "test/suite.rb",
    "content": "require File.expand_path('../helper', __FILE__)\nrequire 'test/unit'\n\nDir[File.expand_path('../test_*.rb', __FILE__)].\neach { |file| require file }\n"
  },
  {
    "path": "test/test_basics.rb",
    "content": "require File.expand_path('../helper', __FILE__)\n\nclass RoccoBasicTests < Test::Unit::TestCase\n  def test_rocco_exists_and_is_instancable\n    roccoize( \"filename.rb\", \"# Comment 1\\ndef codeblock\\nend\\n\" )\n  end\n\n  def test_filename\n    r = roccoize( \"filename.rb\", \"# Comment 1\\ndef codeblock\\nend\\n\" )\n    assert_equal \"filename.rb\", r.file\n  end\n\n  def test_sources\n    r = roccoize( \"filename.rb\", \"# Comment 1\\ndef codeblock\\nend\\n\" )\n    assert_equal [ \"filename.rb\" ], r.sources\n  end\n\n  def test_sections\n    r = roccoize( \"filename.rb\", \"# Comment 1\\ndef codeblock\\nend\\n\" )\n    assert_equal 1, r.sections.length\n    assert_equal 2, r.sections[ 0 ].length\n    assert_equal \"
Comment 1
\\n\", r.sections[ 0 ][ 0 ]\n    assert_equal \"def codeblock\\nend\", r.sections[ 0 ][ 1 ]\n  end\n\n  def test_parsing\n    r = Rocco.new( 'test' ) { \"\" } # Generate throwaway instance so I can test `parse`\n    assert_equal(\n      [\n        [ [ \"Comment 1\" ], [ \"def codeblock\", \"end\" ] ]\n      ],\n      r.parse( \"# Comment 1\\ndef codeblock\\nend\\n\" )\n    )\n    assert_equal(\n      [\n        [ [ \"Comment 1\" ], [ \"def codeblock\" ] ],\n        [ [ \"Comment 2\" ], [ \"end\" ] ]\n      ],\n      r.parse( \"# Comment 1\\ndef codeblock\\n# Comment 2\\nend\\n\" )\n    )\n  end\n\n  def test_splitting\n    r = Rocco.new( 'test' ) { \"\" } # Generate throwaway instance so I can test `split`\n    assert_equal(\n      [\n        [ \"Comment 1\" ],\n        [ \"def codeblock\\nend\" ]\n      ],\n      r.split([ [ [ \"Comment 1\" ], [ \"def codeblock\", \"end\" ] ] ])\n    )\n    assert_equal(\n      [\n        [ \"Comment 1\", \"Comment 2\" ],\n        [ \"def codeblock\", \"end\" ]\n      ],\n      r.split( [\n        [ [ \"Comment 1\" ], [ \"def codeblock\" ] ],\n        [ [ \"Comment 2\" ], [ \"end\" ] ]\n      ] )\n    )\n  end\nend\n"
  },
  {
    "path": "test/test_block_comment_styles.rb",
    "content": "require File.expand_path('../helper', __FILE__)\n\nclass RoccoBlockCommentTest < Test::Unit::TestCase\n  def test_one_liner\n    r = Rocco.new( 'test', '', { :language => \"c\" } ) { \"\" } # Generate throwaway instance so I can test `parse`\n    assert_equal(\n      [\n        [ [ \"Comment 1\" ], [ \"def codeblock\", \"end\" ] ]\n      ],\n      r.parse( \"/** Comment 1 */\\ndef codeblock\\nend\\n\" )\n    )\n  end\n\n  def test_block_start_with_comment\n    r = Rocco.new( 'test', '', { :language => \"c\" } ) { \"\" } # Generate throwaway instance so I can test `parse`\n    assert_equal(\n      [\n        [ [ \"Comment 1a\", \"Comment 1b\" ], [ \"def codeblock\", \"end\" ] ]\n      ],\n      r.parse( \"/** Comment 1a\\n * Comment 1b\\n */\\ndef codeblock\\nend\\n\" )\n    )\n  end\n\n  def test_block_end_with_comment\n    r = Rocco.new( 'test', '', { :language => \"c\" } ) { \"\" } # Generate throwaway instance so I can test `parse`\n    assert_equal(\n      [\n        [ [ \"Comment 1a\", \"Comment 1b\" ], [ \"def codeblock\", \"end\" ] ]\n      ],\n      r.parse( \"/**\\n * Comment 1a\\n Comment 1b */\\ndef codeblock\\nend\\n\" )\n    )\n  end\n\n  def test_block_end_with_comment_and_middle\n    r = Rocco.new( 'test', '', { :language => \"c\" } ) { \"\" } # Generate throwaway instance so I can test `parse`\n    assert_equal(\n      [\n        [ [ \"Comment 1a\", \"Comment 1b\" ], [ \"def codeblock\", \"end\" ] ]\n      ],\n      r.parse( \"/**\\n * Comment 1a\\n * Comment 1b */\\ndef codeblock\\nend\\n\" )\n    )\n  end\n\n  def test_block_start_with_comment_and_end_with_comment\n    r = Rocco.new( 'test', '', { :language => \"c\" } ) { \"\" } # Generate throwaway instance so I can test `parse`\n    assert_equal(\n      [\n        [ [ \"Comment 1a\", \"Comment 1b\" ], [ \"def codeblock\", \"end\" ] ]\n      ],\n      r.parse( \"/** Comment 1a\\n Comment 1b */\\ndef codeblock\\nend\\n\" )\n    )\n  end\n\n  def test_block_start_with_comment_and_end_with_comment_and_middle\n    r = Rocco.new( 'test', '', { :language => \"c\" } ) { \"\" } # Generate throwaway instance so I can test `parse`\n    assert_equal(\n      [\n        [ [ \"Comment 1a\", \"Comment 1b\" ], [ \"def codeblock\", \"end\" ] ]\n      ],\n      r.parse( \"/** Comment 1a\\n * Comment 1b */\\ndef codeblock\\nend\\n\" )\n    )\n  end\n\nend\n"
  },
  {
    "path": "test/test_block_comments.rb",
    "content": "require File.expand_path('../helper', __FILE__)\n\nclass RoccoBlockCommentTest < Test::Unit::TestCase\n  def test_basics\n    r = Rocco.new( 'test', '', { :language => \"c\" } ) { \"\" } # Generate throwaway instance so I can test `parse`\n    assert_equal(\n      [\n        [ [ \"Comment 1\" ], [ \"def codeblock\", \"end\" ] ]\n      ],\n      r.parse( \"/**\\n * Comment 1\\n */\\ndef codeblock\\nend\\n\" )\n    )\n    assert_equal(\n      [\n        [ [ \"Comment 1a\", \"Comment 1b\" ], [ \"def codeblock\", \"end\" ] ]\n      ],\n      r.parse( \"/**\\n * Comment 1a\\n * Comment 1b\\n */\\ndef codeblock\\nend\\n\" )\n    )\n  end\n\n  def test_multiple_blocks\n    r = Rocco.new( 'test', '', { :language => \"c\" } ) { \"\" } # Generate throwaway instance so I can test `parse`\n    assert_equal(\n      [\n        [ [ \"Comment 1\" ], [ \"def codeblock\", \"end\" ] ],\n        [ [ \"Comment 2\" ], [] ]\n      ],\n      r.parse( \"/**\\n * Comment 1\\n */\\ndef codeblock\\nend\\n/**\\n * Comment 2\\n */\\n\" )\n    )\n    assert_equal(\n      [\n        [ [ \"Comment 1\" ], [ \"def codeblock\", \"end\" ] ],\n        [ [ \"Comment 2\" ], [ \"if false\", \"end\" ] ]\n      ],\n      r.parse( \"/**\\n * Comment 1\\n */\\ndef codeblock\\nend\\n/**\\n * Comment 2\\n */\\nif false\\nend\" )\n    )\n  end\n\n  def test_block_without_middle_character\n    r = Rocco.new( 'test', '', { :language => \"python\" } ) { \"\" } # Generate throwaway instance so I can test `parse`\n    assert_equal(\n      [\n        [ [ \"Comment 1\" ], [ \"def codeblock\", \"end\" ] ],\n        [ [ \"Comment 2\" ], [] ]\n      ],\n      r.parse( \"\\\"\\\"\\\"\\n  Comment 1\\n\\\"\\\"\\\"\\ndef codeblock\\nend\\n\\\"\\\"\\\"\\n  Comment 2\\n\\\"\\\"\\\"\\n\" )\n    )\n    assert_equal(\n      [\n        [ [ \"Comment 1\" ], [ \"def codeblock\", \"end\" ] ],\n        [ [ \"Comment 2\" ], [ \"if false\", \"end\" ] ]\n      ],\n      r.parse( \"\\\"\\\"\\\"\\n  Comment 1\\n\\\"\\\"\\\"\\ndef codeblock\\nend\\n\\\"\\\"\\\"\\n  Comment 2\\n\\\"\\\"\\\"\\nif false\\nend\" )\n    )\n  end\n\n  def test_language_without_single_line_comments_parse\n    r = Rocco.new( 'test', '', { :language => \"css\" } ) { \"\" } # Generate throwaway instance so I can test `parse`\n    assert_equal(\n      [\n        [ [ \"Comment 1\" ], [ \"def codeblock\", \"end\" ] ],\n        [ [ \"Comment 2\" ], [ \"if false\", \"end\" ] ]\n      ],\n      r.parse( \"/**\\n * Comment 1\\n */\\ndef codeblock\\nend\\n/**\\n * Comment 2\\n */\\nif false\\nend\" )\n    )\n  end\n\n  def test_language_without_single_line_comments_split\n    r = Rocco.new( 'test', '', { :language => \"css\" } ) { \"\" } # Generate throwaway instance so I can test `parse`\n    assert_equal(\n      [\n        [ \"Comment 1\", \"Comment 2\" ],\n        [ \"def codeblock\\nend\", \"if false\\nend\" ]\n      ],\n      r.split( [\n        [ [ \"Comment 1\" ], [ \"def codeblock\", \"end\" ] ],\n        [ [ \"Comment 2\" ], [ \"if false\", \"end\" ] ]\n      ] )\n    )\n  end\n\n  def test_language_without_single_line_comments_highlight\n    r = Rocco.new( 'test', '', { :language => \"css\" } ) { \"\" } # Generate throwaway instance so I can test `parse`\n\n    highlighted = r.highlight( r.split( r.parse( \"/**\\n * This is a comment!\\n */\\n.rule { goes: here; }\\n/**\\n * Comment 2\\n */\\n.rule2 { goes: here; }\" ) ) )\n    assert_equal(\n      \"
This is a comment!
\",\n      highlighted[0][0]\n    )\n    assert_equal(\n      \"
Comment 2
\\n\",\n      highlighted[1][0]\n    )\n    assert(\n      !highlighted[0][1].include?(\"DIVIDER\") &&\n      !highlighted[1][1].include?(\"DIVIDER\"),\n      \"`DIVIDER` stripped successfully.\"\n    )\n    assert( true )\n  end\n\nend\n"
  },
  {
    "path": "test/test_comment_normalization.rb",
    "content": "require File.expand_path('../helper', __FILE__)\n\nclass RoccoCommentNormalization < Test::Unit::TestCase\n  def test_normal_comments\n    r = Rocco.new( 'test', '', { :language => \"python\" } ) { \"\" } # Generate throwaway instance so I can test `parse`\n    assert_equal(\n      [\n          [ [ \"Comment 1a\", \"Comment 1b\" ], [ \"def codeblock\", \"end\" ] ],\n          [ [ \"Comment 2a\", \"  Comment 2b\" ], [] ]\n      ],\n      r.parse( \"\\\"\\\"\\\"\\n  Comment 1a\\n  Comment 1b\\n\\\"\\\"\\\"\\ndef codeblock\\nend\\n\\\"\\\"\\\"\\n  Comment 2a\\n    Comment 2b\\n\\\"\\\"\\\"\\n\" )\n    )\n  end\n\n  def test_single_line_comments\n    r = Rocco.new( 'test', '', { :language => \"python\" } ) { \"\" } # Generate throwaway instance so I can test `parse`\n    assert_equal(\n      [\n          [ [ \"Comment 1a\", \"Comment 1b\" ], [ \"def codeblock\", \"end\" ] ],\n          [ [ \"Comment 2a\", \"  Comment 2b\" ], [] ]\n      ],\n      r.parse( \"#   Comment 1a\\n#   Comment 1b\\ndef codeblock\\nend\\n#   Comment 2a\\n#     Comment 2b\\n\" )\n    )\n  end\nend\n"
  },
  {
    "path": "test/test_commentchar_detection.rb",
    "content": "require File.expand_path('../helper', __FILE__)\n\nclass RoccoAutomaticCommentChars < Test::Unit::TestCase\n  def test_basic_detection\n    r = Rocco.new( 'filename.js' ) { \"\" }\n    assert_equal \"//\", r.options[:comment_chars][:single]\n  end\n\n  def test_fallback_language\n    r = Rocco.new( 'filename.an_extension_with_no_meaning_whatsoever', '', { :language => \"js\" } ) { \"\" }\n    assert_equal \"//\", r.options[:comment_chars][:single]\n  end\n\n  def test_fallback_default\n    r = Rocco.new( 'filename.an_extension_with_no_meaning_whatsoever' ) { \"\" }\n    assert_equal \"#\", r.options[:comment_chars][:single], \"`:comment_chars` should be `#` when falling back to defaults.\"\n  end\n\n  def test_fallback_user\n    r = Rocco.new( 'filename.an_extension_with_no_meaning_whatsoever', '', { :comment_chars => \"user\" } ) { \"\" }\n    assert_equal \"user\", r.options[:comment_chars][:single], \"`:comment_chars` should be the user's default when falling back to user-provided settings.\"\n  end\n\n  def test_fallback_user_with_unknown_language\n    r = Rocco.new( 'filename.an_extension_with_no_meaning_whatsoever', '', { :language => \"not-a-language\", :comment_chars => \"user\" } ) { \"\" }\n    assert_equal \"user\", r.options[:comment_chars][:single], \"`:comment_chars` should be the user's default when falling back to user-provided settings.\"\n  end\nend\n"
  },
  {
    "path": "test/test_descriptive_section_names.rb",
    "content": "require File.expand_path('../helper', __FILE__)\n\nclass RoccoDescriptiveSectionNamesTests < Test::Unit::TestCase\n  def test_section_name\n    r = roccoize( \"filename.rb\", \"# # Comment 1\\ndef codeblock\\nend\\n\" )\n    html = r.to_html\n    assert(\n      html.include?( \"\" ),\n      \"The first section should be named\"\n    )\n    assert(\n      html.include?( '' ),\n      \"The rendered HTML should link to a named section\"\n    )\n  end\n\n  def test_section_numbering\n    r = roccoize( \"filename.rb\", \"# # Header 1\\ndef codeblock\\nend\\n# Comment 1\\ndef codeblock1\\nend\\n# # Header 2\\ndef codeblock2\\nend\" )\n    html = r.to_html\n    assert(\n      html.include?( '' ) &&\n      html.include?( '' ),\n      \"First and second headers should be named sections\"\n    )\n    assert(\n      html.include?( '' ),\n      \"Sections should continue numbering as though headers were counted.\"\n    )\n  end\nend\n"
  },
  {
    "path": "test/test_docblock_annotations.rb",
    "content": "require File.expand_path('../helper', __FILE__)\n\nclass RoccoDocblockAnnotationsTest < Test::Unit::TestCase\n  def test_basics\n    r = Rocco.new( 'test', '', { :language => \"c\", :docblocks => true } ) { \"\" } # Generate throwaway instance so I can test `parse`\n    assert_equal(\n      [\n        \"Comment\\n\\n> **param** mixed foo  \\n> **return** void  \"\n      ],\n      r.docblock( [\"Comment\\n\\n@param mixed foo\\n@return void\"] )\n    )\n  end\n  def test_highlighted_in_blocks\n    r = Rocco.new( 'test', '', { :language => \"c\", :docblocks => true } ) { \"\" } # Generate throwaway instance so I can test `parse`\n    highlighted = r.highlight( r.split( r.parse( \"/**\\n * Comment\\n * @param type name\\n */\\ndef codeblock\\nend\\n\" ) ) )\n\n    assert_equal(\n      \"
Comment
\\n\\n
param type name
\\n\",\n      highlighted[0][0]\n    )\n  end\nend\n"
  },
  {
    "path": "test/test_heredoc.rb",
    "content": "require File.expand_path('../helper', __FILE__)\n\nclass RoccoHeredocTest < Test::Unit::TestCase\n  def test_basics\n    r = Rocco.new( 'test', '', { :language => \"rb\" } ) { \"\" } # Generate throwaway instance so I can test `parse`\n    assert_equal(\n      [\n        [ [ \"Comment 1\" ], [ \"heredoc <<-EOH\", \"#comment\", \"code\", \"EOH\" ] ]\n      ],\n      r.parse( \"# Comment 1\\nheredoc <<-EOH\\n#comment\\ncode\\nEOH\" )\n    )\n  end\nend\n"
  },
  {
    "path": "test/test_language_detection.rb",
    "content": "require File.expand_path('../helper', __FILE__)\n\nclass RoccoLanguageDetection < Test::Unit::TestCase\n  def test_basic_detection\n    r = Rocco.new( 'filename.py' ) { \"\" }\n    if r.pygmentize?\n      assert_equal \"python\", r.detect_language(), \"`detect_language()` should return the correct language\"\n      assert_equal \"python\", r.options[:language], \"`@options[:language]` should be set to the correct language\"\n    end\n  end\n\n  def test_fallback_default\n    r = Rocco.new( 'filename.an_extension_with_no_meaning_whatsoever' ) { \"\" }\n    if r.pygmentize?\n      assert_equal \"text\", r.detect_language(), \"`detect_language()` should return `text` when nothing else is detected\"\n      assert_equal \"ruby\", r.options[:language], \"`@options[:language]` should be set to `ruby` when nothing else is detected\"\n    end\n  end\n\n  def test_fallback_user\n    r = Rocco.new( 'filename.an_extension_with_no_meaning_whatsoever', '', { :language => \"c\" } ) { \"\" }\n    if r.pygmentize?\n      assert_equal \"text\", r.detect_language(), \"`detect_language()` should return `text` nothing else is detected\"\n      assert_equal \"c\", r.options[:language], \"`@options[:language]` should be set to the user's setting when nothing else is detected\"\n    end\n  end\nend\n"
  },
  {
    "path": "test/test_reported_issues.rb",
    "content": "# encoding: utf-8\nrequire File.expand_path('../helper', __FILE__)\n\nclass RoccoIssueTests < Test::Unit::TestCase\n  def test_issue07_incorrect_parsing_in_c_mode\n    # Precursor to issue #13 below, Rocco incorrectly parsed C/C++\n    # http://github.com/rtomayko/rocco/issues#issue/7\n    r = Rocco.new( 'issue7.c', [], { :language => 'c' } ) {\n        \"// *stdio.h* declares *puts*\\n#include \\n\\n//### code hello world\\n\\n// every C program contains function *main*.\\nint main (int argc, char *argv[]) {\\n  puts('hello world');\\n  return 0;\\n}\\n\\n// that's it!\"\n    }\n    r.sections.each do | section |\n      if not section[1].nil?\n        assert(\n            !section[1].include?(\"# DIVIDER\"),\n            \"`# DIVIDER` present in code text, which means the highligher screwed up somewhere.\"\n        )\n      end\n    end\n  end\n\n  def test_issue10_utf8_processing\n    # Rocco has issues with strange UTF-8 characters: need to explicitly set the encoding for Pygments\n    # http://github.com/rtomayko/rocco/issues#issue/10\n    r = Rocco.new( File.dirname(__FILE__) + \"/fixtures/issue10.utf-8.rb\" )\n    assert_equal(\n      \"
hello ąćęłńóśźż
\\n\",\n      r.sections[0][0],\n      \"UTF-8 input files ought behave correctly.\"\n    )\n    # and, just for grins, ensure that iso-8859-1 works too.\n    # @TODO:    Is this really the correct behavior?  Converting text\n    #           to UTF-8 on the way out is probably preferable.\n    r = Rocco.new( File.dirname(__FILE__) + \"/fixtures/issue10.iso-8859-1.rb\" )\n    assert_equal(\n      \"
hello w\\366rld
\\n\",\n      r.sections[0][0],\n      \"ISO-8859-1 input should probably also behave correctly.\"\n    )\n  end\n\n  def test_issue12_css_octothorpe_classname_change\n    # Docco changed some CSS classes.  Rocco needs to update its default template.\n    # http://github.com/rtomayko/rocco/issues#issue/12\n    r = Rocco.new( 'issue12.sh' ) {\n      \"# Comment 1\\n# Comment 1\\nprint 'omg!'\"\n    }\n    html = r.to_html\n    assert(\n      !html.include?( \"
\" ),\n      \"`octowrap` wrapper is present in rendered HTML.  This ought be replaced with `pilwrap`.\"\n    )\n    assert(\n      !html.include?( \"\" ),\n      \"`octothorpe` link is present in rendered HTML.  This ought be replaced with `pilcrow`.\"\n    )\n  end\n\n  def test_issue13_incorrect_code_divider_parsing\n    # In `bash` mode (among others), the comment class is `c`, not `c1`.\n    # http://github.com/rtomayko/rocco/issues#issue/13\n    r = Rocco.new( 'issue13.sh', [], { :language => 'bash' } ) {\n      \"# Comment 1\\necho 'code';\\n# Comment 2\\necho 'code';\\n# Comment 3\\necho 'code';\\n\"\n    }\n    r.sections.each do | section |\n      if not section[1].nil?\n        assert(\n          !section[1].include?(\"# DIVIDER\"),\n          \"`# DIVIDER` present in code text, which means the highligher screwed up somewhere.\"\n        )\n      end\n    end\n  end\n\n  def test_issue15_extra_space_after_comment_character_remains\n    # After the comment character, a single space should be removed.\n    # http://github.com/rtomayko/rocco/issues#issue/15\n    r = Rocco.new( 'issue15.sh') {\n      \"# Comment 1\\n# ---------\\necho 'code';\"\n    }\n    assert(\n      !r.sections[0][0].include?( \"
\" ),\n      \"`
` present in rendered documentation text.  It should be a header, not text followed by a horizontal rule.\"\n    )\n    assert_equal(\"
Comment 1
\\n\", r.sections[0][0])\n  end\nend\n"
  },
  {
    "path": "test/test_skippable_lines.rb",
    "content": "require File.expand_path('../helper', __FILE__)\n\nclass RoccoSkippableLines < Test::Unit::TestCase\n  def test_shebang_first_line\n    r = Rocco.new( 'filename.sh' ) { \"\" }\n    assert_equal(\n      [\n        [ [ \"Comment 1\" ], [ \"def codeblock\" ] ],\n        [ [ \"Comment 2\" ], [ \"end\" ] ]\n      ],\n      r.parse( \"#!/usr/bin/env bash\\n# Comment 1\\ndef codeblock\\n# Comment 2\\nend\\n\" ),\n      \"Shebang should be stripped when it appears as the first line.\"\n    )\n  end\n\n  def test_shebang_in_content\n    r = Rocco.new( 'filename.sh' ) { \"\" }\n    assert_equal(\n      [\n        # @TODO: `#!/` shouldn't be recognized as a comment.\n        [ [ \"Comment 1\", \"!/usr/bin/env bash\" ], [ \"def codeblock\" ] ],\n        [ [ \"Comment 2\" ], [ \"end\" ] ]\n      ],\n      r.parse( \"# Comment 1\\n#!/usr/bin/env bash\\ndef codeblock\\n# Comment 2\\nend\\n\" ),\n      \"Shebang shouldn't be stripped anywhere other than as the first line.\"\n    )\n  end\n\n  def test_encoding_in_ruby\n    r = Rocco.new( 'filename.rb' ) { \"\" }\n    assert_equal(\n      [\n        [ [ \"Comment 1\" ], [ \"def codeblock\" ] ],\n        [ [ \"Comment 2\" ], [ \"end\" ] ]\n      ],\n      r.parse( \"#!/usr/bin/env bash\\n# encoding: utf-8\\n# Comment 1\\ndef codeblock\\n# Comment 2\\nend\\n\" ),\n      \"Strings matching the PEP 263 encoding definition regex should be stripped when they appear at the top of a python document.\"\n    )\n  end\n\n  def test_encoding_in_python\n    r = Rocco.new( 'filename.py' ) { \"\" }\n    assert_equal(\n      [\n        [ [ \"Comment 1\" ], [ \"def codeblock\" ] ],\n        [ [ \"Comment 2\" ], [ \"end\" ] ]\n      ],\n      r.parse( \"#!/usr/bin/env bash\\n# encoding: utf-8\\n# Comment 1\\ndef codeblock\\n# Comment 2\\nend\\n\" ),\n      \"Strings matching the PEP 263 encoding definition regex should be stripped when they appear at the top of a python document.\"\n    )\n  end\n\n  def test_encoding_in_notpython\n    r = Rocco.new( 'filename.sh' ) { \"\" }\n    assert_equal(\n      [\n        [ [ \"encoding: utf-8\", \"Comment 1\" ], [ \"def codeblock\" ] ],\n        [ [ \"Comment 2\" ], [ \"end\" ] ]\n      ],\n      r.parse( \"#!/usr/bin/env bash\\n# encoding: utf-8\\n# Comment 1\\ndef codeblock\\n# Comment 2\\nend\\n\" ),\n      \"Strings matching the PEP 263 encoding definition regex should be stripped when they appear at the top of a python document.\"\n    )\n  end\nend\n"
  },
  {
    "path": "test/test_source_list.rb",
    "content": "require File.expand_path('../helper', __FILE__)\n\nclass RoccoSourceListTests < Test::Unit::TestCase\n  def test_flat_sourcelist\n    r = Rocco.new( 'issue26.sh', [ 'issue26a.sh', 'issue26b.sh', 'issue26c.sh' ] ) {\n        \"# Comment 1\\n# Comment 1\\nprint 'omg!'\"\n    }\n    html = r.to_html\n    assert(\n      html.include?( 'issue26a.sh' ) &&\n      html.include?( 'issue26b.sh' ) &&\n      html.include?( 'issue26c.sh' ),\n      \"URLs correctly generated for files in a flat directory structure\"\n    )\n  end\n\n  def test_heiarachical_sourcelist\n    r = Rocco.new( 'a/issue26.sh', [ 'a/issue26a.sh', 'b/issue26b.sh', 'c/issue26c.sh' ] ) {\n        \"# Comment 1\\n# Comment 1\\nprint 'omg!'\"\n    }\n    html = r.to_html\n    assert(\n      html.include?( 'issue26a.sh' ) &&\n      html.include?( 'issue26b.sh' ) &&\n      html.include?( 'issue26c.sh' ),\n      \"URLs correctly generated for files in a flat directory structure\"\n    )\n  end\nend\n"
  },
  {
    "path": "test/test_stylesheet.rb",
    "content": "require File.expand_path('../helper', __FILE__)\n\nclass RoccoStylesheetTests < Test::Unit::TestCase\n  def test_default_stylesheet\n    r = Rocco.new( 'file.rb', [ 'file.rb'] ) {\n      \"# Content\"\n    }\n    html = r.to_html\n    assert(\n      html.include?('')\n    )\n  end\n\n  def test_custom_stylesheet\n    r = Rocco.new( 'file.rb', [ 'file.rb'], :stylesheet => 'http://example.com/custom.css' ) {\n      \"# Content\"\n    }\n    html = r.to_html\n    assert(\n      html.include?('')\n    )\n  end\nend\n"
  }
]