codnar 0.1.64

data/lib/codnar/string_extensions.rb

@@ -0,0 +1,25 @@
+# Extend the core String class.
+class String
+
+  # Convert this String to an identifier. This is a stable operation, so
+  # anything that accept a name will also accept an identifier as well.
+  def to_id
+    return self.strip.gsub(/[^a-zA-Z0-9]+/, "-").downcase
+  end
+
+  # {{{ Clean HTML
+
+  # Clean HTML generated by markup formatters. Such HTML tends to have extra
+  # empty lines for no apparent reason. Cleaning it up seems to be safe enough,
+  # and eliminates the ugly additional vertical space in the final HTML.
+  def clean_markup_html
+    return gsub(/\n*<p>\n*/, "\n<p>\n") \
+          .gsub(/\n*<\/p>\n*/, "\n</p>\n") \
+          .gsub(/\n*<pre>\n*/, "\n<pre>\n") \
+          .gsub(/\n*<\/pre>\n*/, "\n</pre>\n") \
+          .sub(/^\n*/, "")
+  end
+
+  # }}}
+
+end

data/lib/codnar/sunlight.rb

@@ -0,0 +1,17 @@
+module Codnar
+
+  # Syntax highlight using Sunlight.
+  class Sunlight
+
+    # Convert a sequence of classified code lines to HTML using Sunlight syntax
+    # highlighting. All we need to do is wrap the lines in an HTML +pre+
+    # element with the correct class (<tt>sunlight-highlight-_syntax_</tt>).
+    # The actual highlighting is done in the HTML DOM using Javascript.
+    # Embedding this Javascript into the final HTML should be done separately.
+    def self.lines_to_html(lines, syntax)
+      return Formatter.lines_to_pre_html(lines, :class => "sunlight-highlight-#{syntax}")
+    end
+
+  end
+
+end

data/lib/codnar/version.rb

@@ -0,0 +1,8 @@
+# This module contains all the code narrator code.
+module Codnar
+
+  # This version number. The third number is automatically updated to track the
+  # number of Git commits by running <tt>rake version</tt>.
+  VERSION = "0.1.64"
+
+end

data/lib/codnar/weave.rb

@@ -0,0 +1,58 @@
+module Codnar
+
+  # Weave application.
+  class Weave < Application
+
+    # Run the weaving Codnar application, returning its status.
+    def run
+      super { weave }
+    end
+
+  protected
+
+    # Weave all the chunks together to a single HTML.
+    def weave
+      @configuration = Codnar::Configuration::WEAVE_INCLUDE if @configuration == {}
+      weaver = Weaver.new(@errors, ARGV, @configuration)
+      puts(weaver.weave("include"))
+      weaver.collect_unused_chunk_errors
+    end
+
+    # Parse remaining command-line file arguments.
+    def parse_arguments
+      return if ARGV.size > 0
+      $stderr.puts("#{$0}: No chunk files to weave")
+      exit(1)
+    end
+
+    # Return the banner line of the help message.
+    def banner
+      return "codnar-weave - Weave documentation chunks to a single HTML."
+    end
+
+    # Return the name and description of any final command-line file arguments.
+    def arguments
+      return "MAIN-CHUNK ADDITIONAL-CHUNKS", "Chunk files to weave together."
+    end
+
+    # Return a short description of the program.
+    def description
+      print(<<-EOF.unindent)
+        Weave chunks in all chunk files (from codnar-split) to a single HTML that is
+        printed to the output. The first file is the main documentation file that is
+        expected to include all the rest of the chunks via directives of the format:
+
+          <embed src="chunk-name" type="x-codnar/template-name"></embed>
+
+        Where the template-name is a key in the configuration, whose value is an ERB
+        template for embedding the named chunk into the documentation.
+
+        If no configuration is specified, the WEAVE_INCLUDE configuration is assumed.
+        This configuration contains a single template named "include", which simply
+        includes the named chunk into the generated HTML.
+      EOF
+    end
+
+  end
+
+end

data/lib/codnar/weave_configurations.rb

@@ -0,0 +1,48 @@
+module Codnar
+
+  module Configuration
+
+    # Weave configuration providing a single simple +include+ template.
+    WEAVE_INCLUDE = { "include" => "<%= chunk.expanded_html %>\n" }
+
+    # Weave chunks in the plainest possible way.
+    WEAVE_PLAIN_CHUNK = {
+      "plain_chunk" => <<-EOF.unindent, #! ((( html
+        <div class="plain chunk">
+        <a name="<%= chunk.name.to_id %>"/>
+        <%= chunk.expanded_html %>
+        </div>
+      EOF
+    } #! ))) html
+
+    # Weave chunks with their name and the list of container chunks.
+    WEAVE_NAMED_CHUNK_WITH_CONTAINERS = {
+      "named_chunk_with_containers" => <<-EOF.unindent, #! ((( html
+        <div class="named_with_containers chunk">
+        <div class="chunk name">
+        <a name="<%= chunk.name.to_id %>">
+        <span><%= CGI.escapeHTML(chunk.name) %></span>
+        </a>
+        </div>
+        <div class="chunk html">
+        <%= chunk.expanded_html %>
+        </div>
+        % if chunk.containers != []
+        <div class="chunk containers">
+        <span class="chunk containers header">Contained in:</span>
+        <ul class="chunk containers">
+        % chunk.containers.each do |container|
+        <li class="chunk container">
+        <a class="chunk container" href="#<%= container.to_id %>"><%= CGI.escapeHTML(container) %></a>
+        </li>
+        % end
+        </ul>
+        </div>
+        % end
+        </div>
+      EOF
+    } #! ))) html
+
+  end
+
+end

data/lib/codnar/weaver.rb

@@ -0,0 +1,105 @@
+module Codnar
+
+  # Weave all chunks to a unified HTML.
+  class Weaver < Reader
+
+    # Load all chunks from the specified disk files to memory for weaving using
+    # the specified templates.
+    def initialize(errors, paths, templates)
+      super(errors, paths)
+      @templates = templates
+    end
+
+    # How to process each magical file template.
+    FILE_TEMPLATE_PROCESSORS = {
+      "file" => lambda { |name, data| data },
+      "image" => lambda { |name, data| Weaver.embedded_base64_img_tag(name, data) },
+    }
+
+    # Weave the HTML for a named chunk.
+    def weave(template, chunk_name = @root_chunk)
+      return process_file_template(template, chunk_name) if FILE_TEMPLATE_PROCESSORS.include?(template)
+      @last_chunk = chunk = self[chunk_name.to_id]
+      expand_chunk_html(chunk)
+      return process_template(chunk, template)
+    end
+
+  protected
+
+    # Due to http://github.com/relevance/rcov/issues/#issue/43 the following regular expressions must be on a single line.
+
+    # Detect embedded chunks (+type+ before +src+).
+    TYPE_SRC_CHUNK = / [ ]* <embed \s+ type = ['\"] x-codnar\/ (.*?) ['\"] \s+ src = ['\"] \#* (.*?) ['\"] \s* (?: \/> | > \s* <\/embed> ) [ ]* /x
+
+    # Detect embedded chunks (+src+ before +type+).
+    SRC_TYPE_CHUNK = / [ ]* <embed \s+ src = ['\"] \#* (.*?) ['\"] \s+ type = ['\"] x-codnar\/ (.*?) ['\"] \s* (?: \/> | > \s* <\/embed> ) [ ]* /x
+
+    # Recursively expand all embedded chunks inside a container chunk.
+    def expand_chunk_html(chunk)
+      html = chunk.html
+      @errors.push("No HTML in chunk: #{chunk.name} #{Weaver.locations_message(chunk)}") unless html
+      #! TRICKY: All "container" chunks are assumed to be whole-file chunks with
+      #! a single location. Which makes sense as these are documentation and not
+      #! code chunks. TODO: It would be nice to know the exact line number of
+      #! the chunk embedding directive for better pinpointing of any error.
+      @errors.in_path(chunk.locations[0].file) do
+        chunk.expanded_html ||= expand_embedded_chunks(html || "").chomp
+      end
+    end
+
+    # Recursively expand_embedded_chunks all embedded chunk inside an HTML.
+    def expand_embedded_chunks(html)
+      return html.gsub(TYPE_SRC_CHUNK) { |match| weave($1, $2).chomp } \
+                 .gsub(SRC_TYPE_CHUNK) { |match| weave($2, $1).chomp }
+    end
+
+    # Process the chunk using an ERB template prior to inclusion in container
+    # chunk.
+    def process_template(chunk, template_name)
+      template_text = @templates[template_name] ||= (
+        @errors << "Missing ERB template: #{template_name}"
+        "<%= chunk.expanded_html %>\n"
+      )
+      return (
+        (
+          chunk.erb ||= {}
+        )[template_name] ||= ERB.new(template_text, nil, "%")
+      ).result(binding)
+    end
+
+    # {{{ Processing the file template
+
+    # Process one of the magical file templates. The content of the file,
+    # optionally processed, is directly embedded into the generated
+    # documentation. If the file's path begins with ".", it is taken to be
+    # relative to the current working directory. Otherwise, it is searched for
+    # in Ruby's load path, allowing easy access to files packaged inside gems.
+    def process_file_template(template, path)
+      begin
+        path = Olag::DataFiles.expand_path(path) unless path[0,1] == "."
+        return FILE_TEMPLATE_PROCESSORS[template].call(path, File.read(path))
+      rescue Exception => exception
+        @errors.push("#{$0}: Reading file: #{path} exception: #{exception} #{Reader.locations_message(@last_chunk)}") \
+          if @last_chunk
+        return "FILE: #{path} EXCEPTION: #{exception}"
+      end
+    end
+
+    # }}}
+
+    # {{{ Processing Base64 embedded data images
+
+    # Create an +img+ tag with an embedded data URL. Different browsers have
+    # different constraints about the size of the resulting URL, so YMMV.
+    def self.embedded_base64_img_tag(name, data)
+      extension = File.extname(name).sub(".", "/")
+      return "<img src='data:image#{extension};base64," \
+           + Base64.encode64(data) \
+           + "'/>"
+    end
+
+    # }}}
+
+  end
+
+end

data/lib/codnar/writer.rb

@@ -0,0 +1,38 @@
+module Codnar
+
+  # Write chunks into a disk file.
+  class Writer
+
+    # Write one chunk or an array of chunks to a disk file.
+    def self.write(path, data)
+      self.new(path) do |writer|
+        writer << data
+      end
+    end
+
+    # Add one chunk or an array of chunks to the disk file.
+    def <<(data)
+      case data
+      when Array
+        @chunks += data
+      when Hash
+        @chunks << data
+      else
+        raise "Invalid data class: #{data.class}"
+      end
+    end
+
+  protected
+
+    # Write chunks into the specified disk file.
+    def initialize(path, &block)
+      @chunks = []
+      File.open(path, "w") do |file|
+        block.call(self)
+        file.print(@chunks.to_yaml)
+      end
+    end
+
+  end
+
+end

data/test/cache_computations.rb

@@ -0,0 +1,41 @@
+require "codnar"
+require "olag/test"
+require "test/spec"
+
+# Test caching long computations.
+class TestCacheComputations < Test::Unit::TestCase
+
+  include Test::WithTempfile
+
+  def test_cached_computation
+    cache = make_addition_cache(directory = create_tempdir(".."))
+    cache[1].should == 2
+    File.open(Dir.glob(directory + "/*")[0], "w") { |file| file.puts("3") }
+    cache[1].should == 3
+    cache.force_recompute = true
+    cache[1].should == 2
+  end
+
+  def test_uncached_computation
+    stderr = capture_stderr { make_addition_cache("no-such-directory")[1].should == 2 }
+    stderr.should.include?("no-such-directory")
+  end
+
+protected
+
+  # Run a block and capture its standard error (without using FakeFS).
+  def capture_stderr
+    stderr_path = write_tempfile("stderr", "")
+    Olag::Globals.without_changes do
+      $stderr = File.open(stderr_path, "w")
+      yield
+    end
+    return File.read(stderr_path)
+  end
+
+  # Create a cache for the "+ 1" operation.
+  def make_addition_cache(directory)
+    return Codnar::Cache.new(directory) { |value| value + 1 }
+  end
+
+end

data/test/deep_merge.rb

@@ -0,0 +1,29 @@
+require "codnar"
+require "test/spec"
+
+# Test deep-merging complex structures.
+class TestDeepMerge < Test::Unit::TestCase
+
+  def test_deep_merge
+    default = {
+      "only_default" => "default_value",
+      "overriden" => "default_value",
+      "overriden_array" => [ "default_value" ],
+      "merged_array" => [ "default_value" ],
+    }
+    override = {
+      "only_override" => "overriden_value",
+      "overriden" => "overriden_value",
+      "overriden_array" => [ "overriden_value" ],
+      "merged_array" => [ "overriden_value", [] ],
+    }
+    default.deep_merge(override).should == {
+      "only_default" => "default_value",
+      "only_override" => "overriden_value",
+      "overriden" => "overriden_value",
+      "overriden_array" => [ "overriden_value" ],
+      "merged_array" => [ "overriden_value", "default_value" ],
+    }
+  end
+
+end

data/test/embed_images.rb

@@ -0,0 +1,12 @@
+require "codnar"
+require "test/spec"
+
+# Test computing embedded image HTML tags.
+class TestEmbedImages < Test::Unit::TestCase
+
+  def test_embed_image
+    Codnar::Weaver.embedded_base64_img_tag('fake file.png', 'fake file content').should \
+      == "<img src='data:image/png;base64,ZmFrZSBmaWxlIGNvbnRlbnQ=\n'/>"
+  end
+
+end

data/test/expand_markdown.rb

@@ -0,0 +1,27 @@
+require "codnar"
+require "test/spec"
+
+# Test expanding Markdown text.
+class TestExpandMarkdown < Test::Unit::TestCase
+
+  def test_emphasis_text
+    Markdown.to_html("*text*").should == "<p>\n<em>text</em>\n</p>\n"
+  end
+
+  def test_strong_text
+    Markdown.to_html("**text**").should == "<p>\n<strong>text</strong>\n</p>\n"
+  end
+
+  def test_embed_chunk
+    Markdown.to_html("[[Chunk|template]]").should == "<p>\n<embed src='chunk' type='x-codnar/template'/>\n</p>\n"
+  end
+
+  def test_embed_anchor
+    Markdown.to_html("[[#Name]]").should == "<p>\n<a id='name'/>\n</p>\n"
+  end
+
+  def test_embed_link
+    Markdown.to_html("[Label](#Name)").should == "<p>\n<a href=\"#name\">Label</a>\n</p>\n"
+  end
+
+end

data/test/expand_rdoc.rb

@@ -0,0 +1,20 @@
+require "codnar"
+require "test/spec"
+
+# Test expanding RDoc text.
+class TestExpandRDoc < Test::Unit::TestCase
+
+  def test_emphasis_text
+    RDoc.to_html("_text_").should == "<p>\n<em>text</em>\n</p>\n"
+  end
+
+  def test_strong_text
+    RDoc.to_html("*text*").should == "<p>\n<b>text</b>\n</p>\n"
+  end
+
+  def test_indented_pre
+    RDoc.to_html("base\n  indented\n    more\nback\n").should \
+      == "<p>\nbase\n</p>\n<pre>\nindented\n  more\n</pre>\n<p>\nback\n</p>\n"
+  end
+
+end

data/test/format_code_gvim_configurations.rb

@@ -0,0 +1,55 @@
+require "codnar"
+require "olag/test"
+require "test/spec"
+require "test_with_configurations"
+
+# Test built-in split code formatting configurations using GVim.
+class TestGVimFormatCodeConfigurations < Test::Unit::TestCase
+
+  include Test::WithConfigurations
+  include Test::WithErrors
+  include Test::WithTempfile
+
+  CODE_TEXT = <<-EOF.unindent
+    int x;
+  EOF
+
+  GVIM_HTML = <<-EOF.unindent.chomp
+    <div class='c code syntax' bgcolor=\"#ffffff\" text=\"#000000\">
+    <font face=\"monospace\">
+    <font color=\"#00ff00\">int</font>&nbsp;x;<br />
+    </font>
+    </div>
+  EOF
+
+  def test_html_code
+    check_any_code(GVIM_HTML, Codnar::Configuration::FORMAT_CODE_GVIM_HTML.call("c"))
+  end
+
+  GVIM_CSS = <<-EOF.unindent.chomp
+    <pre class='c code syntax'>
+    <span class=\"Type\">int</span> x;
+    </pre>
+  EOF
+
+  def test_css_code
+    check_any_code(GVIM_CSS, Codnar::Configuration::FORMAT_CODE_GVIM_CSS.call("c"))
+  end
+
+protected
+
+  def check_any_code(html, configuration)
+    check_split_file(CODE_TEXT,
+                     Codnar::Configuration::CLASSIFY_SOURCE_CODE.call("c"),
+                     configuration) do |path|
+      [ {
+        "name" => path,
+        "locations" => [ { "file" => path, "line" => 1 } ],
+        "containers" => [],
+        "contained" => [],
+        "html" => html,
+      } ]
+    end
+  end
+
+end