manveru-innate 2009.02.06

data/COPYING

@@ -0,0 +1,18 @@
+Copyright (c) 2008 Michael Fellinger <m.fellinger@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/MANIFEST

@@ -0,0 +1,100 @@
+CHANGELOG
+COPYING
+MANIFEST
+README.md
+Rakefile
+example/app/retro_games.rb
+example/app/whywiki_erb/layout/wiki.html.erb
+example/app/whywiki_erb/spec/wiki.rb
+example/app/whywiki_erb/start.rb
+example/app/whywiki_erb/view/edit.html.erb
+example/app/whywiki_erb/view/index.html.erb
+example/custom_middleware.rb
+example/error_handling.rb
+example/hello.rb
+example/howto_spec.rb
+example/link.rb
+example/providing_hash.rb
+example/session.rb
+innate.gemspec
+lib/innate.rb
+lib/innate/action.rb
+lib/innate/adapter.rb
+lib/innate/cache.rb
+lib/innate/cache/api.rb
+lib/innate/cache/drb.rb
+lib/innate/cache/file_based.rb
+lib/innate/cache/marshal.rb
+lib/innate/cache/memory.rb
+lib/innate/cache/yaml.rb
+lib/innate/core_compatibility/basic_object.rb
+lib/innate/core_compatibility/string.rb
+lib/innate/current.rb
+lib/innate/dynamap.rb
+lib/innate/helper.rb
+lib/innate/helper/aspect.rb
+lib/innate/helper/cgi.rb
+lib/innate/helper/flash.rb
+lib/innate/helper/link.rb
+lib/innate/helper/partial.rb
+lib/innate/helper/redirect.rb
+lib/innate/helper/send_file.rb
+lib/innate/log.rb
+lib/innate/log/color_formatter.rb
+lib/innate/log/hub.rb
+lib/innate/mock.rb
+lib/innate/node.rb
+lib/innate/options.rb
+lib/innate/options/dsl.rb
+lib/innate/request.rb
+lib/innate/response.rb
+lib/innate/route.rb
+lib/innate/session.rb
+lib/innate/session/flash.rb
+lib/innate/setup.rb
+lib/innate/spec.rb
+lib/innate/state.rb
+lib/innate/state/accessor.rb
+lib/innate/state/fiber.rb
+lib/innate/state/thread.rb
+lib/innate/traited.rb
+lib/innate/trinity.rb
+lib/innate/version.rb
+lib/innate/view.rb
+lib/innate/view/erb.rb
+lib/innate/view/none.rb
+lib/rack/middleware_compiler.rb
+lib/rack/reloader.rb
+spec/example/hello.rb
+spec/example/link.rb
+spec/helper.rb
+spec/innate/cache/common.rb
+spec/innate/cache/marshal.rb
+spec/innate/cache/memory.rb
+spec/innate/cache/yaml.rb
+spec/innate/dynamap.rb
+spec/innate/helper.rb
+spec/innate/helper/aspect.rb
+spec/innate/helper/cgi.rb
+spec/innate/helper/flash.rb
+spec/innate/helper/link.rb
+spec/innate/helper/partial.rb
+spec/innate/helper/redirect.rb
+spec/innate/helper/send_file.rb
+spec/innate/helper/view/aspect_hello.erb
+spec/innate/helper/view/locals.erb
+spec/innate/helper/view/loop.erb
+spec/innate/helper/view/num.erb
+spec/innate/helper/view/partial.erb
+spec/innate/helper/view/recursive.erb
+spec/innate/mock.rb
+spec/innate/node.rb
+spec/innate/node/bar.html
+spec/innate/node/foo.html.erb
+spec/innate/node/with_layout.erb
+spec/innate/options.rb
+spec/innate/parameter.rb
+spec/innate/request.rb
+spec/innate/route.rb
+spec/innate/session.rb
+spec/innate/traited.rb

data/README.md

@@ -0,0 +1,485 @@
+# Innate
+
+Innate is the new core of Ramaze, but useful on its own.
+
+## Features
+
+* Powerful Helper system
+* Nodes[1] simply include Innate::Node, so class inheritance is your choice.
+* The only hard dependency is Rack
+* Easy to get started
+* Compatible with major Ruby implementations[2].
+* Usage of Fiber[3] instead of Thread if possible.
+* Namespaced serializable configuration system
+* Simple testing without need of a running server
+* No clutter in your application directory structure, scales from a single file
+  upwards
+* Seamless integration with Rack middleware
+* No patching[4] of ruby core or stdlib.
+* Direct access to the current Request, Response, and Session from anywhere via
+  Trinity
+* Supporting numerous templating engines.
+* Any action can be presented in multiple ways.
+
+[1]: What you may think of as Controller.
+[2]: This includes: Ruby 1.8, Ruby 1.9.1, JRuby, Rubinius
+[3]: Fiber is available on 1.9 only at this point.
+[4]: However, we add String#each if it isn't there to be compatible with Rack.
+
+## Usage
+
+A simple example of using Innate that also shows you how to add your custom
+middleware, write specs and the overall concept:
+
+    require 'innate'
+
+    Innate.setup_middleware
+
+    Innate.map('/') do |env|
+      Rack::Response.new(['Hello, World!']).finish
+    end
+
+    Innate::Mock.get('/')
+
+And another example, using Node with a normal server:
+
+    require 'innate'
+
+    class Hi
+      include Innate::Node
+      map '/'
+
+      def index
+        "Hello, World!"
+      end
+    end
+
+    Innate.start :adapter => :mongrel
+
+## Installation
+
+### Via git (recommended)
+
+Installing Innate from git is highly recommended, since it gives you easy
+access to alternate branches, bugfixes, and new features.
+
+    git clone git://github.com/manveru/innate.git
+
+And add the innate/lib directory to your `RUBYLIB` environment variable.
+
+For unixish systems you may want to add it to `~/.bashrc` or the equivalent for
+your shell:
+
+    export RUBYLIB="~/path/to/innate/lib:$RUBYLIB"
+
+### Via gem install
+
+#### From Github
+
+    gem install manveru-innate --source=http://gems.github.com
+
+#### From Rubyforge
+
+Not yet, and not sure when I'll get around to do this, feel free to ask if you
+want to maintain the project at rubyforge.
+
+## Concepts
+
+First let's see about the good old MVC:
+
+### Model
+
+Innate doesn't have any ties to models, it does not offer helpers or rake tasks
+or whatever you may be expecting, there is no M, use whatever you like.
+Innate is, however, known to be compatible with the ORMs listed below:
+
+* ActiveRecord
+* DataMapper
+* M4DBI
+* Og
+* Sequel
+
+Please consider giving us a heads up about what worked for you if it isn't in
+the list yet.
+
+### View
+
+Innate supports multiple templating engines and it is very easy to add your
+own.
+At the moment we offer following engines out of the box:
+
+* [Builder](http://builder.rubyforge.org)
+* [Haml](http://haml.hamptoncatlin.com/)
+* [Sass](http://haml.hamptoncatlin.com/docs/sass)
+* [Erubis](http://rubyforge.org/projects/erubis)
+* [Tenjin](http://www.kuwata-lab.com/tenjin/)
+
+How to build your own is discussed at
+[HowTo:View](http://ramaze.net/HowTo:View).
+
+### Controller
+
+Innate follows a different approach than most frameworks, making the controller
+subclassing obsolete. To make an object accessible from the outside simply
+include Innate::Node and map it to the location you would like.
+
+## Differences from Ramaze
+
+Innate throws a lot overboard; it doesn't provide all the bells and whistles
+that you may be used to.  This makes Ramaze a very good option for larger
+applications.
+
+For this reason, Innate won't just be a standalone framework, but will also
+become the new core for Ramaze.
+
+Ramaze started out without any of the benefits that Rack gives us these days,
+especially regarding the server handlers, request/response, and middleware.
+
+Still it tried to provide everything one might need with the least effort,
+leading to a lot of incorporation of dependencies (we have things like bacon,
+simple_http, gettext, mime types, ...)
+
+### Configuration
+
+Configurability has always been a major aspect of Ramaze, and I will keep it
+this way. The famous option.rb is the peak of what can be achieved with the
+approach of a single Struct for all options, making them approachable from the
+CLI, during runtime, on startup, in separate files, even loading from YAML...
+
+What was always missing was a way to add configuration to your own
+applications, and extending the Ramaze::Global for this purpose is very
+difficult.
+
+With Innate I hope to tackle this problem, it's currently not as fast as
+Ramaze::Global, but offers namespaces and inheritance.
+
+The areas wherein Ramaze::Global excels (CLI arguments, documentation and
+annotation for options) will soon be integrated as well.
+
+Configuration namespaces will offer a nice way to merge different applications
+and reconcile their options in a unified manner, opening the way for slice-like
+behaviour.
+
+So for example, one can provide some slice that handles feeds:
+
+    Innate::Options.for(:feed_slice) do |feed|
+      feed.map = '/feeds'
+      feed.view_root = 'slice/feed/view'
+      feed.retrieve = lambda{ Post.all }
+    end
+
+    class Feeds
+      include Innate::Node
+      options :feed_slice
+    end
+
+It would be a requirement to set the options before requiring the slice itself,
+but that's just a minor issue that I think we can live with.
+
+### Controller
+
+Well, that's the part I worry most about. Every existing Ramaze application
+relies on the Ramaze::Controller.
+
+The major question is, should we switch Ramaze entirely to the Node approach or
+maybe just provide a Ramaze::Controller that has Innate::Node included?
+
+It does have drawbacks, such as decreased support for either approach, but
+might give people a familiar anchor when switching, and allow them to gradually
+adjust their applications.
+
+Other things are layouts and provides.
+
+#### Layouts
+
+Since layouts were an afterthought in Ramaze, they were made normal actions
+like every other on the respective controllers, leading to lots of confusion
+over the correct way to use layouts, the Controller::layout syntax in respect
+to the real location of layouts, how to exclude/include single actions, where
+layouts should be stored, how to prevent lookup from external requests, ...
+
+I made layouts just as important as views and methods for the Action in Innate,
+and they have their own root directory to live in and will not be considered as
+a normal view template, so they cannot be accidentally be rendered as their own
+actions.
+
+This strikes me as important, because I consider layouts to be superior to
+Ezamar elements and equal to render_partial or render_template, just about
+every application uses it, so they should be handled in the best way possible.
+
+The root directory for layouts is in line with the other default locations:
+
+/node
+/layout
+/view
+/model
+/public
+
+While none of these directories is necessary, they will be the default
+locations and should be included in a new proto for Ramaze.
+
+Innate will not have project generating capabilities, so we just have to
+document it very well and provide some example apps.
+
+#### Provides
+
+This is a major new feature stolen from Merb and adapted for the ease of use of
+Innate/Ramaze.
+It won't have all the capabilities one might be used to out of the box, but
+extending them is easy.
+
+Having "provides" means that every Action has different ways of being rendered,
+depending on so-called wishes.
+
+A wish may be anything related to the request object, and by default it will
+trigger on the filename extension asked for.
+This enables you to create a single action that can be rendered in
+json/rss/atom/yaml/xml/xhtml/html/wap or different languages...
+
+The dispatching in Node depends on the filename extension by default, but more
+decision paths can be added to Action by overriding some defaults.
+
+There is no convention yet of how layouts will map to these wishes, but I hope
+to specify this further once we have some specific requirements.
+
+This feature is very alien to Ramaze, which always has a 1:1 mapping between
+actions and their views and how they are rendered, which made people wonder how
+to serve sass as css or how to respond with json for a ajax request until they
+finally were pointed to setting content-type, using respond and setting up
+custom routes.
+
+I hope that adding this feature will make things simpler for people who care
+about it while it can be ignored by people who don't.
+
+### More specifics
+
+Here I try to list the most important things that Ramaze will offer but that
+are not included in Innate itself in terms of globs:
+
+* cache.rb and cache/*.rb
+* current/response.rb
+* tool/{create,mime,localize,daemonize,record,project_creator}.rb
+* spec/helper/*.rb
+* snippets/**/*.rb
+* gestalt.rb
+* store/default.rb
+* contrib.rb or any contribs
+* adapter/*.rb (superseded by a lightweight adapter.rb)
+* template/ezamar*/*
+* bacon.rb
+* dispatcher.rb
+* dispatcher/*.rb
+
+There might be a couple of things I've forgotten, but that's what a quick
+glance tells me.
+
+Let's go through them one by one and consider what's gonna happen to them:
+
+### Cache
+
+Caching is a very important concern and one of the most difficult things to get
+right for any web application.  Ramaze tried to get caching done right and I
+consider it fairly successful when it comes to that.  There are a myriad of
+options available for caching, different caching mechanisms such as marshal to
+filesystem, memcached, in-memory, yaml to filesystem, etc.  The granularity can
+be chosen depending on the use case, distributed caching of sessions, actions,
+single key/value pairs, and so on.  Fine-tuning each of those to use a different
+mechanism will be made as painless as possible.
+
+We have gone through a lot of difficulties, memory-leaks, disputes, and
+challenges to get this done, but most users won't realize this until they
+encounter a problem.
+
+At this point I would really like to thank all of the people who contributed to
+caching as it is today.
+
+I will move caching in a lighter form to Innate, mostly what is needed for
+distributed sessions, giving Ramaze the opportunity to add new kinds.
+
+### Response
+
+This was always a very little class since Rack started providing more features,
+I think it's time to retire it and lobby for integration of features into Rack
+itself.
+
+### Tools
+
+Ramaze acquired quite a lot of tools, some of those are not useful anymore,
+other ones might have to stick around.
+
+#### Tool::Create
+
+This has been used by `bin/ramaze --create` and I think it will stick around
+for some more time.
+
+#### Tool::ProjectCreator
+
+Dependency for Tool::Create, should get a lot more documentation and exposure
+because I think it can be very useful for sharing and creating basic
+application skeletons.
+Another route would be to find a better tool and make it a dependency for
+`ramaze --create`, but that would give a terrible out-of-the-box experience.
+
+##### Tool::Daemonize
+
+Nothing but issues with this one although it is just a very thin wrapper for
+the daemons gem. Nobody has contributed to this so far despite the issues and
+it seems that there are a lot of different solutions for this problem.
+This will be removed from both Ramaze and Innate.
+
+##### Ramaze::Record
+
+Well, this might be the most obvious candidate for removal, maybe it can be
+revived as middleware.  The functionality itself is in the adapter and even
+that's only a few lines.  But so far I have never seen any usage for it.
+
+##### Tool::Localize
+
+I and a lot of other people have used this over time and it has proven itself
+to be a very easy and straight-forward way of doing localization.
+
+It think it is better suited as middleware which can be included into
+rack-contrib and doesn't rely on the normal session but a simple unobfuscated
+cookie.
+
+##### Tool::MIME
+
+This one will be removed, Rack::Mime is a viable alternative.
+
+### Spec helpers
+
+Over the years, Ramaze has collected a wide variety of spec helpers that are
+not really compatible to each other and rely on real request/response with a
+running server.
+
+Innate provides a better alternative via Innate::Mock for its own specs,
+applications will need the power of a real scraping library and we will provide
+a canonical way of running a server in the background before running the specs.
+There will not be any other helpers in Innate, but Ramaze might provide a few
+standard ones to get up and running (hpricot, rexml).
+
+Regarding the spec output parsers, that's a different issue.  Providing
+readable output while running specs is a major feature that must be included in
+order to keep frustration low.  We will provide a suitable logger replacement
+so one can simply extend Bacon with that in order to get nice summaries and
+good error output.
+
+### Snippets
+
+Snippets have been in Ramaze since day 1, but I think it is wrong for Innate to
+provide those. Over the years there have been lots of libraries that all
+provide their own core extensions and interference is a major issue. Innate
+will keep everything as clean as possible, doing subclasses inside the Innate
+namespace where it needs to change things.
+
+Two things that we need are (currently) String#each, because Rack relies on it,
+and BasicObject as superclass for the Option class. They are only applied on
+demand.
+
+These are in the directory called core_extensions, to make it very, very clear
+what we are doing and how we are doing it.
+
+Ramaze has still a lot of these snippets and will continue to, although I will
+constantly strive to reduce them slowly.
+
+### Gestalt
+
+Gestalt has been the first "templating_engine" for Ramaze and is still used in
+some fractions of the code and various applications.  There are a lot of other
+html/xml builders out there these days so I think this is no good choice for
+inclusion into Innate. I will keep it inside Ramaze.
+
+### Ramaze::Store::Default
+
+I will remove this class from both Innate and Ramaze. It started out as a
+simple wrapper for YAML::Store to make the tutorial easier, but I think it
+gives a wrong impression of being anything else.
+
+It's very slow, might raise exceptions under heavy load and a plain YAML::Store
+or PStore or any other persistence mechanism is generally a better choice, so
+there is no need to keep this around.
+
+### Contrib
+
+There's a lot in there, and some of these things are used widely, others not at
+all.  Some things are better suited as middleware, I will move them to
+rack-contrib ASAP:
+
+* gzip_filter
+* profiling
+
+Then there's things that don't see much use.  They should stay in the future
+Ramaze contrib or face removal:
+
+* facebook
+* gettext
+* maruku_uv
+* sequel_cache
+* rest
+
+And other things that should be moved into Ramaze proper:
+
+* email
+* file_cache (done)
+* gems
+
+None of these will be included in Innate.
+
+### Adapters
+
+These are entirely the responsibility of Rack/Innate now, Ramaze doesn't need
+to worry about that.  WEBrick will remain the default adapter since it is in
+the Ruby stdlib.
+
+### Templating
+
+Templating will also be handled by Innate for the most part.
+
+#### Ezamar
+
+I have plans to make Ezamar a separate project.  It's been stable since over a
+year and I think it's time to make it available for other projects.  ERB will
+be the new default engine since it also is in the stdlib.
+
+### Bacon
+
+Bacon will be a dependency for Ramaze and Innate specs, but we will not ship it
+anymore, it's stable and has all features we need included in the release.
+
+### Dispatcher
+
+Innate uses a stripped down version of the Ramaze dispatcher.  The Ramaze
+dispatcher was strongly influenced by Nitro, but proved to be a difficult
+part.  We are now using Rack's URLMap directly, and have a minimal dispatching
+mechanism directly in Node (like we used to have one in Controller).
+
+A lot of the functionality that used to be in the different dispatchers is now
+provided by Rack middleware.
+
+The Dispatcher itself isn't needed anymore.  It used to setup
+Request/Response/Session, which was superseded by Current, this again is now
+superseded by STATE::wrap.
+
+We are going to remove all the other dispatchers as well, providing default
+ways to provide the same functionality, and various middleware to use.
+
+#### Dispatcher::Action
+
+This dispatcher was used to initiate the controller dispatching, this is now
+not needed anymore.
+
+#### Dispatcher::Directory
+
+This will also be removed.  There is a directory listing middleware already.
+
+#### Dispatcher::Error
+
+There's middleware for this as well, and a canonical way of routing errors to
+other actions.  This used to be one of the most difficult parts of Ramaze and
+it will be removed to make things simpler.
+
+#### Dispatcher::File
+
+This is a combination of the etag and conditionalget middlewares, ergo Innate
+and Ramaze will not serve static files themselves anymore, but leave the job to
+Rack or external servers.