clivecrous-ramaze 0.3.9.5

data/doc/INSTALL

@@ -0,0 +1,34 @@
+= Installating Ramaze
+
+* via RubyGems
+
+  The simplest way of installing Ramaze is via 
+
+    $ gem install ramaze
+
+  in case you have RubyGems installed.
+  (this will work as soon as I have registered on RubyForge ;)
+
+* via install.rb
+
+  Ramaze provides a basic install.rb that should take care of the installation
+  you can use it like 
+
+    $ ruby install.rb
+
+  you may need root-privileges to do
+  that, depending on what options you provide.
+  (please note that I haven't tested the install.rb extensively yet, so if you
+  find some quirks, please send me patches or a simple note)
+
+* via darcs
+
+  To get the latest and sweetest, you can just pull from the repository and run
+  Ramaze that way.
+
+    $ darcs get --partial http://manveru.mine.nu/ramaze
+
+  Please read the man page or `darcs help` for more information about updating
+  and creating your own patches.
+  This is at the moment the premier way to use Ramaze, since it is the way I use
+  it.

data/doc/LEGAL

@@ -0,0 +1,26 @@
+This is a list of files included into ramaze but under different licenses.
+Also included are files that are not under the copyright from Michael Fellinger.
+
+lib/ramaze/helper/pager.rb
+  License: BSD License
+  Author: George K. Moschovitis
+
+lib/ramaze/snippets/dictionary.rb
+  License: Ruby License
+  Authors: Jan Molic and Thomas Sawyer
+
+lib/proto/js/jquery.js
+  License: Dual licensed under MIT and GPL
+  Author: John Resig
+
+lib/ramaze/spec/helper/simple_http.rb
+  License: GPL
+  Author: Tim Becker
+
+lib/ramaze/template/xslt.rb
+  License: Ruby
+  Author: Stephan Maka
+
+lib/vendor/bacon.rb
+  License: MIT
+  Author: Christian Neukirchen

data/doc/ProjectInfo

@@ -0,0 +1,53 @@
+---
+project : ramaze
+version : '0.0.7'
+status  : alpha
+
+title    : Ramaze
+subtitle : A light and modular Web-Framework
+description : >
+  Ramaze is a very simple and straight-forward web-framework.
+  The philosophy of it could be expressed in a mix of KISS and POLS, trying to
+  make simple things simple and complex things possible.
+
+author     : Michael Fellinger <m.fellinger@gmail.com>
+created    : "2006-10-14"
+homepage   : "http://ramaze.rubyforge.org"
+download   : "https://rubyforge.org/frs/?group_id=3034"
+repository : "http://manveru.mine.nu/darcs/ramaze"
+slogan     : Ramaze, light and modular
+#signiture  : "../_privkey.pem"
+
+pack       : [gem, tgz, bz2]
+distribute : [ -scrap ]
+dependency :
+  - [ autorake, >= 0.5.1 ]
+executable : [ bin/ramaze ]
+
+#digest     : sha256
+#manifest   : MANIFEST.txt
+archive    : ~/ruby/ARCHIVE
+scm        : darcs
+scm_ignore : [ doc/allison ]
+changelog  : doc/CHANGELOG
+stamp      : doc/VERSION
+
+rdoc:
+  template : allison
+
+mail:
+  server   : smtp.gmail.com
+  account  : m.fellinger@gmail.com
+  mail_to  : m.fellinger@gmail.com
+
+rubyforge:
+  project  : ramaze
+  username : manveru
+  groupid  : 3034
+  package  : ramaze
+
+#host:
+#  domain   : rubyforge.org
+#  user     : transami
+#  root     : '/var/www/gforge-projects/ratchets'
+

data/doc/TODO

@@ -0,0 +1,29 @@
+This list is programmaticly generated by `rake todolist`
+If you want to add/remove items from the list, change them at the
+position specified in the list.
+
+/home/manveru/prog/projects/ramaze/lib/ramaze/template/ezamar/morpher.rb
+- Add pure Ruby implementation as a fall-back.
+
+/home/manveru/prog/projects/ramaze/lib/ramaze/helper/pager.rb
+  ++
+
+/home/manveru/prog/projects/ramaze/spec/ramaze/action/basics.rb
+
+/home/manveru/prog/projects/ramaze/lib/ramaze/template/ezamar/engine.rb
+- provide C version or maybe use erbuis
+
+/home/manveru/prog/projects/ramaze/lib/ramaze/template/xslt.rb
+  * Error handling
+  * Maybe prevent extFunction to be called by HTTP
+
+/home/manveru/prog/projects/ramaze/lib/ramaze/helper/identity.rb
+- maybe using StackHelper, but this is a really minimal overlap?
+
+/home/manveru/prog/projects/ramaze/spec/snippets/ramaze/caller_info.rb
+
+/home/manveru/prog/projects/ramaze/lib/ramaze/snippets/dictionary.rb
+  ++
+
+/home/manveru/prog/projects/ramaze/lib/ramaze/helper/redirect.rb
+- maybe some more options, like a delay

data/doc/meta/announcement.txt

@@ -0,0 +1,126 @@
+This time we are proud to announce Version 0.3.5 of Ramaze, the light and
+modular open source web framework.
+
+This release features a lot of work directly from our community and we are
+really greatful for everybody who helped in testing, patching and contributing
+exciting new features.
+
+Our extensive set of specs and docs now covers almost every detail of
+implementation and usage. Ramaze is under development by a growing community
+and in production use at companies.
+
+
+Home page:   http://ramaze.net
+Screencasts: http://ramaze.net/screencasts
+
+View source: http://source.ramaze.net
+Darcsweb:    http://darcs.ramaze.net
+
+IRC: #ramaze on irc.freenode.net
+
+
+Simple example:
+
+  require 'ramaze'
+
+  class MainController
+    def index
+      'Hello, World!'
+    end
+  end
+
+  Ramaze.start
+
+
+Special (alphabetic) thanks go to:
+
+  Aman 'tmm1' Gupta         - patches and support
+  Carlo Zottmann            - first patch!
+  Chris 'celldee' Duncan    - first patch!
+  Gabriele 'riffraff' Renzi - patches for file dispatcher
+  jeedee                    - new Ramaze logo
+  Jonathan 'Kashia' Buch    - patches and support
+  Keita Yamaguchi           - first patch!
+  Pistos                    - lots of friendly support
+  skaar                     - first patch!
+
+
+Selected summary of the 62 patches from 0.3.0 to 0.3.5:
+
+  Core
+    - Ramaze::Contrib::Route made available by default as Ramaze::Route
+      (backwards compatibility retained)
+    - Support added for ETag and If-Modified-Since in Dispatcher::File
+    - Adapter for LiteSpeed webserver added
+    - Added ability to set default session cookie options using Session::COOKIE
+    - Support added for Content-Language based localization and gettext
+
+  Templates
+    - Support added for passing in locals to render_template
+    - Added support for symbol argument to template_root
+    - render_template no longer requires template extensions
+    - Dots allowed in template extensions (template.html.erb)
+
+  Templating Engines
+    - Builder templating engine added to produce XML
+    - RedCloth templating engine added
+    - Amrita2 templating engine updated to latest release
+
+  Helpers
+    - Simple EmailHelper added
+    - IdentityHelper updated for latest ruby-openid
+    - MarukuHelper added
+    - AuthHelper cleaned up
+    - LinkHelper improved: A(), R(), Rs() and breadcrumbs
+
+  Examples
+    - All examples were standardized to include rubygems
+    - Simple file upload example added
+    - Search and diff functionality added to Rapaste
+
+  Misc
+    - Read and read/write issues fixed in Ramaze::Store
+    - Fix applied for running Ramaze apps within IDEs on Windows
+
+
+A complete Changelog is available at
+http://darcs.ramaze.net/ramaze/doc/CHANGELOG
+
+
+Known issues:
+
+  - none yet, waiting for your reports :)
+
+
+Ramaze Features:
+  - Builds on top of the Rack library, which provides easy use of adapters like
+    Mongrel, WEBrick, LiteSpeed, Thin, CGI or FCGI.
+
+  - Supports a wide range of templating-engines like: Amrita2, Erubis, Haml,
+    Liquid, Markaby, Remarkably and its own engine called Ezamar and (still
+    unofficial) Nagoro.
+
+  - Highly modular structure: you can just use the parts you like. This also
+    means that it's very simple to add your own customizations.
+
+  - A variety of helpers is already available, giving you things like advanced
+    caching, OpenID-authentication or aspect-oriented programming for your
+    controllers.
+
+  - It is possible to use the ORM you like, be it Sequel, DataMapper,
+    ActiveRecord, Og, Kansas or something more simplistic like DBI, or a
+    wrapper around YAML::Store.
+
+  - Good documentation: although we don't have 100% documentation right now
+    (dcov says around 75%), just about every part of Ramaze is covered with
+    basic and advanced docs. There are a variety of examples, screencasts and a
+    tutorial available.
+
+  - Friendly community: there are people from all over the world using Ramaze,
+    so you can get almost instant help and info.
+
+
+For more information please come to http://ramaze.net or ask directly on IRC
+irc://irc.freenode.net/#ramaze
+
+Thank you, Michael 'manveru' Fellinger and the Ramaze community

data/doc/meta/configuration.txt

@@ -0,0 +1,162 @@
+This chapter covers how to do configuration in Ramaze for your application.
+
+
+### Global
+
+The object holding most configuration is called Global. It resides in the Ramaze
+module/name space.
+
+Global is an instance of GlobalStruct, which itself is an instance of Struct.
+There have been some changes to it to suit its purpose.
+
+Before covering some of the available options let us see how to actually use it.
+
+For the examples shown here we will assume that you did include Ramaze
+into your main into your main name space. If you don't do that, just prefix
+Global with Ramaze so it is written Ramaze::Global.
+
+
+#### Basic assignment:
+
+  Global.spawn = 10
+
+if you do that before calling Ramaze::start Ramaze will spawn the given number of servers.
+
+
+#### Multiple assignment:
+
+  Global.setup :adapter => :mongrel,
+               :cache   => :memcached
+
+So you can pass a Hash of all the options you want to change.
+In this case you would use Mongrel as the adapter and use memcached for your
+sessions and general caching.
+
+
+#### Block assignment:
+
+  Global.setup do |g|
+    g.error_page = false
+    g.host = '127.0.0.1'
+    g.port = 7070
+  end
+
+This method is similar to the hash-assignment, but may be preferred for some
+applications.
+
+
+#### Pass on Ramaze.start
+
+  Ramaze.start :run_loose => true
+
+This way you can save a line or two in a small script.
+Please note that the values passed here have precedence over the ones directly
+set on Global and will overwrite them if you set them before, that is mostly
+useful to quickly test some configuration.
+
+
+### Global options
+
+This listing is here to provide you with descriptions of the most common
+configurations in alphabetical order per section showing the default value next
+to the key.
+
+This chapter has been shrunk a lot to cover only essentials, please look at
+lib/ramaze/global.rb to see all available options.
+
+Date of last update: 2007-05-20
+
+#### General Configuration:
+
+:sourcereload => 3
+
+SourceReload is a nifty mechanism that takes advantage of the dynamics of Ruby,
+it's basically a Thread that runs in the background and polls for files in the
+application and framework that have changed (using mtime). The value specifies
+roughly how fast your changes are going to be loaded and should be a number.
+If you set this to false, it will not start.
+
+
+:adapter => :webrick
+
+The adapter is the server Ramaze runs to serve your application. This can be any
+of mongrel/webrick/fcgi/cgi, please note that so far neither fcgi nor cgi have
+received the necessary testing, but, as they are only wrappers around the
+underlying Rack library, should work fine. Both fcgi and mongrel require
+additional libraries to be installed, webrick and cgi run out of the box.
+Generally the most supported and recommended for deployment is Mongrel.
+
+
+:cache => :memory
+
+Possible: :memory, :memcached, :yaml
+The cache is one of the more important things for deployment, the default for
+this is MemoryCache, a simple Hash.
+What you specify here will be used by Ramaze::Cache and is used throughout
+Ramaze to cache various things, like sessions, page- and value-caching.
+Included in Ramaze are the MemoryCache and YAMLStoreCache, after you install
+'memcached' you can also use the much more performant MemcachedCache that also
+makes it easy to use the same cache between different applications (sharing
+sessions is one of the most obvious uses).
+
+
+:cache_all => false
+
+Setting this value to true would enable caching for all pages served from the
+Controller (all actions).
+This is a very powerful setting and you might want to enable it if all pages
+you serve are only built once and have no further dynamics, the key for this
+cache consists of the controller and parameters, when repeated requests are
+made it will always serve the same (now static) page.
+
+
+:sessions => true
+
+Enables creation of sessions and automatic creation/setting of cookies.
+Please note that many functionalities of Ramaze depend on an intact session and
+you will have to be careful not to use these.
+This is most likely useful in combination with `cache_all`
+
+
+:error_page => true
+
+Enables the default Error page of Ramaze which is mostly useful for manual
+testing and faster debugging. In most deployment-scenarios you will however
+want to use your own Error page and so you can safely disable this setting.
+
+:host => '0.0.0.0'
+
+Tell the adapter where it accepts requests from, 0.0.0.0 says that every
+IP will be accepted, 127.0.0.1 would accept only requests from loopback.
+
+
+:mapping => {}
+
+This is a very central and special setting, it contains key/value pairs
+that define routes to your controllers, the keys are simple strings and
+start with '/', which means http://yourhost.com/ - '/foo/bar' would point
+to http://yourhost.com/foo/bar.
+The value is the class of your controller.
+
+
+:port => 7000
+
+The port Ramaze runs on, if you can think of more information about this feel
+free to tell us.
+
+
+:run_loose => false
+
+This option is mostly used to run the specs, it means that Ramaze will not
+join the adapter-threads and therefor you are free to run any code you want
+afterwards. You won't have to use this in most cases, example usage is in
+spec/spec_helper.
+
+
+:template_root => 'template'
+
+The template_root is the point your templates are located relative to the
+location of the entry-file (usually start.rb)
+It is also worth to mention that inside this directory the `mapping` is used
+to locate templates for each controller, only the controller mapped to '/' uses
+the templates directly from the `template_root`

data/doc/meta/internals.txt

@@ -0,0 +1,278 @@
+This document is a humble attempt to explain the internal workings of Ramaze and
+how the different parts fit into the big picture.
+
+It does not try to describe every little detail, as you will be better off
+reading the actual source instead. But you will at least get an idea of where to
+look.
+
+### Ramaze
+
+Ramaze is a web framework and therefor tries to make it simple to deploy your
+own applications on top of it.
+Let's outline the realms that Ramaze works in as to show what the current
+limitations and features are.
+
+
+#### Life of a request/response cycle
+
+This is a small summary of how a request creates a response in the
+examples/hello.rb and webrick (to keep it simple and short).
+All files referenced here are in lib/ramaze/ unless indicated otherwise.
+We don't explain the startup/shutdown process, only what happens from request to
+the eventual response.
+
+Browser sends request, webrick receives it and hands the ENV over to our rack
+handler (adapter/webrick.rb and adapter/base.rb).
+There it gets converted into a Ramaze::Request (trinity/request.rb) and
+a new blank Ramaze::Response (trinity/response.rb) is created.
+These two objects are then sent to Dispatcher::handle (dispatcher.rb).
+
+This all happens inside a new Thread, which is what Ramaze takes advantage of by
+assigning Thread-variables. You can see this now in
+Dispatcher::setup_environment which sets :request/:session/:response in
+Thread.current.
+
+After that, Dispatcher::dispatch is called with the path from request.path_info
+which in turn takes every class/module set in Dispatcher::FILTER and calls
+::process with the path.
+
+
+##### First, `/favicon.ico` (for most browsers)
+
+The first in FILTER is Dispatcher::File (dispatcher/file.rb) which searches
+Global.public_root and afterwards Global.public_proto for a matching file on
+this path. In our example the file found is a favicon.ico from
+Global.public_proto.
+
+The contents of FILTER have to return a Ramaze::Response, either the (possibly
+modified) original (Response#build helps with that) or a totally new
+one.
+
+In our case, Dispatcher::File uses response#build with an opened filehandler as
+body, '200 OK' as status and the Content-Type set to what Tool::MIME.type_for
+tells it is the correct mimetype for this file.
+
+
+##### Second, `/hello`
+
+We start in the processing of FILTER, since the previous steps are the same for
+every request.
+
+Here we now get only a nil value back from Dispatcher::File since no file in our
+two public directories exists for the given path.
+
+So, this time, Dispatcher::Action is called via ::process and the first thing
+this dispatcher does is trying to set the body of the request to the answer of
+Controller.handle (controller.rb) for the given path.
+
+Controller::handle doesn't do much either, but calls Controller::resolve
+(controller/resolve.rb) for the path.
+
+Here we get now into the guts of Ramaze, despite our efforts it's no easy
+reading since the underlying theory is a bit complex and many edge-cases have to
+be solved.
+
+Let me try to quickly sketch what happens here, maybe we can add a chapter about
+this aspect of Ramaze later.
+
+First we generate a pattern of how the requested path could fit into our
+controller and template structure. `/hello` only has 3 possible outcomes:
+
+Controller on '/', template or method `hello`
+Controller on '/', method `index` with parameter `hello`
+Controller on '/hello', method or template `index`
+
+After matching (in the order we wrote here) these possibilities against your
+application we get only one possibility, MainController on '/' with method
+`index`.
+
+The result is stored into an instance of Action and cached for repeated lookups,
+then passed back into Dispatcher::handle which subsequently calls Action#render
+(action/render.rb) on it.
+
+From here, Thread.current[:action] gets set and #uncached_render is called. This
+calls #before_process which only has effects if you have the AspectHelper
+activated and next on comes engine.transform with self as parameter.
+#engine is a method that figures out which engine this Action has to be rendered
+with, according to things like trait[:engine] in your controller and the
+extension of a template. In this case we have neither and the default engine
+Template::Ezamar (template/ezamar.rb) is used.
+
+So off we go, to Template::Ezamar::transform with the current instance of Action
+as parameter.
+
+::transform first calls ::wrap_compile which is inherited from Template
+(template.rb) and manages caching of compiled templates, calling ::compile with
+the action and template.
+
+The template again is retrieved through two attempts, firstly, we always call
+the method (if specified from Controller::resolve) on the controller, we
+temporarily store its result and replace it if a path for a template is set with
+the contents of the file on this path. The result of this is the final template
+that is ready for compilation.
+
+In the case of Ezamar, we first walk the TRANSFORM_PIPELINE (only
+Ezamar::Element (template/ezamar/element.rb) with ::transform and pass each the
+template for manipulation. In the example we don't have any elements, so we get
+back what we gave and generate a new instance of Ezamar::Template
+(template/ezamar/engine.rb) with the template and a path that indicates eval
+where we currently are supposed to be (templates path or the transformer).
+
+This instance is passed back to Ezamar::transform and we call #result with the
+actions binding (retrieved from earlier instantiation of the controller and
+subsequently eval `binding` inside of it).
+
+Now it's all done, we have got our body for the response which will be sent back
+to our handler as body.
+
+
+#### The Ramaze module
+
+Ramaze is also the main module or so-called namespace that the framework lives
+in. It has 
+
+Tasks on require
+
+* Inform
+  * LogHub.new(Informer)
+* Global
+  * GlobalStruct.new
+
+
+Tasks on startup as defined in Ramaze.trait[:internals] in lib/ramaze.rb
+
+* Global::startup
+  * passed options to Ramaze.start
+  * CLI options from bin/ramaze (treat as passed.merge)
+  * Global options set before startup (fake Global?)
+
+* Cache::startup
+  * adds the following caches via Cache.add:
+    * compiled
+      If Global.compile is set true this cache is used to store the compiled
+      templates.
+
+    * actions
+      Caching compiled actions.
+      
+    * patterns
+      This is used in Controller::resolve to cache the generated patterns for a
+      path.
+
+    * resolved
+      Caching the resolved but not yet compiled actions by their path.
+
+    * shield
+      Caching the generated errors for the path, so on repeated erronous
+      requests no new error-page has to be generated.
+
+* Controller::startup
+  * mapping of all subclassed Controller
+  * validation of mapping
+  * validation of template_root
+
+* Session::startup
+  * adds Cache.sessions if Global.sessions is true
+    This cache is used to store all sessions with their session-id as key.
+
+* SourceReload::startup
+  * start with Global.reload_interval
+  * assign Global.sourcereload
+
+* Adapter::startup
+  * interpret Global.adapter
+  * add every created adapter to Global.adapters
+
+
+Tasks on shutdown
+
+* Adapter::shutdown (iterates Global.adapters)
+* Inform::shutdown (iterates all in LogHub)
+
+
+
+#### Global configuration
+
+Any serious application or framework needs to be configured.
+Yes, I wished there was a silver bullet to serve all your needs as well, but at
+the current stage of programming development there is no such thing.
+So, since we need to configure, we should make it as simple and painless as
+possible, and, thanks to Ruby, it is actually quite enjoyable to do that.
+You can find a very detailed description about Global in the section about
+Configuration, for now just the basics.
+
+The basis of Ramaze::Global, the instance that is holding most part of your
+configuration or at least links to the actual places, is the
+Ramaze::GlobalStruct (ramaze/global.rb), which is a subclass of OpenStruct. If
+you are not yet familiar with OpenStruct, I very much recommend to read its
+documentation and play around a bit, it is basically just a wrapper around a
+normal Hash where you can access the keys instead of ostruct[:foo] with
+ostruct.foo.
+It simply defines a new accessors on assignment by catching things in
+method_missing. I won't go into more details here, I hope you got the principle.
+
+Now, based on this technique, GlobalStruct adds things like defaults and a
+couple of convenience methods like they are common in Ruby, giving you more
+power by tapping to the internal Hash of the GlobalStruct and adding
+update/setup methods so you can assign many key/value pairs at once.
+The RDocs will give you a very good overview of what is available and how one is
+supposed to work with it.
+
+Now back to the big picture.
+
+Ramaze accesses Global all over the place, there have been made several choices
+as to why using something like Global is considered beneficial against choosing
+for example global variables, which would be considered as a fatal choice by
+any respected Rubyist anyway.
+
+Now to something more subtle, which has to do with Global. I speak about traits,
+which is a very different concept in most of its implementations, but it is
+something that basically fits this name. It is configuration of single Objects
+and whole ancestries.
+You can give an object a trait, and most likely will use it along the lines of
+something like MyController.trait(:map => '/'), which would be picked up on
+startup and used to create Global.mapping - where we are at configuration again.
+Choosing this style of configuration complementary to a central place to put all
+your configuration was made very early in the development of Ramaze, and the
+basic code of how traits are implemented and used has proven very efficient both
+in understanding and using them.
+
+There is a basic distinction when to use Global and when to use traits and when
+to generate or assume one based on the other.
+
+If something affects your whole application and is either used directly in the
+Ramaze module or throughout the framework it is considered to be put into Global
+to gain benefits of better documentation and accessibility.
+
+On the other hand - if something is used in a configuring manner by a class that
+is instantiated often (like Controller is for example), or a module that cannot
+hold instance variables in a nice manner and is also not a constant - then it is
+configured using traits.
+
+
+Ramaze
+Global
+Adapter
+Dispatcher
+Controller
+Action
+
+Session
+Helper
+Tool
+
+
+#### The Web
+
+The so called web consists of a plethora of data, most of it is browsable
+through a web browser that just about every toaster has installed these days.
+The browser is the target of a web author, trying to utilize common standards
+like HTML and CSS which are means for data and layout to be combined, giving the
+browser a way to display the data.
+Ramaze works on the URI-scale web, meaning that addresses like
+http://someserver.com/blog/article/1 have a unique representation on your
+server.
+If we stay with this example, we see already everything Ramaze needs to see to
+serve a page based on your instructions.
+We assume that blog/article is a Controller named ArticleController in the blog
+application.