bijou 0.1.0

data/ChangeLog.txt

@@ -0,0 +1,4 @@
+
+2008-13-01  Todd Lucas <tl@dogandponyshow.org>
+
+ * Initial release, version 0.1.0

data/LICENSE.txt

@@ -0,0 +1,58 @@
+Ruby is copyrighted free software by Yukihiro Matsumoto <matz@netlab.co.jp>.
+You can redistribute it and/or modify it under either the terms of the GPL
+(see COPYING.txt file), or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+	  modifications to Usenet or an equivalent medium, or by allowing
+	  the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) rename any non-standard executables so the names do not conflict
+	  with standard executables, which must also be provided.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or executable
+     form, provided that you do at least ONE of the following:
+
+       a) distribute the executables and library files of the software,
+	  together with instructions (in the manual page or equivalent)
+	  on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+	  the software.
+
+       c) give non-standard executables non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  But some files in the distribution
+     are not written by the author, so that they are not under this terms.
+
+     They are gc.c(partly), utils.c(partly), regex.[ch], st.[ch] and some
+     files under the ./missing directory.  See each file for the copying
+     condition.
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.
+

data/README.txt

@@ -0,0 +1,48 @@
+
+README.txt
+
+Bijou is a templating system for Ruby. It was inspired by Perl's HTML::Mason. 
+Bijou files are text or HTML files that support in-line Ruby. Bijou also 
+supports the inclusion of text and code from other sources, called methods 
+and components. Components may be shared between files. They may also be used 
+as containers (sometimes called templates or layouts in other environments). 
+By chaining together components and containers, an arbitrarily sophisticated 
+system may be developed.
+
+The Bijou home page is at
+
+    http://bijou.rubyforge.org/
+
+The source code, Ruby Gem, etc. is available here
+
+    https://rubyforge.org/frs/?group_id=4980
+
+The directory structure is as follows
+
+    lib/
+        Contains the Ruby source code for Bijou.
+
+    doc/
+        Contains the reference documentation in HTML format, courtesy of
+        RDoc. To get started, open doc/rdoc/index.html and go from there.
+
+    tests/
+        A basic suite of unit tests.
+
+    examples/
+        Several examples of how to use Bijou. Some of these are stand-alone
+        and do not require a web server.
+
+Contact
+
+    Todd Lucas <tl@dogandponyshow.org>
+
+License
+
+    Released under the same license as Ruby.
+
+Warranty
+
+    This software is provided "as is" and without any express or implied 
+    warranties, including, without limitation, the implied warranties of 
+    merchantibility and fitness for a particular purpose.

data/Rakefile

@@ -0,0 +1,105 @@
+# -*- ruby -*-
+#
+# Copyright (c) 2007-2008 by Todd Lucas
+#
+# Rakefile for Bijou
+#
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/contrib/sshpublisher'
+
+PKG_VERSION = "0.1.0"
+
+desc "Default Task"
+task :default => [ :clean, :test, :package ]
+
+CLEAN.include('pkg', 'examples/**/*.obj')
+
+# Run the unit tests
+Rake::TestTask.new { |t|
+  t.libs << "test"
+  t.pattern = 'test/tc_*.rb'
+  t.verbose = true
+  t.warning = false
+}
+
+PKG_FILES = FileList[
+  'Rakefile',
+  'README.txt',
+  'LICENSE.txt',
+  'ChangeLog.txt',
+  'doc/*',
+  'doc/releases/*',
+  'lib/**/*',
+  'examples/**/*',
+  'script/*.rb',
+  'test/*'
+]
+
+#------ Gem ----------------------------------------------------------
+
+spec = Gem::Specification.new do |s| 
+  s.name = "bijou"
+  s.version = PKG_VERSION
+  s.author = "Todd Lucas"
+  s.email = "tl@dogandponyshow.org"
+  s.homepage = "http://bijou.rubyforge.org/"
+  s.platform = Gem::Platform::RUBY
+  s.summary = "Bijou is a web templating system for Ruby."
+  s.description = <<EOS
+Bijou is a web templating system in the style of Perl\'s HTML::Mason project.
+It is a flexible system that allows HTML to be mixed with Ruby code, and to
+allow page fragments to be shared and combined in a number of ways. It is 
+written in pure Ruby with minimal dependencies and is designed to be run in
+a number of configurations, including as a CGI script, using the lightweight 
+WEBrick server, or stand-alone via the stdio console.
+EOS
+  s.files = PKG_FILES.to_a
+  s.require_path = "lib"  # make the default explicit
+
+  s.test_files = FileList["test/tc_*.rb"]
+
+  s.required_ruby_version = '>= 1.8.4'
+  s.rubyforge_project = 'bijou'
+
+  # NOTE: Only applies to Gems
+  # s.add_dependency('digest/sha1')
+
+  s.has_rdoc = true  # Advisory
+
+  # We must duplicate rdoc directives here because this controls how the RDoc
+  # gets built during Gem installation (distinct from rake rdoc task).
+  s.rdoc_options << '--main' << 'lib/bijou.rb'
+  s.rdoc_options << "--inline-source" << "--line-numbers"
+end
+
+# Rake task to build the package 
+Rake::GemPackageTask.new(spec) do |pkg| 
+  pkg.need_tar = true
+  pkg.need_zip = true
+end
+      
+#------ RDoc Documentation -------------------------------------------
+
+desc "Generate rdoc documentation"
+Rake::RDocTask.new("rdoc") do |rdoc|
+  rdoc.rdoc_dir = 'doc/rdoc'
+  rdoc.title    = "Bijou - Web templates for Ruby"
+
+  # Make the readme file the start page for the generated html
+  rdoc.options << '--main' << 'doc/README.rdoc'
+
+  # Show source inline with line numbers
+  rdoc.options << "--inline-source" << "--line-numbers"
+
+  rdoc.template = "#{ENV['template']}.rb" if ENV['template']
+
+  rdoc.rdoc_files.include('doc/*.rdoc',
+                          'lib/**/*.rb',
+                          'doc/releases/*.rdoc')
+  rdoc.rdoc_files.exclude(/\btest\b/)
+end

data/doc/INSTALL.rdoc

@@ -0,0 +1,260 @@
+= Bijou - Installation instructions
+
+== Overview
+
+This first release of Bijou is intended as a technology demonstration (i.e.,
+alpha). For this reason, it only supports basic web server configurations.
+
+CGI script:: tested with Apache
+WEBrick:: for running a light-weight, stand-alone server
+Standard I/O console:: primarily for testing and debugging
+
+This guide will show you how to run under these configurations, so that you
+can give Bijou a try. If you like it and would like to see continued 
+development, please register your interest by commenting in the project
+forums[https://rubyforge.org/forum/?group_id=4980]  at rubyforge or by 
+sending email.
+
+We hope to add to the supported list of web servers and environments soon. 
+In particular, a FastCGI or SCGI handler, as well as Mongrel support.
+
+=== Install
+
+First, install the gem file. On *nix machines, you'll need root, so running
+
+  sudo gem install bijou
+
+should suffice. On other platforms, such as Windows, you can just run
+
+  gem install bijou
+
+This will download the gem from rubyforge and install it. If you're installing
+from a local gem file, you must specify the filename itself.
+
+  [sudo] gem install bijou-0.1.0.gem
+
+=== Uninstall
+
+To uninstall the gem, just run
+
+  [sudo] gem uninstall bijou
+
+regardless of whether you installed from rubyforge or from a local file.
+
+== Setup
+
+All of the simple entry points to the Bijou processor are provided in the 
+<tt>scripts</tt> subdirectory of the package.
+
+The package location will depend on the platform used and how it was installed.
+On a *nix system, if the package were installed as root, the path would be 
+similar to
+
+  /usr/local/lib/ruby/gems/1.8
+
+On Windows, it would be similar to
+
+  C:\Program Files\Ruby\lib\ruby\gems\1.8\gems\bijou-0.1.0\script
+
+or
+
+  C:\ruby\lib\ruby\gems\1.8\gems\bijou-0.1.0\script
+
+The three files we'll be dealing with are
+
+- console.rb
+- server.rb
+- cgi.rb
+
+=== Console
+
+First, go to the scripts subdirectory under the installation directory. 
+From the command line, run
+
+  ruby console.rb [flags] <filename>
+
+This will invoke the Bijou processor as if it were a web server serving up the
+page specified by <tt>filename</tt>. To pass query string arguments, use the 
+-q or --query flag.
+
+  ruby console.rb --query "user=bill&pass=twinkies" login.rbb
+
+The file extension is unimportant in this case. It becomes more important when 
+running CGI under Apache.
+
+The results are rendered to standard out, so it might be a little 
+disappointing--especially if you've constructed a complex page with HTML. 
+We suggest using plain text and simple pages when testing via the console.
+
+This can be especially helpful if you get an Internal Server Error later on
+when running under Apache. Apache is very sensitive to extraneous output while
+HTTP headers are being generated (as it should be). This is a first version,
+and there are still cases where an exception will be triggered that will
+result in text choking the Apache header parser. Running your page at
+the console will give you a better idea of what caused the error.
+
+Also, if you see such an error, please post a bug to the rubyforge project 
+tracker--preferably with a reproduction case (like a simple Bijou page that
+demonstrates the problem). That way it'll be more likely to be fixed in the 
+next release.
+
+Note: the console.rb file can be copied to another directory, such as the
+location of your web project, and be run from there. This can be handy for 
+customizing the script to suit your needs.
+
+=== WEBrick
+
+This is a nice little server that can be used to get a real taste of writing 
+web pages using Bijou, without the hassle of setting up Apache. WEBrick is 
+very straightforward to use, at the cost of some missing features. In 
+particular, you cannot POST forms using WEBrick. So any test pages you 
+have containing forms should specifiy:
+
+  <form method="GET">...
+
+This will pass the form parameters via the query-string channel and will 
+be good enough to get you started.
+
+To run WEBrick, just go to to the bijou <tt>scripts</tt> directory and type
+
+  ruby server.rb
+
+This will run WEBrick at the default port location of 2000. By default, the
+WEBrick server assumes that the current directory is the web server's root 
+directory. To change that, you may set the environment variable DOCUMENT_ROOT
+to an absolute path prior to calling WEBbrick. 
+
+You may also specify a config file by setting the environment variable
+BIJOU_CONFIG to point to a config file (e.g., www.cfg), that conforms to the
+Bijou config file format (see the Configuration section).
+
+Note: currently, the only extensions recognized as Bijou files are (.rbb, .htm,
+and .html). A feature for a future release is a matching regex that may be 
+specified via the config file. This limitation is specific to WEBrick since
+Apache has a built-in mechanism for handling file types.
+
+To test, let's assume you have a file in the current directory called 
+<tt>hello.rbb</tt>. To access this file, go to your browser and type the URL:
+
+ http://localhost:2000/hello.rbb
+
+You should see the result in your browser.
+
+=== CGI
+
+The CGI handler should be able to be run under any web server that supports
+CGI. To date, it has only been tested under Apache (and only version 2.2, at
+that).
+
+==== Apache
+
+First, the <tt>cgi.rb</tt> file in the <tt>scripts</tt> directory should 
+be copied to the CGI directory, specified in the Apache <tt>http.conf</tt> file,
+and given an appropriate name. For example, <tt>bijoucgi.rb</tt> or 
+<tt>bijou.cgi</tt>.
+
+The cgi-bin directory may be defined by <tt>ScriptAlias</tt> (part of 
+mod_alias). For example, on Windows:
+
+  ScriptAlias /cgi-bin/ "C:/Program Files/Apache Software Foundation/Apache2.2/cgi-bin/"
+
+In this case, copy <tt>cgi.rb</tt> to this directory. If Bijou has been 
+installed, <tt>cgi.rb</tt> will be able to invoke the Bijou CGI handler.
+
+After copying the file, be sure to update the <tt>#!</tt> line at the top of 
+the file to refer to the installed Ruby path. Apache requires this directive--
+even on systems, such as Windows, which have shells that do not recognize it.
+
+Finally, Apache will need to be configured. This requires editing the 
+configuration file, typically called <tt>http.conf</tt>. The following is an 
+example VirtualHost section, showing Windows file paths.
+
+  <VirtualHost *:80>
+    ServerName localhost
+    ServerAdmin webmaster@example.com
+    DocumentRoot "C:/projects/mysite/www"
+
+    SetEnv BIJOU_CACHE "C:/projects/mysite/www_cache"
+    SetEnv BIJOU_CONFIG "C:/projects/mysite/www.cfg"
+
+    Action bijou-cgi /cgi-bin/bijoucgi.rb
+
+    <LocationMatch "\.(rbb|html|htm|xml)$">
+      Options +ExecCGI
+    </LocationMatch>
+
+    DirectoryIndex "index.html"
+
+    <Directory "C:/projects/mysite/www">
+      AddHandler bijou-cgi .htm .html .rbb .xml
+      Options Includes FollowSymLinks
+      AllowOverride None
+      Order allow,deny
+      Allow from all
+    </Directory>
+ </VirtualHost>
+
+There are many different ways to set up your Apache config file. This example
+contains the key options for running Bijou. Namely:
+
+  DocumentRoot "C:/projects/mysite/www"
+
+  SetEnv BIJOU_CACHE "C:/projects/mysite/www_cache"
+  SetEnv BIJOU_CONFIG "C:/projects/mysite/www.cfg"
+
+  Action bijou-cgi /cgi-bin/bijoucgi.rb
+
+  AddHandler bijou-cgi .htm .html .rbb .xml
+
+This results in the expected environment variables being set and the 
+<tt>bijoucgi.rb</tt> file being called when particular file types are 
+requested.
+
+Two final points remain. First, Apache requires the action handler to support 
+the <tt>Action</tt> directive:
+
+  LoadModule actions_module modules/mod_actions.so
+
+Second, Apache support for CGI requires the cgi module, which is usually 
+enabled:
+
+  LoadModule cgi_module modules/mod_cgi.so
+
+If you have any problems or suggestions, please let us know in the 
+Bijou Forums[https://rubyforge.org/forum/?group_id=4980].
+
+--
+==== .htaccess
+
+TBD
+++
+
+== Reference
+
+=== Configuration
+
+A configuration file can be specified to control how Bijou operates. This file
+is usually specified via the environment variable BIJOU_CONFIG. If the variable
+is defined, the server adapter will load the file at that location and use it 
+to tailor the operation of the Bijou processor and runtime environment.
+
+[<b>@document_root</b>] String - The location to search when loading a requested file. This should be an absolute path to the top-level directory containing your web pages.
+
+[<b>@cache_root</b>] String - The name of a directory to use as a cache for parsed Bijou files. This is often <web-directory>_cache (e.g., www_cache) located parallel to the web directory.
+
+[<b>@cache_ext</b>] String - If the cache files are to be located in the same directory as the source files, an extension must be specified. For example, ".obj" would cause the cached file for index.rbb to be named index.rbb.obj.
+
+[<b>@includes</b>] String - An array containing any additional paths to include during the request. This can simplify <tt>require</tt> calls. Absolute paths are recommended. For example <tt>@includes=['/home/me/proj/app', '/home/me/proj/lib']</tt>.
+
+[<b>@component_base</b>] String - The class to use for the base of all components. By default, this is <tt>Bijou::Component</tt>. However, if you derive a customized class from <tt>Bijou::Component</tt> and you would like to use it everywhere, it may be specified here as a string. To use a different base on a case-by-case basis, use the base directive (e.g., <%! base="MyComponent" %>).
+
+[<b>@require_list</b>] Array - Like the @includes parameter, this is an array. Any requires that should be automatically included in the generated component files. This is particularly useful if a customized base is being used. For example, to use <tt>MyComponent</tt> as the default base (which should derive from <tt>Bijou::Component</tt>), the path to this file should be included here.
+
+[<b>@cache</b>] Boolean - The cache value is true by default. To disable caching, set it to false. Caching should normally be used to avoid parsing components on every request. When caching is enabled, if a component is modified, the processor will parse the file and update the cache. This is primarily useful when hacking on the framework.
+
+[<b>@debug</b>] Boolean - Can be used to add diagnostics
+
+[<b>@trace_level</b>] Bijou::Log or integer - A number from 0 - 3 or a constant to indicate the trace level. By default it is 0 (or Bijou::Log::None), which disables tracing.
+
+[<b>@trace_buffer</b>] Boolean - Causes trace output to be buffered instead of beging rendered inline. Rendering inline is discouraged because it can cause output to precede the HTTP headers, yielding, for example, an internal server error on Apache. True by default.
+