roda 3.28.0 → 3.29.0

data/doc/release_notes/1.0.0.txt

@@ -1,329 +0,0 @@
-= New Plugins
-
-* A csrf plugin has been added for CSRF prevention, using
-  Rack::Csrf.  It also adds helper methods for views such as
-  csrf_tag.
-
-* A symbol_matchers plugin has been added, for customizing
-  the regexps used per symbol.  This also affects the use
-  of embedded colons in strings.  This supports the following
-  symbol regexps by default:
-
-  :d :: (\d+), a decimal segment
-  :format :: (?:\.(\w+))?, an optional format/extension
-  :opt :: (?:\/([^\/]+))?, an optional segment
-  :optd :: (?:\/(\d+))?, an optional decimal segment
-  :rest :: (.*), all remaining characters, if any
-  :w :: (\w+), a alphanumeric segment
-
-  This allows you to write code such as:
-
-    plugin :symbol_matchers
-
-    route do |r|
-      r.is "track/:d" do
-      end
-    end
-
-  And have it only match routes such as /track/123, not
-  /track/abc.
-
-  Note that :opt, :optd, and :format are only going to make sense
-  when used as embedded colons in strings, due to how segment matching
-  works.
-
-  You can add your own symbol matchers using the symbol_matcher
-  class method:
-
-    plugin :symbol_matchers
-    symbol_matcher :slug, /([\w-]+)/
-
-    route do |r|
-      r.on :slug do
-      end
-    end
-
-* A symbol_views plugin has been added, which allows match blocks to
-  return symbols, which are interpreted as template names:
-
-    plugin :symbol_views
-
-    route do |r|
-      :template_name # same as view :template_name
-    end
-
-* A json plugin has been added, which allows match blocks to return
-  arrays or hashes, and uses a JSON version of them as the response
-  body:
-
-    plugin :json
-
-    route do |r|
-      {'a'=>[1,2,3]} # response: {"a":[1,2,3]}
-    end
-
-  This also sets the Content-Type of the response to application/json.
-
-  To convert additional object types to JSON, you can modify
-  json_response_classes:
-
-    plugin :json
-    json_response_classes << Sequel::Model
-
-* A view_subdirs plugin has been added for setting a default
-  subdirectory to use for views:
-
-    Roda.route do |r|
-      r.on "admin" do
-        set_view_subdir "admin"
-        
-        r.is do
-          view "index" # uses admin/index view
-        end
-      end
-    end
-
-* A render_each plugin has been added, for rendering the same
-  template for multiple objects, and returning the concatenation
-  of all of the output:
-
-    <%= render_each([1,2,3], 'number') %>
-
-  This renders the number template 3 times.  Each time the template
-  is rendered, a local variable named number will be present with
-  the current entry in the enumerable.  You can control the name of
-  the local variable using the :local option:
-
-    <%= render_each([1,2,3], 'number', :local=>:n) %>
-
-* A content_for plugin has been added, for storing content in one
-  template and retrieving that content in a different template (such
-  as the layout).  To set content, you call content_for with a block:
-
-    <% content_for :foo do %>
-      content for foo
-    <% end %>
-
-  To retrieve content, you call content_for without a block:
-
-    <%= content_for :foo %>
-
-  This plugin probably only works when using erb templates.
-
-* A not_allowed plugin has been added, for automatically returning 405
-  Method Not Allowed responses when a route is handled for a different
-  request method than the one used.  For this routing tree:
-
-    plugin :not_allowed
-
-    route do |r|
-      r.get "foo" do
-      end
-    end
-
-  If you submit a POST /foo request, it will return a 405 error
-  instead of a 404 error.
-
-  This also handles cases when multiple methods are supported for
-  a single path, so for this routing tree:
-
-    route do |r|
-      r.is "foo" do
-        r.get do
-        end
-        r.post do
-        end
-      end
-    end
-
-  If you submit a DELETE /foo request, it will return a 405 error
-  instead of a 404 error.
-
-* A head plugin has been added, automatically handling HEAD requests
-  the same as GET requests, except returning an empty body. So for
-  this routing tree:
-
-    plugin :head
-
-    route do |r|
-      r.get "foo" do
-      end
-    end
-
-  A request for HEAD /foo will return a 200 result instead of a 404
-  error.
-
-* A backtracking_array plugin has been added, which makes matching
-  backtrack to the next entry in an array if a later matcher fails.
-  For example, the following code does not match /foo/bar by
-  default in Roda:
-
-    r.is ['foo', 'foo/bar'] do
-    end
-
-  This is because the 'foo' entry in the array matches, so the
-  array matches.  However, after the array is matched, the terminal
-  matcher added by r.is fails to match.  That causes the routing
-  method not to match the request, so the match block is not called.
-
-  With the backtracking_array plugin, failures of later matchers after
-  an array matcher backtrack so the next entry in the array is tried.
-
-* A per_thread_caching plugin has been added, allowing you to change
-  from a thread-safe shared cache to a per-thread cache, which may
-  be faster on alternative ruby implementations, at the cost of
-  additional memory usage.
-
-= New Features
-
-* The hash_matcher class method has been added to make it easier to
-  define custom hash matchers:
-
-    hash_matcher(:foo) do |v|
-      self['foo'] == v
-    end
-    
-    route do |r|
-      r.on :foo=>'bar' do
-        # matches when param foo has value bar
-      end
-    end
-
-* An r.root routing method has been added for handling GET
-  requests where the current path is /.  This is basically
-  a faster and simpler version of r.get "", except it does
-  not consume the / from the path.
-
-* The r.halt method now works without an argument, in which
-  case it uses the current response.
-
-* The r.redirect method now works without an argument for non-GET
-  requests, redirecting to the current path.
-
-* An :all hash matcher has been added, which takes an array and
-  matches only if all of the elements match.  This is mainly
-  designed for usage inside an array matcher, so:
-
-    r.on ["foo", {:all=>["bar", :id]}] do
-    end
-
-  will match either /foo or /bar/123, but not /bar.
-
-* The render plugin's view method now accepts a :content option,
-  in which case it uses the content directly without running it
-  through the template engine.  This is useful if you have
-  arbitrary content you want rendered inside the layout.
-
-* The render plugin now accepts an :escape option, in which case
-  it will automatically set the default :engine_class for erb
-  templates to an Erubis::EscapedEruby subclass.  This changes the
-  behavior of erb templates such that:
-
-    <%= '<escaped>' %> # &lt;escaped&gt;
-    <%== '<not escaped>' %> # <not escaped>
-
-  This makes it easier to protect against XSS attacks in your
-  templates, as long as you only use <%== %> for content that has
-  already been escaped.
-
-  Note that similar behavior is available in Erubis by default,
-  using the :opts=>{:escape_html=>true} render option, but that
-  doesn't handle postfix conditionals in <%= %> tags.
-
-* The multi_route plugin now has an r.multi_route method, which
-  will attempt to dispatch to one of the named routes based on
-  first segment in the path.  So this routing tree:
-
-    plugin :multi_route
-
-    route "a" do |r|
-      r.is "c" do
-        "e"
-      end
-    end
-    route "b" do |r|
-      r.is "d" do
-        "f"
-      end
-    end
-
-    route do |r|
-      r.multi_route
-    end
-
-  will return "e" for /a/c and "f" for /b/d.
-
-* Plugins can now override request and response class methods
-  using RequestClassMethods and ResponseClassMethods modules.
-
-= Optimizations
-
-* String, hash, and symbol matchers are now much faster by caching
-  the underlying regexp.
-
-* String, hash, and symbol matchers are now faster by using a
-  regexp positive lookahead assertion instead of an additional
-  capture.
-
-* Terminal matching in the r.is, r.get, and r.post routing methods
-  is now faster, as it does not use a hash matcher internally.
-
-* The routing methods are now faster by reducing the number of
-  Array objects created.
-
-* Calling routing methods without arguments is now faster.
-
-* The r.get method is now faster by reducing the number of string
-  allocations.
-
-* Many request methods are faster by reducing the number of
-  method calls used.
-
-* Template caching no longer uses a mutex on MRI, since one is
-  not needed for thread safety there.
-
-= Other Improvements
-
-* The flash plugin now implements its own flash hash instead of
-  using sinatra-flash.  It is now slightly faster and handles nil
-  keys in #keep and #discard.
-
-* Roda's version is now stored in roda/version.rb so that it can be
-  required without requiring Roda itself.
-
-= Backwards Compatibility
-
-* The multi_route plugin's route instance method has been changed
-  to a request method.  So the new usage is:
-
-    plugin :multi_route
-
-    route "a" do |r|
-    end
-
-    route do |r|
-      r.route "a" # instead of: route "a"
-    end
-
-* The session key used for the flash hash in the flash plugin is
-  now :_flash, not :flash.
-
-* The :extension matcher now longer forces a terminal match, use
-  one of the routing methods that forces a terminal match if you
-  want that behavior.
-
-* The :term hash matcher has been removed.
-
-* The r.consume private method now takes the exact regexp to use
-  to search the current path, it no longer enforces a preceeding
-  slash and that the match end on a segment boundary.
-
-* Dynamically constructing match patterns is now a potential
-  memory leak due to them being cached.  So you shouldn't do
-  things like:
-
-    r.on r['param'] do
-    end
-
-* Many private routing methods were changed or removed, if you were
-  using them, you'll probably need to update your code.

data/doc/release_notes/1.1.0.txt

@@ -1,226 +0,0 @@
-= New Plugins
-
-* An assets plugin has been added, for rendering your CSS and
-  javascript asset files on the fly in development, and compiling
-  them to a single, compressed file in production.
-
-  When loading the plugin, you just specify the assets to use via :css
-  and/or :js options:
-
-    plugin :assets, :css=>'some_file.scss', :js=>'some_file.coffee'
-
-  Inside your Roda.route block, you call r.assets to serve the assets:
-
-    route do |r|
-      r.assets
-    end
-
-  In your views, you can call the assets method, which returns strings
-  containing link/script tags for your assets:
-
-    <%= assets(:css) %>
-    <%= assets(:js) %>
-
-  In production mode, you call compile_assets after loading the
-  plugin, and it will compile all of the asset files into a single
-  file per type, optionally compress it (using yuicompressor), and
-  write the file to the public folder where it can be served by the
-  webserver.  In compiled mode, calling assets in your views will
-  reference the compiled file.
-
-  It's possible to precompile your assets before application boot, so
-  they don't need to be compiled every time your application boots.
-
-  The assets plugin also supports asset groups, useful when different
-  sections of your application use different sets of assets.
-
-* A chunked plugin has been added, for streaming template rendering
-  using Transfer-Encoding: chunked.  By default, this flushes the
-  rendering of the top part of the layout template before rendering
-  the content template, allowing the client to load the assets
-  necessary to fully render the page while the content template is
-  still being rendered on the server.  This can significantly decrease
-  client rendering times.
-
-  To use chunked encoding for a response, just call the chunked method
-  instead of view:
-
-    r.root do
-      chunked(:index)
-    end
-
-  If you want to execute code after flushing the top part of the layout
-  template, but before rendering the content template, pass a block to
-  chunked:
-
-    r.root do
-      chunked(:index) do
-        # expensive calculation here
-      end
-    end
-
-  If you want to use chunked encoding for all responses, pass the
-  :chunk_by_default option when loading the plugin:
-
-    plugin :chunked, :chunk_by_default => true
-
-  Inside your layout or content templates, you can call the flush method
-  to flush the current result of the template to the user, useful for
-  streaming large datasets.
-
-    <% (1..100).each do |i| %>
-      <%= i %>
-      <% sleep 0.1 %>
-      <% flush %>
-    <% end %>
-
-* A caching plugin has been added, for simple HTTP caching support.
-  The implementation is based on Sinatra's, and offers
-  r.last_modifed and r.etag methods for conditional responses:
-
-    r.get '/albums/:d' do |album_id|
-      @album = Album[album_id]
-      r.last_modified @album.updated_at
-      r.etag @album.sha1
-      view('album')
-    end
-
-  This also adds response.cache_control and response.expires methods
-  for setting the Cache-Control/Expires headers for the response.
-
-* A path plugin has been added for simple support for named paths:
-
-    plugin :path
-    path :foo, '/foo'   # foo_path => '/foo'
-    path :bar do |bar|  # bar_path(bar) => '/bar/1'
-      "/bar/#{bar.id}"
-    end
-  
-* An error_email plugin has been added, for easily emailing error
-  notifications for an exception.  This is designed for use with
-  the error_handler plugin, and should only be used in low-traffic
-  environments:
-
-    plugin :error_email, :to=>'to@example.com',
-                         :from=>'from@example.com'
-    plugin :error_handler do |e|
-      error_email(e)
-      'Internal Server Error'
-    end
-
-= multi_route Plugin Improvements
-
-* The multi_route plugin now supports namespaces, allowing it to
-  support routing trees of arbitrary complexity.  Previously, only
-  a single namespace was supported. For example, if you want
-  to store your named routes in a directory tree:
-
-    /routes/foo.rb
-    /routes/foo/baz.rb
-    /routes/foo/quux.rb
-    /routes/bar.rb
-    /routes/bar/baz.rb
-    /routes/bar/quux.rb
-
-  You can load all of the routing files in the routes subdirectory
-  tree, and structure your routing tree as follows:
-
-    # app.rb
-    route do |r|
-      r.multi_route
-    end
-
-    # routes/foo.rb
-    route('foo') do |r|
-      check_foo_access!
-      r.multi_route('foo')
-    end
-
-    # routes/bar.rb
-    route('bar') do |r|
-      check_bar_access!
-      r.multi_route('bar')
-    end
-
-    # routes/foo/baz.rb
-    route('baz', 'foo') do
-      # ...
-    end
-
-* Newly added named routes are now picked up while running, useful in
-  development when using code reloading.
-
-* r.multi_route now ignores non-String named routes, allowing you to
-  only dispatch to the String named routes.  Previously, calling
-  r.multi_route when any non-String names routes were present resulted
-  in an error.
-
-* r.multi_route now prefers longer routes to shorter routes if
-  routes have the same prefix.  This can fix behavior if you have
-  named routes such as "foo" and "foo/bar".
-
-* If you don't pass a block to r.multi_route, it will use the
-  return value of the named route as the block value to return,
-  instead of always returning nil.
-
-= Optimizations
-
-* Dispatch speed is slightly improved by using allocate instead of
-  new to create new instances.
-
-* Hash allocations in the render plugin have been reduced.
-
-= Other Improvements
-
-* The Roda.route block is now inherited when subclassing, making
-  it possible to subclass a Roda application and have the subclass
-  work without adding a route block.
-
-* Middleware added to a Roda app after the Roda.route method is
-  called are now used instead of being ignored.
-
-* A response.finish_with_body method has been added, for overriding
-  the response body to use.  This is useful if you want to support
-  arbitrary response bodies.
-
-* The render plugin now defaults the locals argument to an empty
-  frozen hash instead of nil when rendering templates via tilt.
-  This is faster as it avoids a hash allocation inside tilt, and
-  also works with broken external tilt templates that require that
-  the locals argument be a hash.
-
-* Plugins that ship with Roda no longer set constants inside
-  InstanceMethods.  Instead, the constants are set at the plugin
-  module level.  This is done to avoid polluting the namespace of
-  the application with the constants.  Roda's policy is that all
-  internal constants inside the Roda namespace are prefixed with
-  Roda, so they don't pollute the user's namespace, and setting
-  these constants inside InstanceMethods in plugins violated that
-  policy.
-
-= Backwards Compatibility
-
-* response.write no longer sets a Content-Length header.  Instead,
-  response.finish sets it.  This is faster if you call
-  response.write multiple times, and more correct if you call
-  response.finish without calling response.write.
-
-* In the render plugin, modifying render_opts directly is now
-  deprecated and will raise an error in the next major release (the
-  hash will be frozen).  Instead, users should call plugin :render
-  again with a new hash, which will be merged into the existing
-  render_opts hash.
-
-* Moving plugin's constants from InstanceMethods to the plugin level
-  can break applications where the constant was referenced directly.
-  For example, if you were doing:
-
-    Roda::SESSION_KEY
-
-  to get the constant for the session key, you would now need to use:
-
-    Roda::RodaPlugins::Base::SESSION_KEY
-
-  In general, it is recommended to not reference such constants at
-  all.  If you think there should be a general reason to access them,
-  request that a method is added that returns them.