Pistos-ramaze 2008.09

data/doc/meta/announcement.txt

@@ -0,0 +1,99 @@
+This time we are proud to announce Version 2008.07 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
+
+Source browser:  http://source.ramaze.net
+Repository:      http://github.com/manveru/ramaze
+
+Nightly gems:    http://gems.ramaze.net
+Git clone:       git://github.com/manveru/ramaze
+Current tarball: http://github.com/manveru/ramaze/tarball/master
+
+IRC: #ramaze on irc.freenode.net
+
+
+Simple example:
+
+  require 'ramaze'
+
+  class MainController
+    def index
+      'Hello, World!'
+    end
+  end
+
+  Ramaze.start
+
+
+Some of 52 patches since 2008.06:
+
+  - Loggers are now in Ramaze::Logger namespace
+  - Global.prefix for nested deployment via webserver in front
+  - Binding#locals fixed for Ruby 1.9
+  - Redirects now use HTTP status 302 instead of 303
+  - Logger::Syslog works again
+
+Special (alphabetic) thanks go to:
+
+  Pistos                  - The usual Mathetes, patches and lots of friendly support
+  Aman 'tmm1' Gupta       - Time snippets for numeric
+  Clinton R. Nixon        - More REST and some fixes
+  Jean-Francois Chevrette - Restore --console feature
+  raggi                   - Various fixes
+  Rob Lievaart            - Fix Logger::Syslog
+  Sam Carr                - Cleanup of Cache
+  Wang Jinjing            - 1.9 compatibility
+  Yasushi Abe             - First patch!
+
+A complete Changelog is available at
+http://github.com/manveru/ramaze/tree/master/doc/CHANGELOG?raw=true
+
+
+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,163 @@
+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.port = 10
+
+if you do that before calling Ramaze::start Ramaze will choose the given number
+as port.
+
+
+#### 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.

data/doc/meta/users.kml

@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://earth.google.com/kml/2.2">
+  <Document>
+    <Placemark>
+      <name>manveru</name>
+      <description><![CDATA[ <img src="http://manveru.mine.nu/public/me.png" /><br />
+            Tokyo, Japan ]]>
+        </description>
+      <Point>
+        <coordinates>139.667846,35.614759</coordinates>
+      </Point>
+    </Placemark>
+    <Placemark>
+      <name>Pistos</name>
+      <description>
+      <![CDATA[
+          <img src="http://purepistos.net/favicon32.png" alt="Pistos" /><br />
+          Toronto, Canada<br />
+          <a href="http://blog.purepistos.net">blog.purepistos.net</a>
+      ]]>
+      </description>
+      <Point>
+        <coordinates>-79.386985,43.642515,0</coordinates>
+      </Point>
+    </Placemark>
+    <Placemark>
+      <name>MonoDelDiablo</name>
+      <description><![CDATA[ Seattle, Washington, United States ]]></description>
+      <Point>
+        <coordinates>-122.266881,47.682765,0</coordinates>
+      </Point>
+    </Placemark>
+    <Placemark>
+      <name>Kashia</name>
+      <description><![CDATA[ Helsinki, Etela-Suomen Laani, Finland ]]></description>
+      <Point>
+        <coordinates>8.447204,49.028928,0</coordinates>
+      </Point>
+    </Placemark>
+    <Placemark>
+      <name>zenix</name>
+      <description><![CDATA[ Gaithersburg, Maryland, United States ]]></description>
+      <Point>
+        <coordinates>-77.183338,39.137049,0</coordinates>
+      </Point>
+    </Placemark>
+    <Placemark>
+      <name>tmm1</name>
+      <description><![CDATA[ <img src="http://tmm1.net/me.jpg" /><br />
+            Boston, Massachussetts ]]>
+        </description>
+      <Point>
+        <coordinates>-71.084371,42.365975,0</coordinates>
+      </Point>
+    </Placemark>
+    <Placemark>
+      <name>riffraff</name>
+      <description><![CDATA[ Rome, Italia ]]></description>
+      <Point>
+        <coordinates>41.993372,12.087193,0</coordinates>
+      </Point>
+    </Placemark>
+  </Document>
+</kml>

data/doc/readme_chunks/appendix.txt

@@ -0,0 +1,10 @@
+* Performance
+  * Serving
+  
+    For best performance you should consider using Mongrel to host your
+    application.
+
+  * Caching
+  
+    You can easily cache your pages using the CacheHelper.
+    Also, using MemCache gives you high-end performance and security.

data/doc/readme_chunks/examples.txt

@@ -0,0 +1,38 @@
+There are some examples for your instant pleasure inside the examples-directory
+in the Ramaze-distribution.
+To start up an example, you can use the Ramaze binary located in bin/ramaze 
+for example:
+
+  $ ramaze examples/hello.rb
+
+Or:
+
+  $ cd examples/blog
+  $ ramaze
+
+Since ramaze uses the start.rb by default if you don't pass anything else.
+
+For more information about the usage of ramaze try:
+
+  $ ramaze --help
+
+
+Examples include:
+
+* examples/hello.rb
+  Hello, World!
+
+* examples/simple.rb
+  A bit more advanced than the hello-example, but still very basic.
+
+* examples/blog
+  Not yet fully functional, but coming along.
+
+* examples/whywiki
+  A basic examples of a minimalistic application, based on the Wiki of \_why in
+  his camping-framework.
+
+* examples/templates
+  examples of real usage of the templating-engines. Tries to implement the same
+  functionality in each `template_*.rb` file using a different engine.
+