RubyGems - bijou - Versions diffs - 0.1.0 - Mend

bijou 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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)
+}