manveru-innate 2009.02.25 → 2009.03.24

data/README.md

@@ -1,6 +1,58 @@
 # Innate
 
-Innate is the new core of Ramaze, but useful on its own.
+Innate is the core of Ramaze, but useful on its own.
+
+
+## Philosophy
+
+The philosophy behind Innate is to provide a simple web-framework that:
+
+* Stays below 2000 easily readable lines of code
+* Has Rack as the only dependency
+* Provides the default helpers
+* Is easy to encapsulate and reuse in other contexts as a simple rack app
+* Has a rock-solid and fast implementation
+* Scores at least 95% in rcov
+* Is fully documented using YARD
+
+
+## Innate vs. Ramaze
+
+Numerous people asked where Innate fits into the picture of Ramaze and when it
+would be appropriate to use Innate alone.
+
+The answer to this is not as simple as I thought, given that Ramaze improves on
+it a lot by taking full advantage of the encapsulation.
+
+Innate started out as I grew increasingly annoyed by the many hacks and add-ons
+that diluted the original simplicity of Ramaze as we discovered ways to do
+things better, so I went on to create something that is impossible to dilute and
+simply works as a multiplier.
+
+It does work standalone, and it might be suitable for applications that just
+need the little extra over plain old Rack, making it easy to deploy and rely on
+the stability that comes with simple code.
+It's also the starting point if you want to study the inner workings of Ramaze
+without being distracted, all you need to keep in mind is Rack.
+
+If all you need is a couple of ERB templates and a few nodes then Innate is the
+way to go.
+Upgrading to Ramaze later is quite easy, just change a couple of lines and the
+power of your code multiplies (again).
+
+The split between Innate and Ramaze is clear cut and gives Ramaze freedom to
+expand in any direction (and I have quite some ideas where to take it).
+
+Ramaze adds things that require other dependencies, caching with memcached or
+sequel, logging with analogger or growl, templating with haml or erubis, just to
+name a few.
+
+Ramaze also adds Apps to the mix, and it is easier to understand them when the
+concepts of what's going on inside an App is completely abstracted by Innate.
+
+To summarize, Innate really keeps it simple, acts as a learning tool and
+encourages everybody to build on top of it whatever they want.
+
 
 ## Features
 
@@ -18,8 +70,9 @@ Innate is the new core of Ramaze, but useful on its own.
 * 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.
+* Works out of the box with ERB the templating engine.
+* Support for all rack-compatible web-servers.
+* Dynamic content-representation.
 
 [1]: What you may think of as Controller.
 [2]: This includes: Ruby 1.8, Ruby 1.9.1, JRuby, Rubinius
@@ -83,10 +136,12 @@ your shell:
 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
@@ -102,8 +157,10 @@ Innate is, however, known to be compatible with the ORMs listed below:
 Please consider giving us a heads up about what worked for you if it isn't in
 the list yet.
 
+
 ### View
 
+Innate has support for only
 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:
@@ -117,20 +174,22 @@ At the moment we offer following engines out of the box:
 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
+that you may be used to. This makes Ramaze the way to go for larger
 applications.
 
-For this reason, Innate won't just be a standalone framework, but will also
-become the new core for Ramaze.
+For this reason, Innate is not only a standalone framework, it is also the core
+of Ramaze.
 
 Ramaze started out without any of the benefits that Rack gives us these days,
 especially regarding the server handlers, request/response, and middleware.
@@ -139,56 +198,65 @@ 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...
+Innate provides the Innate::Options DSL, in some aspects to the old
+Ramaze::Global, but a lot more flexible.
 
-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.
+Options has namespaces, inheritance, defaults, triggers, documentation, and a
+sane name.
 
-With Innate I hope to tackle this problem, it's currently not as fast as
-Ramaze::Global, but offers namespaces and inheritance.
+The definition syntax roughly resembles Ramaze::Global.
 
-The areas wherein Ramaze::Global excels (CLI arguments, documentation and
-annotation for options) will soon be integrated as well.
+We break with the tradition where all options one would ever need were provided
+in one file. It made maintenance rather difficult and the code hard to follow.
+So the new approach is to put options where they belong, alongside the class or
+module they are used in.
 
-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.
+There are some things still in Innate.options, but they have large impact on the
+whole system.
 
-So for example, one can provide some slice that handles feeds:
+Options doesn't do things like merging env variables or parsing ARGV, these are
+things that Ramaze adds.
 
-    Innate::Options.for(:feed_slice) do |feed|
-      feed.map = '/feeds'
-      feed.view_root = 'slice/feed/view'
-      feed.retrieve = lambda{ Post.all }
-    end
+What makes Options especially useful is that you can use it in your own
+application to configure it without using diverse routes like putting config
+into counter-intuitive yaml files, using global variables, or relying on yet
+another dependency.
 
-    class Feeds
-      include Innate::Node
-      options :feed_slice
+A small example:
+
+    module Blog
+      include Innate::Optional
+
+      options.dsl do
+        o "Title of the blog", :title, "My Blog"
+        o "Syntax highlighting engine for blog posts", :syntax, :coderay
+      end
+
+      class Articles
+        Innate.node '/'
+
+        def index
+          "Welcome to #{Blog.options.title}"
+        end
+      end
     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.
+Away with controllers, long live the Node.
 
-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?
+Nodes are objects that include Innate::Node and are then considered rack
+applications that get automatically hooked into the routing.
 
-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.
+Since every existing Ramaze application relies on Ramaze::Controller and normal
+subclassing is not without merits as well we keep that part entirely in Ramaze,
+Controller simply includes Innate::Node and makes it suitable for the usage
+within Apps.
 
-Other things are layouts and provides.
 
 #### Layouts
 
@@ -209,18 +277,21 @@ 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
+    proto
+    |-- layout
+    |-- model
+    |-- node
+    |-- public
+    `-- view
 
-While none of these directories is necessary, they will be the default
-locations and should be included in a new proto for Ramaze.
+While none of these directories is necessary, they are the default locations and
+should be included in a new proto for Ramaze (just that ramaze uses
+`/controller` instead of `/node`.
 
 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
@@ -229,7 +300,8 @@ 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.
+depending on so-called wishes, that's what people usually call
+content-representation.
 
 A wish may be anything related to the request object, and by default it will
 trigger on the filename extension asked for.
@@ -239,17 +311,18 @@ 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.
+Layouts map to wishes just like views, so every content representation can have
+a suitable layout as well.
+
+This is very alien to old 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.
 
-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 this feature makes things simpler for people who care about it while it
+can be ignored by people who don't.
 
-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
 
@@ -275,66 +348,71 @@ 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.
+right for any web application.
 
-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.
+Innate defines the caching API that enables everybody to add caches with very
+little code.
 
-At this point I would really like to thank all of the people who contributed to
-caching as it is today.
+Innate provides caching by following means:
+
+* DRb
+* Hash
+* Marshal
+* YAML
+
+Ramaze adds:
+
+* Memcached
+* Sequel
+
+And as time goes on there will be many more.
 
-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.
+Very little code, just provide some options regarding default headers and easy
+ways to reset the response.
+Ramaze adds some more convenient methods.
+
 
 ### Tools
 
-Ramaze acquired quite a lot of tools, some of those are not useful anymore,
-other ones might have to stick around.
+Innate doesn't provide any of the stuff in ramaze/tool and it was removed from
+Ramaze as well, some of the reasoning is below.
 
 #### Tool::Create
 
-This has been used by `bin/ramaze --create` and I think it will stick around
-for some more time.
+This has been used by `bin/ramaze --create`, bougyman is working on a new
+`bin/ramaze` which won't use it, so we removed it.
 
 #### 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.
+Dependency for Tool::Create, removed as well.
 
 ##### 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.
+
+This was removed from Ramaze and Innate. You may use the daemonize functionality
+from rackup.
 
 ##### 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.
+revived as middleware. The functionality itself was in the adapter and even
+that's only a few lines. But so far I have never seen any usage of it.
 
 ##### Tool::Localize
 
+Despite being quite popular it has many issues and is totally unusable if you
+don't have full knowledge about what is going to be served.
+
 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.
 
@@ -342,9 +420,13 @@ 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.
 
+Innate does not attempt to do anything related to localization. Ramaze builds
+localization on top of Helper::Localize which does a much better job.
+
 ##### Tool::MIME
 
-This one will be removed, Rack::Mime is a viable alternative.
+This one was removed, Rack::Mime is the way to go.
+
 
 ### Spec helpers
 
@@ -352,25 +434,20 @@ 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).
+Innate provides a better alternative via Innate::Mock for specs, the output
+formatting is done in a rake task.
+
+There is some work in progress to integrate Innate and Ramaze with the rack-test
+library which will allow us to run specs with webrat (which is able to run using
+selenium and possibly watir in a DRY way).
+
+Rack-test will provide us also with xpath checks, multipart requests, digest
+authorization, etc.
 
-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.
+Innate abandons the snippets, keeping your core clean.
 
 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
@@ -384,16 +461,16 @@ constantly strive to reduce them slowly.
 
 ### Gestalt
 
-Gestalt has been the first "templating_engine" for Ramaze and is still used in
+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.
+This has been removed from 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
@@ -401,50 +478,59 @@ 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:
+Ramaze got quite some things in contrib, some of them used widely, others not at
+all.
 
-* gzip_filter
-* profiling
+I'm still going through these, putting what is suitable for a wider audience
+into rack-contrib, including what fits into the Ramaze concept into Ramaze, but
+none of these will find its way into Innate.
 
-Then there's things that don't see much use.  They should stay in the future
-Ramaze contrib or face removal:
+One exception, the file cache has been added to Innate already and the sequel
+cache is in Ramaze proper.
 
-* facebook
-* gettext
-* maruku_uv
-* sequel_cache
-* rest
+The gzip filter has a more powerful and better maintained equivalent in
+Rack::Deflater.
 
-And other things that should be moved into Ramaze proper:
+The profiling hook is obsolete as well, there is an equivalent in rack-contrib.
 
-* email
-* file_cache (done)
-* gems
+The emailer is really light-weight and but lacks support for many things you
+will need, I'm working on a new Helper::Email that integrates with Mailit (a
+fork of MailFactory).
+
+Things I'll not touch for now are `facebook` and `gettext`.
+
+The sequel related stuff will have to be removed and might find a place
+somewhere else, (somebody start a sequel-contrib already!).
+
+The `gems` was refactored and put into `ramaze/setup.rb`, where it provides you
+with painless first-start experience.
 
-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.
+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.
+The basic functionality for templating is provided by Innate, it only provides a
+`None` and `ERB` templating engine. The other engines are in Ramaze.
 
 #### 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.
+`Ezamar` has become a standalone project. It has been stable since a long time and
+is suitable for other uses.
+The battle for the place of the default templating engine in Ramaze is still
+going on, competitors are `ERB`, `Ezamar`, and `Nagoro`.
+
 
 ### 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.
+Bacon is still a dependency for specs, but we don't ship it anymore, the stable
+release includes all features we need.
+
 
 ### Dispatcher
 
@@ -456,7 +542,7 @@ 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
+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.
 
@@ -470,16 +556,16 @@ not needed anymore.
 
 #### Dispatcher::Directory
 
-This will also be removed.  There is a directory listing middleware already.
+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.
+other actions. This used to be one of the most difficult parts of Ramaze and
+it was removed to make things simpler.
 
 #### Dispatcher::File
 
-This is a combination of the etag and conditionalget middlewares, ergo Innate
+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.

data/Rakefile

@@ -119,20 +119,23 @@ task :spec => :setup do
   len = specs.map{|s| s.size }.sort.last
   tt = ta = tf = te = 0
 
-  red, green = "\e[31m%s\e[0m", "\e[32m%s\e[0m"
+  red, yellow, green = "\e[31m%s\e[0m", "\e[33m%s\e[0m", "\e[32m%s\e[0m"
   left_format = "%4d/%d: %-#{len + 11}s"
   spec_format = "%d specifications (%d requirements), %d failures, %d errors"
 
   specs.each_with_index do |spec, idx|
     print(left_format % [idx + 1, total, spec])
 
-    Open3.popen3("#{RUBY} #{spec}") do |sin, sout, serr|
+    Open3.popen3(RUBY, spec) do |sin, sout, serr|
       out = sout.read
       err = serr.read
 
+      ran = false
+
       out.each_line do |line|
         tests, assertions, failures, errors = all = line.scanf(spec_format)
         next unless all.any?
+        ran = true
         tt += tests; ta += assertions; tf += failures; te += errors
 
         if tests == 0 || failures + errors > 0
@@ -145,6 +148,8 @@ task :spec => :setup do
 
         break
       end
+
+      puts(yellow % "       skipped") unless ran
     end
   end
 

data/example/provides.rb

@@ -0,0 +1,28 @@
+require 'rubygems'
+require 'innate'
+
+ARTICLES = {
+  'hello' => {
+    :author => 'manveru',
+    :title => 'Hello, World!',
+    :text => 'Some text'
+  }
+}
+
+class BlogArticles
+  Innate.node('/')
+
+  # provide a content representation for requests to /<action>.yaml
+  provide(:yaml, :type => 'text/yaml'){|action, value| value.to_yaml }
+
+  # the return value of this method is the `value` in the provide above
+  # Since ruby has implicit returns, `ARTICLES` will be the return value.
+  #
+  # If you request `/list.yaml` you will get the `ARTICLES` object serialized
+  # to YAML.
+  def list
+    @articles = ARTICLES
+  end
+end
+
+Innate.start