rweb 0.1.0

data/Rakefile

@@ -0,0 +1,249 @@
+# Rakefile
+require "rake/testtask"
+require "rake/clean"
+require "rake/rdoctask"
+require "rake/gempackagetask"
+#---
+# The name of your project
+PROJECT = "RWEB"
+
+# Your name, used in packaging.
+MY_NAME = "Michael T. Richter"
+
+# Your email address, used in packaging.
+MY_EMAIL = "ttmrichter@gmail.com"
+
+# Short summary of your project, used in packaging.
+PROJECT_SUMMARY = "Self-executing WEB-like literate programming for Ruby."
+
+# The project's package name (as opposed to its display name). Used for
+# RubyForge connectivity and packaging.
+UNIX_NAME = "rweb"
+
+# Your RubyForge user name.
+RUBYFORGE_USER = ENV["RUBYFORGE_USER"] || "mtr1966"
+
+# Directory on RubyForge where your website's files should be uploaded.
+WEBSITE_DIR = "rweb"
+
+# Output directory for the rdoc html files.
+# If you don't have a custom homepage, and want to use the RDoc
+# index.html as homepage, just set it to WEBSITE_DIR.
+RDOC_HTML_DIR = "#{WEBSITE_DIR}/rdoc"
+#---
+# Variable settings for extension support.
+EXT_DIR = "ext"
+HAVE_EXT = File.directory?(EXT_DIR)
+EXTCONF_FILES = FileList["#{EXT_DIR}/**/extconf.rb"]
+EXT_SOURCES = FileList["#{EXT_DIR}/**/*.{c,h}"]
+# Eventually add other files from EXT_DIR, like "MANIFEST"
+EXT_DIST_FILES = EXT_SOURCES + EXTCONF_FILES
+#---
+REQUIRE_PATHS = ["lib"]
+REQUIRE_PATHS << EXT_DIR if HAVE_EXT
+$LOAD_PATH.concat(REQUIRE_PATHS)
+# This library file defines the MyProject::VERSION constant.
+require "#{UNIX_NAME}"
+PROJECT_VERSION = eval("#{PROJECT}::VERSION") # e.g. "1.0.2"
+#---
+# Clobber object files and Makefiles generated by extconf.rb.
+CLOBBER.include("#{EXT_DIR}/**/*.{so,dll,o}", "#{EXT_DIR}/**/Makefile")
+# Clobber .config generated by setup.rb.
+CLOBBER.include(".config")
+#---
+# Options common to RDocTask AND Gem::Specification.
+#   The --main argument specifies which file appears on the index.html page
+GENERAL_RDOC_OPTS = {
+  "--title" => "#{PROJECT} API documentation",
+  "--main" => "README.rdoc"
+}
+
+# Additional RDoc formatted files, besides the Ruby source files.
+RDOC_FILES = FileList["README.rdoc", "Changes.rdoc", "TODO.rdoc"]
+# Remove the following line if you don't want to extract RDoc from
+# the extension C sources.
+RDOC_FILES.include(EXT_SOURCES)
+
+# Ruby library code.
+LIB_FILES = FileList["lib/**/*.rb"]
+
+# Filelist with Test::Unit test cases.
+TEST_FILES = FileList["tests/**/tc_*.rb"]
+
+# Executable scripts, all non-garbage files under bin/.
+BIN_FILES = FileList["bin/*"]
+
+# This filelist is used to create source packages.
+# Include all Ruby and RDoc files.
+DIST_FILES = FileList["**/*.rb", "**/*.rdoc"]
+DIST_FILES.include("Rakefile", "COPYING")
+DIST_FILES.include(BIN_FILES)
+DIST_FILES.include("data/**/*", "test/data/**/*")
+DIST_FILES.include("#{WEBSITE_DIR}/**/*.{html,css}", "man/*.[0-9]")
+# Don't package files which are autogenerated by RDocTask
+DIST_FILES.exclude(/^(\.\/)?#{RDOC_HTML_DIR}(\/|$)/)
+# Include extension source files.
+DIST_FILES.include(EXT_DIST_FILES)
+# Don't package temporary files, perhaps created by tests.
+DIST_FILES.exclude("**/temp_*", "**/*.tmp")
+# Don't get into recursion...
+DIST_FILES.exclude(/^(\.\/)?pkg(\/|$)/)
+# Don't bring in our DARCS tree.
+DIST_FILES.exclude(/^(\.\/)?_darcs(\/|$)/)
+# Include our documentation/sample files.
+DIST_FILES.include("docs/**/*")
+#---
+# Run the tests if rake is invoked without arguments.
+task "default" => ["test"]
+
+test_task_name = HAVE_EXT ? "run-tests" : "test"
+Rake::TestTask.new(test_task_name) do |t|
+  t.test_files = TEST_FILES
+  t.libs = REQUIRE_PATHS
+end
+#---
+# Set an environment variable with any configuration options you want to
+# be passed through to "setup.rb config".
+CONFIG_OPTS = ENV["CONFIG"]
+if HAVE_EXT
+  file_create ".config" do
+    ruby "setup.rb config #{CONFIG_OPTS}"
+  end
+  
+  desc "Configure and make extension. " +
+    "The CONFIG variable is passed to `setup.rb config'"
+  task "make-ext" => ".config" do
+    # The -q option suppresses messages from setup.rb.
+    ruby "setup.rb -q setup"
+  end
+  
+  desc "Run tests after making the extension."
+  task "test" do
+    Rake::Task["make-ext"].invoke
+    Rake::Task["run-tests"].invoke
+  end
+end
+#---
+# The "rdoc" task generates API documentation.
+Rake::RDocTask.new("rdoc") do |t|
+  t.rdoc_files = RDOC_FILES + LIB_FILES
+  t.title = GENERAL_RDOC_OPTS["--title"]
+  t.main = GENERAL_RDOC_OPTS["--main"]
+  t.rdoc_dir = RDOC_HTML_DIR
+end
+#---
+GEM_SPEC = Gem::Specification.new do |s|
+  s.name = UNIX_NAME
+  s.version = PROJECT_VERSION
+  s.summary = PROJECT_SUMMARY
+  s.rubyforge_project = UNIX_NAME
+  s.homepage = "http://#{UNIX_NAME}.rubyforge.org/"
+  s.author = MY_NAME
+  s.email = MY_EMAIL
+  s.files = DIST_FILES
+  s.test_files = TEST_FILES
+  s.executables = BIN_FILES.map { |fn| File.basename(fn) }
+  s.has_rdoc = true
+  s.extra_rdoc_files = RDOC_FILES
+  s.rdoc_options = GENERAL_RDOC_OPTS.to_a.flatten
+  if HAVE_EXT
+    s.extensions = EXTCONF_FILES
+    s.require_paths << EXT_DIR
+  end
+end
+
+# Now we can generate the package-related tasks.
+Rake::GemPackageTask.new(GEM_SPEC) do |pkg|
+  pkg.need_zip = true
+  pkg.need_tar = true
+end
+#---
+desc "Upload website to RubyForge. " +
+  "scp will prompt for your RubyForge password."
+task "publish-website" => ["rdoc"] do
+  rubyforge_path = "/var/www/gforge-projects/#{UNIX_NAME}/"
+  sh "scp -r #{WEBSITE_DIR}/* " +
+    "#{RUBYFORGE_USER}@rubyforge.org:#{rubyforge_path}",
+    :verbose => true
+end
+#---
+task "rubyforge-setup" do
+  unless File.exist?(File.join(ENV["HOME"], ".rubyforge"))
+    puts "rubyforge will ask you to edit its config.yml now."
+    puts "Please set the `username' and `password' entries"
+    puts "to your RubyForge username and RubyForge password!"
+    puts "Press ENTER to continue."
+    $stdin.gets
+    sh "rubyforge setup", :verbose => true
+  end
+end
+
+task "rubyforge-login" => ["rubyforge-setup"] do
+  # Note: We assume that username and password were set in
+  # rubyforge's config.yml.
+  sh "rubyforge login", :verbose => true
+end
+
+task "publish-packages" => ["package", "rubyforge-login"] do
+  # Upload packages under pkg/ to RubyForge
+  # This task makes some assumptions:
+  # * You have already created a package on the "Files" tab on the
+  #   RubyForge project page. See pkg_name variable below.
+  # * You made entries under package_ids and group_ids for this
+  #   project in rubyforge's config.yml.  If not, eventually read
+  #   "rubyforge --help" and then run "rubyforge setup".
+  pkg_name = ENV["PKG_NAME"] || UNIX_NAME
+  cmd = "rubyforge add_release #{UNIX_NAME} #{pkg_name} " +
+        "#{PROJECT_VERSION} #{UNIX_NAME}-#{PROJECT_VERSION}"
+  cd "pkg" do
+  sh(cmd + ".gem", :verbose => true)
+    sh(cmd + ".tgz", :verbose => true)
+    sh(cmd + ".zip", :verbose => true)
+  end
+end
+#---
+# The "prepare-release" task makes sure your tests run, and then generates
+# files for a new release.
+desc "Run tests, generate RDoc and create packages."
+task "prepare-release" => ["clobber"] do
+  puts "Preparing release of #{PROJECT} version #{VERSION}"
+  Rake::Task["test"].invoke
+  Rake::Task["rdoc"].invoke
+  Rake::Task["package"].invoke
+end
+
+# The "publish" task is the overarching task for the whole project. It
+# builds a release and then publishes it to RubyForge.
+desc "Publish new release of #{PROJECT}"
+task "publish" => ["prepare-release"] do
+  puts "Uploading documentation..."
+  Rake::Task["publish-website"].invoke
+  puts "Checking for rubyforge command..."
+  `rubyforge --help`
+  if $? == 0
+    puts "Uploading packages..."
+    Rake::Task["publish-packages"].invoke
+    puts "Release done!"
+  else
+    puts "Can't invoke rubyforge command."
+    puts "Either install rubyforge with 'gem install rubyforge'"
+    puts "and retry or upload the package files manually!"
+  end
+end
+=begin
+#---
+$ rake -T
+rake clean            # Remove any temporary products.
+rake clobber          # Remove any generated file.
+rake clobber_package  # Remove package products
+rake clobber_rdoc     # Remove rdoc products
+rake package          # Build all the packages
+rake prepare-release  # Run tests, generate RDoc and create packages.
+rake publish # Publish new release of MyProject
+rake publish-website  # Upload website to RubyForge. scp will prompt for your RubyForge password.
+rake rdoc             # Build the rdoc HTML Files
+rake repackage        # Force a rebuild of the package files
+rake rerdoc           # Force a rebuild of the RDOC files
+rake test             # Run tests for test
+#---
+=end

data/TODO.rdoc

@@ -0,0 +1,4 @@
+= TODO
+1. Supply formal unit tests.
+2. Provide XHTML weaving support.
+3. Design generic weaving framework.

data/bin/rtangle

@@ -0,0 +1,115 @@
+#! /usr/bin/ruby -w
+
+# RTANGLE -- External tangling tool for literate Ruby.
+# Copyright (C) 2007 Michael T. Richter <ttmrichter@gmail.com>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; Version 2, June 1991 (and no other).
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program (in the file COPYING); if not, write to the Free
+# Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307,
+# USA
+
+require 'rubygems'
+require 'rweb'
+
+eval RWEB.tangle(DATA)
+
+__END__
+{title => RTANGLE}
+
+This is a simple utility that acts as a wrapper around RWEB's tangle and,
+instead of executing the resulting code, either prints it to stdout or saves it
+to a given file. Note that RTangle is itself written in RWEB's executable format
+with the boilerplate before the __END__ statement and the actual program
+document afterwards.
+
+The mainline code is quite simple:
+
+<< {
+{<<global requires>>}
+
+{<<command line processing>>}
+
+{<<tangling>>}
+
+{<<main>>}
+}>>
+
+The only require we need to introduce is to require RWEB itself. This is not, of
+course, necessary if we execute the RWEB document directly. Since, however, it
+is highly likely that we may at some point wish to tangle the RTangle utility
+itself into a Ruby source file, we should, pro forma, require the library
+anyway.
+
+<< global requires {
+require 'rweb'
+}>>
+
+The tangling stage itself is a very simple function which takes any kind of IO
+object for input, tangles it, then places the resulting string into the output,
+itself an IO object of any kind. It also doesn't care in the slightest exactly
+what kind of IO object is being used, thus suited to application as a filter in
+a potentially longer chain of tools.
+
+<< tangling {
+def rtangle(io_in, io_out)
+  io_out << RWEB.tangle(io_in)
+end
+}>>
+
+As can be seen, the true heavy lifting is done inside of the RWEB module. This
+utility is a hyper-simple shell around it by comparison.
+
+The mainline function is pretty simple as well. It just takes the arguments from
+the command line and passes them to the command line processor blindly,
+accepting in return a pair of IO objects -- one for input, the other for output.
+It then calls tangle with these objects, wrapping in a begin/ensure clause to
+make sure the IO objects are closed before exiting. The only additional step it
+takes is a call to the function find_block_begin which shadows the IO object
+used for input and silently sweeps away the stuff before __END__ in a document
+if it exists in the first 20 lines.
+
+<< main {
+io_in, io_out = process_argv ARGV
+begin
+  rtangle(io_in, io_out)
+ensure
+  io_in.close
+  io_out.close
+end
+}>>
+
+All that's left is the command line processor.
+
+<< command line processing {
+def process_argv args
+  io_in = STDIN
+  io_out = STDOUT
+  if args.length > 2
+    {<<display usage>>}
+  end
+  arg = args.shift
+  io_in = File.open(arg, "r") if arg
+  arg = args.shift
+  io_out = File.open(arg, "w") if arg
+  return io_in, io_out
+end
+}>>
+
+The usage message is straightforward and broken out only to reduce code clutter.
+
+<< display usage {
+puts "Incorrect command line."
+puts "Usage:"
+puts "  rtangle [input_file [output_file]]"
+puts
+puts "Files default to stdin and stdout respectively."
+}>>

data/bin/rweave

@@ -0,0 +1,115 @@
+#! /usr/bin/ruby -w
+
+# RWEAVE -- External weaving tool for literate Ruby.
+# Copyright (C) 2007 Michael T. Richter <ttmrichter@gmail.com>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; Version 2, June 1991 (and no other).
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program (in the file COPYING.txt); if not, write to the Free
+# Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307,
+# USA
+
+require 'rubygems'
+require 'rweb'
+
+eval RWEB.tangle(DATA)
+
+__END__
+{title => RWEAVE}
+
+This is a simple utility that acts as a wrapper around RWEB's weave and, instead
+of executing the resulting code, either prints it to stdout or saves it to a
+given file. Note that RWeave is itself written in RWEB's executable format with
+the boilerplate before the __END__ statement and the actual program document
+afterwards.
+
+The mainline code is quite simple:
+
+<< {
+{<<global requires>>}
+
+{<<command line processing>>}
+
+{<<weaving>>}
+
+{<<main>>}
+}>>
+
+The only require we need to introduce is to require RWEB itself. This is not, of
+course, necessary if we execute the RWEB document directly. Since, however, it
+is highly likely that we may at some point wish to weave the RWeave utility
+itself into a Ruby source file, we should, pro forma, require the library
+anyway.
+
+<< global requires {
+require 'rweb'
+}>>
+
+The weaving stage itself is a very simple function which takes any kind of IO
+object for input, weaves it, then places the resulting string into the output,
+itself an IO object of any kind. It also doesn't care in the slightest exactly
+what kind of IO object is being used, thus suited to application as a filter in
+a potentially longer chain of tools.
+
+<< weaving {
+def rweave(io_in, io_out)
+  io_out << RWEB.weave(io_in)
+end
+}>>
+
+As can be seen, the true heavy lifting is done inside of the RWEB module. This
+utility is a hyper-simple shell around it by comparison.
+
+The mainline function is pretty simple as well. It just takes the arguments from
+the command line and passes them to the command line processor blindly,
+accepting in return a pair of IO objects -- one for input, the other for output.
+It then calls weave with these objects, wrapping in a begin/ensure clause to
+make sure the IO objects are closed before exiting. The only additional step it
+takes is a call to the function find_block_begin which shadows the IO object
+used for input and silently sweeps away the stuff before __END__ in a document
+if it exists in the first 20 lines.
+
+<< main {
+io_in, io_out = process_argv ARGV
+begin
+  rweave(io_in, io_out)
+ensure
+  io_in.close
+  io_out.close
+end
+}>>
+
+All that's left is the command line processor.
+
+<< command line processing {
+def process_argv args
+  io_in = STDIN
+  io_out = STDOUT
+  if args.length > 2
+    {<<display usage>>}
+  end
+  arg = args.shift
+  io_in = File.open(arg, "r") if arg
+  arg = args.shift
+  io_out = File.open(arg, "w") if arg
+  return io_in, io_out
+end
+}>>
+
+The usage message is straightforward and broken out only to reduce code clutter.
+
+<< display usage {
+puts "Incorrect command line."
+puts "Usage:"
+puts "  rweave [input_file [output_file]]"
+puts
+puts "Files default to stdin and stdout respectively."
+}>>