Pistos-ramaze 2008.09

data/README.markdown

@@ -0,0 +1,481 @@
+          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
+ All files in this distribution are subject to the terms of the Ruby license.
+
+# About Ramaze
+
+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.
+
+This of course is nothing new to anyone who knows some ruby, but is often
+forgotten in a chase for new functionality and features. Ramaze only tries to
+give you the ultimate tools, but you have to use them yourself to achieve
+perfect custom-tailored results.
+
+Another one of the goals during development of Ramaze was to make every part as
+modular and therefor reuasable as possible, not only to provide a basic
+understanding after the first glance, but also to make it as simple as possible
+to reuse parts of the code.
+
+The original purpose of Ramaze was to act as a kind of framework to build
+web-frameworks, this was made obsolete by the introduction of rack, which
+provides this feature at a better level without trying to enforce any structural
+layout of the resulting framework.
+
+
+# Features Overview
+
+Ramaze offers following features at the moment:
+
+* Adapters
+
+   Ramaze takes advantage of the rack library to provide a common way of
+   handling different ways to serve its content.
+
+   Rack supports at the moment:
+
+    * [Mongrel](http://mongrel.rubyforge.org/)
+
+      Mongrel is a fast HTTP library and server for Ruby that is intended for
+      hosting Ruby web applications of any kind using plain HTTP rather than
+      FastCGI or SCGI.
+
+    * [WEBrick](http://www.webrick.org/)
+
+      WEBrick is a Ruby library program to build HTTP servers.
+
+    * CGI
+
+      CGI is the Common Gateway Interface and is one of the most basic ways
+      to integrate into Webservers like Apache or Lighttpd.
+
+    * FCGI
+
+      Improvment of CGI as it doesn't start up a new connection to Ramaze on
+      every request.
+
+
+* Templates
+  * [Amrita2](http://amrita2.rubyforge.org/)
+
+    Amrita2 is a xml/xhtml template library for Ruby. It makes html documents
+    from a template and a model data.
+
+  * [Erubis](http://rubyforge.org/projects/erubis)
+
+    Erubis is a fast, secure, and very extensible implementation of eRuby.
+
+  * [Haml](http://haml.hamptoncatlin.com/)
+
+    Haml takes your gross, ugly templates and replaces them with veritable Haiku.
+
+  * [Liquid](http://home.leetsoft.com/liquid)
+
+    Liquid's syntax and parse model are inspired by Django templates, as well
+    as PHP's smarty.
+
+  * [Remarkably](http://rubyforge.org/projects/remarkably)
+
+    Remarkably is a very tiny Markaby-like XML builder
+
+  * [Markaby](http://code.whytheluckystiff.net/markaby/)
+
+    Markaby means Markup as Ruby.
+
+  * [Sass](http://haml.hamptoncatlin.com/docs/sass)
+
+    Sass is a meta-language on top of CSS that‘s used to describe the style of
+    a document cleanly and structurally, with more power than flat CSS allows.
+
+  * Ezamar
+
+    A simple homage to [Nitro](http://nitroproject.org)s templating, is shipped
+    together with Ramaze.
+
+* Cache
+  * Hash
+  * YAML::Store
+  * MemCache
+
+* Helper
+  * Active by default
+    * CGI
+
+      Shortcuts for escape/unescape of the CGI module.
+
+    * File
+
+      Helps you serving files from your Controller.
+
+    * Flash
+
+      Store a couple of values for one request associated with a session.
+
+    * Link
+
+      Easier linking to the various parts of your applications Controllers and
+      Actions.
+
+    * Redirect
+
+      Easy redirection.
+
+  * Optional
+    * Aspect
+
+      Allows you to wrap different Actions on your Controller with code.
+
+    * Auth
+
+      Simple way to add basic authentication.
+
+    * Cache
+
+      Easy caching Actions and values.
+
+    * Identity
+
+      For ease of use of the OpenID authentication mechanism.
+
+    * Inform
+
+      Wrapping the functionality of Ramazes logging facilities.
+
+    * Markaby
+
+      Allows you to use Markaby in your Controller without having it as the
+      default templating engine.
+
+    * Nitroform
+
+      Hooks up on nitros form builder to help you creating forms from Og
+      objects.
+
+    * OpenID
+
+      Authentication via OpenID made easy.
+
+    * Pager
+
+      Displays a collection of entitities in multiple pages.
+
+    * Partial
+
+      Renders so-called partials.
+
+    * Stack
+
+      Allows you to use a call/answer mechanism for things like redirection to the
+      site a user entered login-forms from.
+
+* Various
+  * Sessions
+  * Global configuration system
+  * Simple request/response handling
+  * Custom sophisticated Error-handling
+
+
+# Basic Principles
+
+There are some basic principles that Ramaze tries to follow:
+
+* KISS (Keep It Super Simple)
+
+  Ramaze doesn't introduce any major change of paradigm for everyone familiar
+  with Ruby and the basics of Web-development.
+
+* POLS (Principle Of Least Surprise)
+
+  Ramaze tries to be intuitive and easy to learn. Most functionality is built in
+  a way to help, not to obfuscate or confuse.
+
+* Modular design
+
+  Use what you want and how you want it.
+
+  Through Ruby Ramaze provides one of the most powerful programming-languages
+  available, giving you full control over your system.
+
+  Even the most essential parts of Ramaze can easily be replaced and/or modified
+  without losing the advantage of the whole framework.
+
+* Minimal dependencies
+
+  Nothing besides Ruby is required for the basic features.
+
+  Of course you can take advantage of several wonderful libraries, but Ramaze is
+  built in a way to be run on any basic setup.
+
+* Documentation
+
+  Document everything, classes, modules, methods, configuration...
+
+  Through 100% documentation Ramaze gives the developer easy and solid
+  understanding of the underlying concepts and functionality.
+
+* Open development
+
+  Everyone is welcome to contribute to Ramaze in the easiest way possible. The
+  repository is open for patches passing the Test-suite.
+
+* Examples
+
+  Everyone learns different, some only read the source, others browse
+  documentation, but everyone loves examples for a quick and painless start.
+
+  Ramaze addresses this need and offers a wide variety of examples of usage,
+  basic functionality, project-layout and more advanced applications.
+
+* Fully BDD (Behaviour Driven Design)
+
+  Ramaze has a very complete set of so-called specifications built by RSpec.
+  These specs define the way Ramaze has to behave.
+
+  The specs are checked every time a new patch is pushed into the repository,
+  deciding whether the changes the patch applies are valid and don't break the framework.
+
+
+# Installation
+
+* via RubyGems
+
+  The simplest way of installing Ramaze is via the gem.
+
+  [Rubygems](http://rubygems.org) is the package manager for ruby apps and
+  libraries and provides you with the last tagged version of Ramaze.
+
+      $ gem install ramaze
+
+  Versions are made as we see fit and get an announcment out (usually that's
+  the major obstacle as there is a lot to announce).
+
+  If you want to install the nightly gem of Ramaze you can do this with:
+
+      $ gem install ramaze --source=http://gem.ramaze.net/
+
+  We also use the gem building process on github, which locates gems at
+  http://gems.github.com - so you can get a version from there as well:
+
+      $ gem install manveru-ramaze --source=http://gems.github.com/
+
+* via git
+
+  To get the latest and sweetest, you can just pull from the repository and run
+  Ramaze that way.
+
+      $ git clone git://github.com/manveru/ramaze.git
+
+  Please read the `man git` or `git 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.
+
+  Some hints for the usage of Git.
+
+  * use `require 'ramaze'` from everywhere
+
+    Simply add the path to your repository to the RUBYLIB environment variable.
+    If you are using bash you can simply put following line into your .bashrc:
+
+        $ export RUBYLIB="$HOME/path/to/repo/lib/"
+
+    Of course you should put the real path instead, you can also add multiple
+    paths, or create your personal `site_ruby`:
+
+        $ export RUBYLIB="$HOME/ruby/ramaze/lib:$HOME/.site_ruby:$HOME/ruby/bacon/lib"
+
+  * use `require 'ramaze'` systemwide from everywhere
+
+    add a file to your `site_ruby` directory named 'ramaze.rb'
+    the content should be: `require '/path/to/git/repo/ramaze/lib/ramaze'`
+
+  * Pull the latest version
+
+        $ git pull
+
+  * Reset the repo to original state (if you screw up something)
+
+        $ git reset --hard # resets the whole repo
+
+  * Revert changes to (for example) lib/ramaze.rb only
+
+        $ git checkout master lib/ramaze.rb
+
+  * Add and commit all changes.
+
+        $ git commit -a
+
+  * Adding only specific changes.
+
+        # Add hunks you want to commit to the staging area (index)
+        $ git add -p
+
+  * Commit the changes into the history of your repository
+
+        # Create a commit from the hunks added
+        $ git commit
+
+  * output your patches into a bundle ready to be mailed (compress it before
+    sending to make sure it arrives in the way you sent it)
+
+    At the end of this process you will have a tar.bz2 for all your changes
+    that you can mail to ramaze@googlegroups.com
+
+        # make sure you are on latest revision to avoid conflicts
+        $ git pull
+
+        # create 00xx-blah.patch files against the remote repo
+        $ git format-patch origin/HEAD
+
+        # From here on you can use either git-send-email or go the manual route
+        $ tar -cjf ramaze_bundle.tar.bz2 *.patch
+
+
+# Getting Started
+
+Now that you have a vague idea of what you're about to get into you might just
+want to get a way to get up and running ASAP.
+Please read below for more information about installation.
+
+Depending on what you are planning to do you can either just go and start
+reading the source or directly get some hands-on experience by trying some of
+the examples.
+Most things will require dependencies though. The basic functionality is
+provided by the WEBrick adapter and the Template::Ramaze, which just run out
+of the box. For more features you will have to install some templating-engines
+and mongrel (_very_ recommended). Ramaze will inform you when it needs further
+dependencies, so just go and try some things.
+
+Some places to get started are:
+- Read the documentation.
+- Run and read the test cases.
+- Look at the examples and run/modify them.
+
+
+
+# A couple of Examples
+
+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.
+
+
+
+# How to find Help
+
+For help you can:
+
+- Visit us in the channel #ramaze on irc.freenode.net
+
+- Join the Mailinglist at http://ramaze.rubyforge.org
+
+
+# Appendix
+
+* 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.
+
+
+# And thanks to...
+
+There is a large number of people who made Ramaze possibe by their ongoing
+efforts in the world of open source and by encouraging and helping me.
+
+This list is by no means a full listing of all these people, but I try to
+get a good coverage despite that.
+
+I would like to thank:
+
+* Yukihiro Matsumoto a.k.a matz
+
+    For giving the world Ruby and bringing fun back into programming.
+
+* Zed Shawn a.k.a. zedas
+
+    For developing Mongrel, Ramaze started out as a simple Hello World based
+    on that awesome server.
+
+* Christian Neukirchen a.k.a chris2
+
+    For building rack, which is just what the numerous web-developers had
+    anticipated and which will, with no doubt, change the world.
+
+* Pistos
+
+    For continious encouragment and building the first real webpage on Ramaze.
+    His bugreports were invaluable.
+
+* Jim Weirich
+
+    For Rake, which lifts off a lot of tasks from the shoulders of every
+    developer who uses it.
+
+* Thomas Sawyer a.k.a Trans
+
+    Dragging me deep into the rabbit-hole and showing me how awesome Ruby
+    truely is through his work on facets, ratchets and tons of other projects.
+
+* George Moschovitis a.k.a gmosx
+
+    For his tremendous efforts in the Nitro/Og framework, which is a source of
+    steady inspiration for Ramaze and brought me to Ruby in the first place.
+
+* Rob Levin a.k.a. lilo
+
+    He founded the most excellent Freenode IRC-network, where the most important
+    channels for rubyists are located (as is #ramaze).
+    May he rest in peace.
+
+* The guys (and gals) in the various channels on Freenode
+
+    As the people are way too many to be listed, here the channels that i call
+    my online home.
+    All the people in there deserve special thanks for getting me hooked to Ruby
+    and providing their help in a friendly and patient manner.
+
+    * #nitro
+    * #ruby-de
+    * #ruby-lang
+    * #rubyforce

data/Rakefile

@@ -0,0 +1,228 @@
+begin
+  require 'rubygems'
+rescue LoadError
+end
+
+require 'rake'
+require 'rake/clean'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+
+require 'pp'
+require 'date'
+require 'time'
+require 'fileutils'
+
+include FileUtils
+
+$:.unshift File.join(File.dirname(__FILE__), "lib")
+
+require 'ramaze/version'
+load 'rake_tasks/conf.rake'
+load 'rake_tasks/maintenance.rake'
+load 'rake_tasks/spec.rake'
+load 'rake_tasks/coverage.rake'
+load 'rake_tasks/release.rake'
+load 'rake_tasks/git.rake'
+load 'rake_tasks/gem.rake'
+load 'rake_tasks/metric.rake'
+
+task :default => ['spec']
+task :test => ['spec']
+# task :package => ['jquery']
+
+desc 'download latest jquery and put in /lib/proto/public/js/jquery.js'
+task :jquery do
+  require 'open-uri'
+  $stdout.sync = true
+
+  File.open('lib/proto/public/js/jquery.js', 'w+') do |jquery|
+    remote = open('http://code.jquery.com/jquery-latest.js')
+    print "openend remote side, copying..."
+    while chunk = remote.read(4096)
+      print '.'
+      jquery.write(chunk)
+    end
+    puts " done."
+  end
+end
+
+desc 'Check gemspec file list against real file list'
+task :check_gemspec do
+  base_dir = File.expand_path(File.dirname(__FILE__))
+  gemspec_files = eval(File.read(File.join(base_dir,'ramaze.gemspec'))).files.map{|file|File.join(base_dir,file)}
+
+  deleted_files = gemspec_files.select{|file|!File.exists?(file)}.map{|file|file[(base_dir.size+1)..-1]}
+
+  added_files = Dir.glob(File.join(File.dirname(__FILE__),'**/*')).select do |file|
+    !gemspec_files.index(file)
+  end.map do |file|
+    file[(base_dir.size+1)..-1]
+  end.select do |file|
+    !( file == 'pkg' or file =~ /.*\.gem/ )
+  end
+
+  unless deleted_files.empty?
+    puts "The following files appear in the gemspec but cannot be found:"
+    deleted_files.each do |file|
+      puts "\t#{file}"
+    end
+  end
+  unless added_files.empty?
+    puts "The following files exist, but cannot be found in the gemspec:"
+    added_files.each do |file|
+      puts "\t#{file}"
+    end
+  end
+end
+
+task :rcov_dir do
+  mkdir_p 'doc/output/tools/rcov/'
+end
+
+desc "Generate HTML coverage report"
+task :rcov_summary => :rcov_dir do
+  `rcov --version`
+  raise LoadError, "Please `gem install rcov` first" if $?.exitstatus == 127
+  raise "Run `rake coverage` to generate coverage data first" unless File.exists? 'coverage.data'
+  sh "rcov --aggregate coverage.data -o doc/output/tools/rcov/"
+end
+
+desc "generate rdoc"
+task :rdoc => [:clean] do
+  sh "rdoc #{(RDOC_OPTS + RDOC_FILES).join(' ')}"
+end
+
+desc "generate improved allison-rdoc"
+task :allison => :clean do
+  opts = RDOC_OPTS
+  path = `allison --path`.strip
+  raise LoadError, "Please `gem install allison` first" if $?.exitstatus == 127
+  opts << %W[--template '#{path}']
+  sh "rdoc #{(RDOC_OPTS + RDOC_FILES).join(' ')}"
+end
+
+desc "create bzip2 and tarball"
+task :distribute => :gem do
+  sh "rm -rf pkg/ramaze-#{VERS}"
+  sh "mkdir -p pkg/ramaze-#{VERS}"
+  sh "cp -r {bin,doc,lib,examples,spec,Rakefile,README.markdown,rake_tasks} pkg/ramaze-#{VERS}/"
+
+  Dir.chdir('pkg') do |pwd|
+    sh "tar -zcvf ramaze-#{VERS}.tar.gz ramaze-#{VERS}"
+    sh "tar -jcvf ramaze-#{VERS}.tar.bz2 ramaze-#{VERS}"
+  end
+
+  sh "rm -rf pkg/ramaze-#{VERS}"
+end
+
+desc "show a todolist from all the TODO tags in the source"
+task :todo do
+  files = Dir[File.join(BASEDIR, '{lib,spec}', '**/*.rb')]
+
+  files.each do |file|
+    lastline = todo = comment = long_comment = false
+
+    File.readlines(file).each_with_index do |line, lineno|
+      lineno += 1
+      comment = line =~ /^\s*?#.*?$/
+      long_comment = line =~ /^=begin/
+      long_comment = line =~ /^=end/
+      todo = true if line =~ /TODO/ and (long_comment or comment)
+      todo = false if line.gsub('#', '').strip.empty?
+      todo = false unless comment or long_comment
+      if todo
+        unless lastline and lastline + 1 == lineno
+          puts
+          puts "vim #{file} +#{lineno}"
+        end
+
+        l = line.strip.gsub(/^#\s*/, '')
+        print '  ' unless l =~ /^-/
+        puts l
+        lastline = lineno
+      end
+    end
+  end
+end
+
+desc "opens a simple readline that makes making requests easier"
+task 'request' do
+  ARGV.clear
+  require 'open-uri'
+  require 'pp'
+
+  loop do
+    print 'do request? [enter] '
+    gets
+    begin
+      pp open('http://localhost:7000/xxx').read
+    rescue Object => ex
+      puts ex
+    end
+  end
+end
+
+desc 'listing of available traits per class/module'
+task 'traits' do
+  nodes = Hash.new{|h,k| h[k] = []}
+  Dir['lib/**/*.rb'].each do |file|
+    content = File.read(file)
+    traits = content.grep(/^\s*trait\s*:/)
+    traits.each do |trait|
+      space = content[0..content.index(trait)].scan(/^\s*(?:class|module)\s+(.*)$/)
+      space = space.flatten.join('::')
+      nodes[space] << trait.strip
+    end
+  end
+
+  nodes.each do |space, traits|
+    puts space
+    traits.each do |trait|
+      print '  ', trait, "\n"
+    end
+    puts
+  end
+end
+
+desc "Update doc/CHANGELOG"
+task 'doc/CHANGELOG' do
+  File.open('doc/CHANGELOG', 'w+') do |f|
+    f.puts `git log`
+  end
+end
+
+desc "#{README} to doc/README.html"
+task 'doc/README.html' => [README] do
+  sh "maruku #{README}"
+  mv 'README.html', 'doc/README.html'
+end
+
+desc "Compile the #{README} from the parts of doc/readme"
+task README do
+  require 'enumerator'
+
+  chapters = [
+    'About Ramaze',         'introduction',
+    'Features Overview',    'features',
+    'Basic Principles',     'principles',
+    'Installation',         'installing',
+    'Getting Started',      'getting_started',
+    'A couple of Examples', 'examples',
+    'How to find Help',     'getting_help',
+    'Appendix',             'appendix',
+    'And thanks to...',     'thanks',
+  ]
+
+  File.open(README, 'w+') do |readme|
+    readme.puts COPYRIGHT.map{|l| l[1..-1]}, ''
+
+    chapters.each_slice(2) do |title, file|
+      file = File.join('doc', 'readme_chunks', "#{file}.txt")
+      chapter = File.read(file)
+      readme.puts "# #{title}", '', chapter
+      readme.puts '', '' unless title == chapters[-2]
+    end
+  end
+end