RubyGems - bijou - Versions diffs - 0.1.0 - Mend

bijou 0.1.0

Files changed (53) hide show

data/ChangeLog.txt +4 -0
data/LICENSE.txt +58 -0
data/README.txt +48 -0
data/Rakefile +105 -0
data/doc/INSTALL.rdoc +260 -0
data/doc/README.rdoc +314 -0
data/doc/releases/bijou-0.1.0.rdoc +60 -0
data/examples/birthday/birthday.rb +34 -0
data/examples/holiday/holiday.rb +61 -0
data/examples/holiday/letterhead.txt +4 -0
data/examples/holiday/signature.txt +9 -0
data/examples/phishing/letter.txt +29 -0
data/examples/phishing/letterhead.txt +4 -0
data/examples/phishing/phishing.rb +21 -0
data/examples/phishing/signature.txt +9 -0
data/examples/profile/profile.rb +46 -0
data/lib/bijou.rb +15 -0
data/lib/bijou/backend.rb +542 -0
data/lib/bijou/cgi/adapter.rb +201 -0
data/lib/bijou/cgi/handler.rb +5 -0
data/lib/bijou/cgi/request.rb +37 -0
data/lib/bijou/common.rb +12 -0
data/lib/bijou/component.rb +108 -0
data/lib/bijou/config.rb +60 -0
data/lib/bijou/console/adapter.rb +167 -0
data/lib/bijou/console/handler.rb +4 -0
data/lib/bijou/console/request.rb +26 -0
data/lib/bijou/context.rb +431 -0
data/lib/bijou/diagnostics.rb +87 -0
data/lib/bijou/errorformatter.rb +322 -0
data/lib/bijou/exception.rb +39 -0
data/lib/bijou/filters.rb +107 -0
data/lib/bijou/httprequest.rb +108 -0
data/lib/bijou/httpresponse.rb +268 -0
data/lib/bijou/lexer.rb +513 -0
data/lib/bijou/minicgi.rb +159 -0
data/lib/bijou/parser.rb +1026 -0
data/lib/bijou/processor.rb +404 -0
data/lib/bijou/prstringio.rb +400 -0
data/lib/bijou/webrick/adapter.rb +174 -0
data/lib/bijou/webrick/handler.rb +32 -0
data/lib/bijou/webrick/request.rb +45 -0
data/script/cgi.rb +25 -0
data/script/console.rb +7 -0
data/script/server.rb +7 -0
data/test/t1.cfg +5 -0
data/test/tc_config.rb +26 -0
data/test/tc_filter.rb +25 -0
data/test/tc_lexer.rb +120 -0
data/test/tc_response.rb +103 -0
data/test/tc_ruby.rb +62 -0
data/test/tc_stack.rb +50 -0
metadata +121 -0

data/doc/README.rdoc ADDED Viewed

@@ -0,0 +1,314 @@
+= Bijou - A web page templating framework for Ruby
+== Introduction
+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.
+=== Example
+This example illustrates some of the similarities and differences between
+Bijou and Mason. We'll use the canonical example here.
+  <% planet = 'World' %>
+  Hello, <%= planet %>!
+This, of course, results in the following ouput:
+  Hello, world!
+The syntax of Bijou was kept very close to that of Mason. However, some
+differences do exist.
+=== Overview
+The most basic Bijou file is a text or HTML file. No special markup is
+required. When the file is first loaded, it will be compiled into a Ruby class
+that renders its output to an object compatible with the target web server.
+To include Ruby code, two special tag formats may be used: inline code
+segments and output tags.
+  <% total = subtotal * tax_rate
+     print format_currency(total)
+  %>
+  <%= format_currency(total) %>
+Code segments, which begin with <tt><%</tt>, may contain any Ruby code on
+one line or across several. To render output to the target HTML stream,
+either <tt>puts</tt>, <tt>print</tt>, or <tt>printf</tt> may be used.
+Output tags begin with <tt><%=</tt> and the result of their evaluation
+is rendered to the HTML stream automatically.
+== Structure
+There are basic three types of Bijou file, all derived from Bijou::Component.
+The following terms are used to clarify meaning in the documentation. There
+is very little difference between them in terms of syntax or operation.
+- Pages
+- Containers
+- Components
+A page is a stand-alone component, typically called directly by the web server.
+A container is used by a page to provide a common layout. And a component is
+a fragment that is used by other pages, containers, or components.
+Although all three types are based on the class Bijou::Component, the term
+component is usually used to refer to the specialized variety.
+=== Pages
+Each Bijou file may contain a mixture of HTML markup and Ruby code. When a
+document is requested by the web server, the server adapter invokes the
+Bijou processor and attempts to locate a corresponding Bijou file. The
+processor then interprets the file, execuing any Ruby code encountered
+along the way.
+  <html>
+    <head>
+      <title>Example</title>
+    </head>
+    <body>
+      <%= "Welcome to Bijou" %>
+    </body>
+  </html>
+This example is a stand-alone page that doesn't require any HTTP arguments.
+=== Arguments
+When a file is called by the web server, the get and post parameters are
+available via intrinsic objects on the component. Their union is available
+via the implicit <tt>args</tt> parameter, which is a hash. In addition, a
+top-level <tt><%args></tt> block may be defined to automatically marshal
+the parameters so they are available as local variables, with or without
+default values. For example:
+  <%args>
+    argument1          # This parameter is required, as there is no specified default.
+    argument2 => ''    # If a value is not sent, this default will be used.
+    ...
+  </%args>
+Here, the <tt>argument1</tt> value may be accessed using:
+- <tt>argument1</tt> - The local variable declared using the <tt><%args></tt> block
+- <tt>args[:argument1]</tt> - The implicit args hash parameter
+- <tt>request.params[:argument1]</tt> - The intrinsic request object
+A file may be a stand-alone module, which is invoked by the web server.
+It may also be a component or a container. Components and containers have
+the same syntax as normal modules, but they serve different purposes.
+=== Components
+A component is a specialized Bijou file that is intended to be called by pages,
+containers, and other components. It has the same markup and code syntax as a
+stand-alone file. The primary difference is that the top-level <tt><%args></tt>
+block does not specify HTTP parameters. Instead, it defines arguments that are
+passed by the caller to the component via the component call, which uses the
+the syntax
+<tt><& <em>component</em> [<em>, argument1 => value1, argument2 => value2, ...</em>] &></tt>.
+=== Containers
+Containers allow users to build re-usable templates, sometimes called layouts.
+The container represents the 'outer' text and the 'inner' text is generated
+by the associated page or content component.
+Containers are like normal components. The only difference is that they
+must contain a special call tag, <tt><& content &></tt>, which is where
+the caller's output is placed during the rendering process. A component
+references a container using the <tt>container</tt> directive.
+For example, a page might start with the following directive. (Directives
+are usually placed at the top.)
+  <%! container="../layouts/frontpage.rbb" %>
+  <h1>Introduction</h1>
+  ...
+This directive would instruct the Bijou processor to load the front page
+container as the 'outer' markup, substituting this page's content
+(starting with <tt><h1>...</tt>) at the location of the container's
+<tt><& content &></tt> tag. A simplified container might look like this
+  <html>
+    <head>
+      <title>Welcome</title>
+    </head>
+    <body>
+      <& content &>
+    </body>
+  </html>
+Containers may contain methods and code just like normal components.
+In addition to pages, containers and components may also specify
+associated containers. In this way, containers may be chained together,
+allowing for an arbitrary level of complexity.
+== Syntax
+A Bijou file contains normal text or HTML mixed with special markup. This
+markup has a syntax similar to HTML, but it is designed to integrate Ruby
+code in a way that supports the generation of dynamic content.
+=== Inline code
+*Syntax*: <% <b>...</b> %>
+Executes any Ruby code that is placed between the delimiters.
+=== Inline output
+*Syntax*: <%= <em>expression</em> %>
+Evalues the expression and prints the result.
+=== Method or Component Call
+*Syntax*: <& <em>name</em> [<em>, argument1 => value1, argument2 => value2, ...</em>] &>
+Calls the named method or component and displays the output.
+Example:
+  <& copyright, name => 'Transgalactic Enterprises, Inc.', year => 2187 &>
+This would call the method <tt><%method copyright></tt> or a component having
+that filename, passing the specified arguments. The output of the method or
+component call would be rendered in place of the call tag.
+=== Indirect Method or Component Call
+*Syntax*: <&= <em>method</em> [<em>, argument1 => value1, argument2 => value2, ...</em>] &>
+This syntax can be used to dynamically select which component or method to
+call. The named method or component is first invoked without rendering the
+result. Instead, the return value (assumed to be a string), is used to locate a
+component or method, which is then invoked normally.
+=== Directive
+*Syntax*: <%! [<em>name1 => value1, name2 => value2, ...</em>] %>
+Directives are used to control various aspects of page generation and
+evaluation. Examples include, <tt>container</tt>, <tt>base</tt>, and
+<tt>include</tt>.
+=== Method
+*Syntax*: <%method <em>name</em>> <b>...</b> </%method>
+Methods may contain arbitrary markup, like the main section of a Bijou file.
+Once a method has been defined, it may then be invoked by name, with or
+without arguments, from the main section or from within other methods.
+In addition, methods defined in a container may be overridden in a content
+component. For example, a container could define a method called <tt>title</tt>
+and call it like this.
+  <html>
+    <head>
+      <title><& title &></title>
+  ...
+    <& content &>
+  ...
+  <%method title>
+    Welcome to Transgalactic Enterprises
+  </%method>
+This has the effect of providing a default title, but one that can be
+overridden by any calling content component. The component would simply
+define its own <tt>title</tt> method, and that method would then override
+the default method provided by the container.
+==== Digression
+This is a powerful construct that was shamelessly poached from HTML::Mason.
+The design of Bijou attempts to address some of the issues of initialization
+order present in Mason. In particular, the <tt><%init></tt> section is called
+for all related (that is, existing in the same content/container chain)
+components prior to invoking any such methods. This allows values to be
+sourced from, for example, a database connection in the content component,
+and to have such values be useable from the container. This is not possible
+when using autohandlers in Mason, unless values are sourced from a
+<tt><%shared></tt> section. Unfortunately, there is no <tt><%cleanup></tt>
+equivalent for <tt><%shared></tt> sections in Mason.
+=== Initializer
+*Syntax*: <%init> <b>...</b> </%init>
+The initializer is a special method that gets invoked prior to the render
+phase. Its content is evaluated as normal Ruby code. All initializers in
+a content/container chain are invoked prior to the content render phase.
+Any subordinate components (and any associated containers) called from
+within the content section will have their initializers called at that time.
+The args passed to the init section are the same as those for the main body.
+Thus, to access a value from the args hash as a local variable or to provide
+a default, an <tt><%args></tt> section must be specified. Any such declarations
+cause a locally scoped variable having the specified name to be available both
+in the init section and to the main body. Because these are implemented as
+separate methods internally, they are separate variables. This implies that
+any changes made to them in the init section might not be reflected in the
+main body.
+This discrepancy may or may not be seen as a benefit. It is one of the
+outstanding issues left to be resolved. <b>NOTE: This behavior may change
+in the future.</b> If a parameter's value is modified and the state needs
+to be persisted for the render, just use a member variable to hold the value.
+Note that an initializer is not the same a a Ruby constructor
+(<tt>def initialze</tt>). A component's initialize method may be called at
+any time, but the initializer will be called in a specific order, with the
+expected arguments.
+=== Finalizer
+*Syntax*: <%fini> <b>...</b> </%fini>
+The finalizer is a special method that gets invoked after the render phase.
+Its content is evaluated as normal Ruby code. It is useful for freeing
+resources, such as database handles.
+=== Argument Block
+*Syntax*: <%args> <b>...</b> </%args>
+Argument blocks may be declared within methods or at the top level. They
+have the following form.
+  <%args>
+    argument1 [ => value1 ] # comment
+    argument2 [ => value2 ]
+    ...
+  </%args>
+The optional value, if specified, defines a default value that will be
+assigned to the argument if one is not passed by the caller. If no value
+is specified, then that argument is expected and will raise an exception
+if it is not present in a caller's argument list. The value may contain
+any single-line expression that is valid within the scope of the method.
+=== Code lines
+We are considering <tt>%</tt> code lines as alternative to <tt><%</tt> code
+blocks. This format, which is used by Mason, allows the user to define a
+single-line section of code by prefixing it with a <tt>%</tt> token. The
+token must appear in the first column of text. This format is conceptually
+similar to single-line comments.
+== Author
+Author::   Todd Lucas <tl@dogandponyshow.org>
+Requires:: Ruby 1.8.4 or later
+License::  Copyright (c) 2007-2008 Todd Lucas.
+           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/doc/releases/bijou-0.1.0.rdoc ADDED Viewed

@@ -0,0 +1,60 @@
+= Bijou 0.1.0 Released
+== Changes
+Version 0.1.0 is an initial alpha release. It is a demonstration of the basic
+functionality of all core features, using simple interfaces: cgi, WEBrick, and
+the standard I/O console.
+* Initial alpha release, version 0.1.0
+=== Roadmap
+* One of the first goals after the initial release is to add support for
+  one or more performant web servers. This means something like FastCGI,
+  SCGI, Mongrel, and/or Thin.
+* Another consideration is replacing the hand-coded parser. The most
+  likely candidate is ANTLR with a Ruby target.
+* Support for plugins. Much of this is TBD based on how people begin using
+  Bijou. One of the first targets will be filters. Filters are built-in
+  currently.
+* Support code lines with a '%' prefix in the first column (a la Mason), as
+  an alternative to '<%' inline code segments. This format allows the user
+  to define a single-line section of code by prefixing it with a <tt>%</tt>
+  token. The token must appear in the first column of text. This format is
+  conceptually similar to single-line comments.
+=== Feedback
+This initial release is intended for people to be able to test the waters.
+Although I'm happy with the initial state of the project, there are some
+things that will probably change. As such, this is not a production release
+and the next release is likely to introduce breaking changes--though I
+expect them to be minor.
+Feedback is welcome on the project forum or via email, as are bug reports.
+== What is Bijou?
+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.
+== Availability
+You may install as a Ruby Gem using the following command
+  gem install bijou
+or from the RubyForge pages
+Home Page:: http://bijou.rubyforge.org
+Download::  http://rubyforge.org/project/showfiles.php?group_id=4980

data/examples/birthday/birthday.rb ADDED Viewed

@@ -0,0 +1,34 @@
+$:.push '../../lib'
+require 'bijou'
+parser = Bijou::Parser.new
+class_name = "BirthdayView"
+class_text = parser.parse(class_name, <<EOS)
+<%args>
+    name => 'to whom it may concern'
+</%args>
+Dear <%= name %>,
+I\'m writing this letter today to send my best wishes for a happy birthday.
+Sincerely,
+Your boss
+---- cut here ----
+EOS
+people = [ 'David', 'Tiffany', 'Richard' ]
+people.each { |who|
+  args = { 'name' => who }
+  context = Bijou::Context.new(Bijou::Config.new)
+  letter = Bijou::Processor.execute(context, class_text, class_name, args)
+  print letter
+}

data/examples/holiday/holiday.rb ADDED Viewed

@@ -0,0 +1,61 @@
+$:.push '../../lib'
+require 'bijou'
+parser = Bijou::Parser.new
+class_name = "HolidayView"
+class_text = parser.parse(class_name, <<EOS)
+<%! container='letterhead.txt' %>
+<%args>
+    name => 'to whom it may concern'
+</%args>
+Dear <%= name %>,
+In this holiday season, I\'d like to extend my personal best to you and yours.
+<& signature.txt, signed => 'Your boss' &>
+---- cut here ----
+EOS
+def container_callback(context, path)
+  parser = Bijou::Parser.new
+  class_name = 'LetterView'
+  class_text = ''
+  File.open(path) do |file|
+    class_text = parser.parse(class_name, file, path)
+  end
+  Bijou::Processor.create_component(context, class_text, class_name)
+end
+def component_callback(context, path, args)
+  parser = Bijou::Parser.new
+  class_name = 'SignatureView'
+  class_text = ''
+  File.open(path) do |file|
+    class_text = parser.parse(class_name, file, path)
+  end
+  Bijou::Processor.execute(context, class_text, class_name, args)
+end
+people = [ 'David', 'Tiffany', 'Richard' ]
+people.each { |who|
+  args = { 'name' => who }
+  context = Bijou::Context.new(Bijou::Config.new)
+  context.container_callback = method(:container_callback)
+  context.component_callback = method(:component_callback)
+  print Bijou::Processor.execute(context, class_text, class_name, args)
+}