devver-germinate 1.0.0

data/features/example_articles/specials.rb

@@ -0,0 +1,19 @@
+# :SAMPLE: A
+a_line_1 = 1
+a_line_2 = 2
+a_line_3 = 3
+a_line_4 = 4
+
+# :SAMPLE: B
+b_line_1 = 1
+b_line_2 = 2
+
+# :TEXT:
+# We can paste in all the code:
+# :INSERT: $CODE
+# 
+# Or all the text:
+# :INSERT: $TEXT
+#
+# Or the entire source file
+# :INSERT: $SOURCE

data/features/example_articles/wrapping.rb

@@ -0,0 +1,8 @@
+# An example of text-wrappeing
+#
+# :TEXT:
+# 'Twas brillig and the slithy toves
+# Did gyre and gimbal in the wabe
+#
+# All mimsy were the borogroves
+# And the momeraths outgrabe

data/features/example_output/code_samples.txt

@@ -0,0 +1,186 @@
+Hi there!  Here's a Hello, World method:
+
+def hello
+  puts "Hello, World!"
+end
+
+The immediately following code sample can be implicitly referenced:
+
+def nameless
+  puts "I have no name"
+end
+
+Or explicitly referenced
+
+def foo
+  puts "foo"
+end
+
+Samples can be referenced by name
+
+def fred
+  # This comment is part of the sample
+  puts "Hello, my name is Fred"
+  puts "la la la"
+end
+
+Or by index:
+
+def boring
+  1 + 1
+end
+
+SOURCE is a special sample which contains this entire source file.
+
+    # This example demonstrates the use of code samples.
+
+    # :TEXT:
+    # Hi there!  Here's a Hello, World method:
+
+    def hello
+      puts "Hello, World!"
+    end
+
+    # :CUT:
+    # Here's some boring support code we don't want to show the world.
+
+    def boring
+      1 + 1
+    end
+
+    # Here are two a named samples:
+    # :SAMPLE: fred
+
+    def fred
+      # This comment is part of the sample
+      puts "Hello, my name is Fred"
+      puts "la la la"
+    end
+
+    # :SAMPLE: sally
+
+    def sally
+      puts "Hello, my name is Sally"
+    end
+
+    # :END:
+    # Sample "sally" ends above, and does not include the following.
+
+    def wizard
+      puts "Pay no attention to the man behind the curtain!"
+    end
+
+    # Samples can be inside comment blocks
+    # :SAMPLE: george
+    #    (defun george () (format "Hello from George"))
+    # :CUT:
+
+    # Samples can have comment markers stripped
+    # :SAMPLE: mary, { uncomment: true }
+    #    (defun mary () (format "Hello from Mary"))
+    # :CUT:
+
+    # :TEXT:
+    # The immediately following code sample can be implicitly referenced:
+    # :INSERT:
+    # :CUT:
+    def nameless
+      puts "I have no name"
+    end
+
+    # :TEXT:
+    # Or explicitly referenced
+    # :INSERT: FOLLOWING
+    # :CUT:
+    def foo
+      puts "foo"
+    end
+
+    # :TEXT:
+    # Samples can be referenced by name
+    # :INSERT: fred
+    # 
+    # Or by index:
+    # :INSERT: #2
+    #
+    # SOURCE is a special sample which contains this entire source file.
+    # :INSERT: SOURCE, { indent: 4 }
+    #
+    # CODE is a special sample which contains all the non-text portions of this
+    # file.
+    # :INSERT: CODE, { indent: " > " }
+    #
+    # We can select specific lines:
+    # :INSERT: sally:2
+    #
+    # Or ranges of lines:
+    # :INSERT: sally:2..3
+    # 
+    # Or lines matching a regex:
+    # :INSERT: sally:/def/
+    #
+    # Or ranges of regexen:
+    # :INSERT: fred:/puts/.../end/
+
+CODE is a special sample which contains all the non-text portions of this file.
+
+ > # This example demonstrates the use of code samples.
+ >
+ > def hello
+ >   puts "Hello, World!"
+ > end
+ >
+ > # Here's some boring support code we don't want to show the world.
+ >
+ > def boring
+ >   1 + 1
+ > end
+ >
+ > # Here are two a named samples:
+ >
+ > def fred
+ >   # This comment is part of the sample
+ >   puts "Hello, my name is Fred"
+ >   puts "la la la"
+ > end
+ >
+ > def sally
+ >   puts "Hello, my name is Sally"
+ > end
+ > 
+ > # Sample "sally" ends above, and does not include the following.
+ > 
+ > def wizard
+ >   puts "Pay no attention to the man behind the curtain!"
+ > end
+ >
+ > # Samples can be inside comment blocks
+ > 
+ > # Samples can have comment markers stripped
+ > 
+ > def nameless
+ >   puts "I have no name"
+ > end
+ >
+ > def foo
+ >   puts "foo"
+ > end
+
+We can select specific lines:
+
+  puts "Hello, my name is Sally"
+
+Or ranges of lines:
+
+  puts "Hello, my name is Sally"
+end
+
+Or lines matching a regex:
+
+  def sally
+
+# Or ranges of regexen:
+
+  puts "Hello, my name is Fred"
+  puts "la la la"
+

data/features/example_output/escaping.out

@@ -0,0 +1,5 @@
+Here are some Germinate directives :TEXT: :SAMPLE: :INSERT: You get the idea.
+
+It works in code too:
+
+# :PROCESS: foo, bar

data/features/example_output/hello.txt

@@ -0,0 +1 @@
+Hello, world!

data/features/example_output/pipelines.out

@@ -0,0 +1,28 @@
+Sorting the sample:
+aaron
+george
+joe
+sally
+susan
+zack
+
+Quoting the sample:
+> joe
+> sally
+> aaron
+> george
+> zack
+> susan
+
+We can combine pipelines with excerpting:
+> sally
+> aaron
+> george
+
+And we can chain processes to form a true pipeline:
+> aaron
+> george
+> joe
+> sally
+> susan
+> zack

data/features/example_output/regexen.txt

@@ -0,0 +1,22 @@
+We can select code by regexp
+def foo
+  # ...
+end
+
+Or with a regex and a length
+def bar
+  # ...
+end
+
+class Frob
+  # ...
+end
+
+Ending offset can be exclusive
+def foo
+  # ...
+end
+
+def bar
+  # ...
+end

data/features/example_output/sample_offsets.txt

@@ -0,0 +1,15 @@
+We can specify a starting offset:
+a_line_2 = 2
+
+And an ending offset
+a_line_2 = 2
+a_line_3 = 3
+
+Ending offset can be exclusive
+a_line_1 = 1
+a_line_2 = 2
+
+We can specify offset and count instead
+a_line_2 = 2
+a_line_3 = 3
+a_line_4 = 4

data/features/example_output/specials.txt

@@ -0,0 +1,36 @@
+We can paste in all the code:
+a_line_1 = 1
+a_line_2 = 2
+a_line_3 = 3
+a_line_4 = 4
+
+b_line_1 = 1
+b_line_2 = 2
+
+Or all the text:
+# We can paste in all the code:
+#
+# Or all the text:
+#
+# Or the entire source file
+
+Or the entire source file
+# :SAMPLE: A
+a_line_1 = 1
+a_line_2 = 2
+a_line_3 = 3
+a_line_4 = 4
+
+# :SAMPLE: B
+b_line_1 = 1
+b_line_2 = 2
+
+# :TEXT:
+# We can paste in all the code:
+# :INSERT: $CODE
+#
+# Or all the text:
+# :INSERT: $TEXT
+#
+# Or the entire source file
+# :INSERT: $SOURCE

data/features/example_output/wrapping.txt

@@ -0,0 +1,3 @@
+'Twas brillig and the slithy toves Did gyre and gimbal in the wabe
+
+All mimsy were the borogroves And the momeraths outgrabe

data/features/step_definitions/germinate.rb

@@ -0,0 +1,30 @@
+require 'tempfile'
+
+Given /^the article "([^\"]*)"$/ do |article_file|
+  @filename = (EXAMPLE_ARTICLES + article_file)
+end
+
+When /^I run the format command on the article$/ do
+  run_germinate("format #{@filename}")
+end
+
+When /^I run the command "([^\"]*)" on the article$/ do |command|
+  run_germinate(command.sub(/^germ /,"") + " #{@filename}")
+end
+
+Then /^the output should look like "([^\"]*)"$/ do |output_file|
+  example_path   = (EXAMPLE_OUTPUT + output_file)
+  example_output = example_path.read
+  @output.should == example_output
+end
+
+Given /^an article with the contents:$/ do |contents|
+  Tempfile.open("germinate_example_article") do |file|
+    file.write(contents)
+    @filename = Pathname(file.path)
+  end
+end
+
+Then /^the output should be as follows:$/ do |example_output|
+  @output.strip.should == example_output.strip
+end

data/features/support/env.rb

@@ -0,0 +1,18 @@
+require 'English'
+require 'pathname'
+require 'spec/expectations'
+require File.expand_path('../../lib/germinate', File.dirname(__FILE__))
+
+EXAMPLE_ARTICLES = (Pathname(__FILE__).dirname + '../example_articles')
+EXAMPLE_OUTPUT = (Pathname(__FILE__).dirname + '../example_output')
+EXAMPLE_BIN = (Pathname(__FILE__).dirname + '../bin')
+
+ENV['PATH'] += ":" + EXAMPLE_BIN.to_s
+
+def run_germinate(arguments, permit_failure=false)
+  exec_path = (Pathname(__FILE__).dirname + '..' + '..' + 'bin/germ').expand_path
+  command   = "#{exec_path} #{arguments}"
+  @output   = `#{command}`
+  @result   = $CHILD_STATUS
+  raise "Command `#{command}` failed" unless @result.success? or permit_failure
+end

data/germinate.gemspec

@@ -0,0 +1,55 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{germinate}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Avdi Grimm"]
+  s.date = %q{2009-07-10}
+  s.default_executable = %q{germ}
+  s.description = %q{Germinate is a tool for writing about code.  With Germinate, the source code IS the article.  For example, given the following source code:  # #!/usr/bin/env ruby # :BRACKET_CODE: <pre>, </pre> # :PROCESS: ruby, "ruby %f"  # :SAMPLE: hello def hello(who) puts "Hello, #{who}" end  hello("World")  # :TEXT: # Check out my amazing program!  Here's the hello method: # :INSERT: @hello:/def/../end/  # And here's the output: # :INSERT: @hello|ruby  When we run the <tt>germ format</tt> command the following output is generated:  Check out my amazing program!  Here's the hello method: <pre> def hello(who) puts "Hello, #{who}" end </pre> And here's the output: <pre> Hello, World </pre>  To get a better idea of how this works, please take a look at link:examples/basic.rb, or run:  germ generate > basic.rb  To generate an example article to play with.  Germinate is particularly useful for writing articles, such as blog posts, which contain code excerpts.  Instead of forcing you to keep a source code file and an article document in sync throughout the editing process, the Germinate motto is "The source code IS the article".  Specially marked comment sections in your code file become the article text.  Wherever you need to reference the source code in the article, use insertion directives to tell Germinate what parts of the code to excerpt.  An advanced selector syntax enables you to be very specific about which lines of code you want to insert.  If you also want to show the output of your code, Germinate has you covered. Special "process" directives enable you to define arbitrary commands which can be run on your code.  The output of the command then becomes the excerpt text. You can define an arbitrary number of processes and have different excerpts showing the same code as processed by different commands.  You can even string processes together into pipelines.  Development of Germinate is graciously sponsored by Devver, purveyor of fine cloud-based services to busy Ruby developers.  If you like this tool please check them out at http://devver.net.}
+  s.email = %q{avdi@avdi.org}
+  s.executables = ["germ"]
+  s.extra_rdoc_files = ["History.txt", "README.rdoc", "bin/germ"]
+  s.files = [".gitignore", "History.txt", "README.rdoc", "Rakefile", "bin/germ", "cucumber.yml", "examples/basic.rb", "examples/short.rb", "features/author-formats-article.feature", "features/author-lists-info.feature", "features/author-publishes-article-source.feature", "features/author-publishes-article.feature", "features/author-republishes-article.feature", "features/author-selects-hunks.feature", "features/author-updates-article-source.feature", "features/author-views-stuff.feature", "features/bin/quoter", "features/bin/sorter", "features/example_articles/code_samples.rb", "features/example_articles/escaping.txt", "features/example_articles/hello.rb", "features/example_articles/pipelines.txt", "features/example_articles/regexen.rb", "features/example_articles/sample_offsets.rb", "features/example_articles/specials.rb", "features/example_articles/wrapping.rb", "features/example_output/code_samples.txt", "features/example_output/escaping.out", "features/example_output/hello.txt", "features/example_output/pipelines.out", "features/example_output/regexen.txt", "features/example_output/sample_offsets.txt", "features/example_output/specials.txt", "features/example_output/wrapping.txt", "features/step_definitions/germinate.rb", "features/support/env.rb", "germinate.gemspec", "lib/germinate.rb", "lib/germinate/application.rb", "lib/germinate/article_editor.rb", "lib/germinate/article_formatter.rb", "lib/germinate/formatter.rb", "lib/germinate/hunk.rb", "lib/germinate/implicit_insertion.rb", "lib/germinate/insertion.rb", "lib/germinate/librarian.rb", "lib/germinate/pipeline.rb", "lib/germinate/process.rb", "lib/germinate/reader.rb", "lib/germinate/selector.rb", "lib/germinate/shared_style_attributes.rb", "lib/germinate/text_transforms.rb", "spec/germinate/application_spec.rb", "spec/germinate/article_editor_spec.rb", "spec/germinate/article_formatter_spec.rb", "spec/germinate/code_hunk_spec.rb", "spec/germinate/formatter_spec.rb", "spec/germinate/hunk_spec.rb", "spec/germinate/implicit_insertion_spec.rb", "spec/germinate/insertion_spec.rb", "spec/germinate/librarian_spec.rb", "spec/germinate/pipeline_spec.rb", "spec/germinate/process_spec.rb", "spec/germinate/reader_spec.rb", "spec/germinate/selector_spec.rb", "spec/germinate/text_hunk_spec.rb", "spec/germinate/text_transforms_spec.rb", "spec/germinate_spec.rb", "spec/spec.opts", "spec/spec_helper.rb", "tasks/ann.rake", "tasks/bones.rake", "tasks/cucumber.rake", "tasks/gem.rake", "tasks/git.rake", "tasks/notes.rake", "tasks/post_load.rake", "tasks/rdoc.rake", "tasks/rubyforge.rake", "tasks/setup.rb", "tasks/spec.rake", "tasks/svn.rake", "tasks/test.rake", "tasks/zentest.rake", "test/test_germinate.rb"]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/devver/germinate/}
+  s.rdoc_options = ["--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{germinate}
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{Germinate is a tool for writing about code}
+  s.test_files = ["test/test_germinate.rb"]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<ick>, ["~> 0.3.0"])
+      s.add_runtime_dependency(%q<fattr>, ["~> 1.0.3"])
+      s.add_runtime_dependency(%q<arrayfields>, ["~> 4.7.3"])
+      s.add_runtime_dependency(%q<orderedhash>, ["~> 0.0.6"])
+      s.add_runtime_dependency(%q<alter-ego>, ["~> 1.0.0"])
+      s.add_runtime_dependency(%q<main>, ["~> 2.8.3"])
+      s.add_development_dependency(%q<bones>, [">= 2.5.1"])
+    else
+      s.add_dependency(%q<ick>, ["~> 0.3.0"])
+      s.add_dependency(%q<fattr>, ["~> 1.0.3"])
+      s.add_dependency(%q<arrayfields>, ["~> 4.7.3"])
+      s.add_dependency(%q<orderedhash>, ["~> 0.0.6"])
+      s.add_dependency(%q<alter-ego>, ["~> 1.0.0"])
+      s.add_dependency(%q<main>, ["~> 2.8.3"])
+      s.add_dependency(%q<bones>, [">= 2.5.1"])
+    end
+  else
+    s.add_dependency(%q<ick>, ["~> 0.3.0"])
+    s.add_dependency(%q<fattr>, ["~> 1.0.3"])
+    s.add_dependency(%q<arrayfields>, ["~> 4.7.3"])
+    s.add_dependency(%q<orderedhash>, ["~> 0.0.6"])
+    s.add_dependency(%q<alter-ego>, ["~> 1.0.0"])
+    s.add_dependency(%q<main>, ["~> 2.8.3"])
+    s.add_dependency(%q<bones>, [">= 2.5.1"])
+  end
+end