roda 2.28.0 → 2.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ca75e717d558d6b3c163517c6e8e3678a33b68e0
-  data.tar.gz: a08ab3922fc609e9413f6151444bc9a92186777e
+  metadata.gz: e11c20c0c5dfda417dafc01b68c10915e59abf04
+  data.tar.gz: edd6bd09207b2f8e15f78b9c9ada35285003ff0d
 SHA512:
-  metadata.gz: 29684100b4d5dd39d11e034a9158442b9e7379c11fe8c0169033fab127394855e79016aa0101f7abdb79cc544dbfcedc98c0fa3fd6fad7559678ab43f69b9dbe
-  data.tar.gz: 77d6d7bb57535d375a46103b4ba5f803231172ecf6b98cdc3ebba85600be1e02dfe06dc907758ffbdbe6123911f436e15fbf87fe3c2a4f2d4a0742a36af94471
+  metadata.gz: a82a396922fc18b9d69551ff405cade3d51e09d5eb518c70bc3166b4214d70692412f91e59c4e31a9fec84e948c93bec3a1a7a066584bd1c5585b39fc57b2c15
+  data.tar.gz: 4690e25684a1264e29c3c60426263a5631716080de3e699785e193bd96868a9c4788b8aa17ca97fbecacf1db96a39146bb33bc0db23e1398c8d79c2ab3ab34da

data/CHANGELOG

@@ -1,3 +1,49 @@
+= 2.29.0 (2017-08-16)
+
+* Deprecate accessing multi_route namespace when there are no routes (jeremyevans)
+
+* Deprecate additional internal constants (jeremyevans)
+
+* Respect :root app option when using :layout_opts=>:views render plugin option (jeremyevans)
+
+* Deprecate rendering templates outside of render plugin :allowed_paths option by default (jeremyevans)
+
+* Deprecate :cache=>nil/false render plugin option overriding :cache render/view method option (jeremyevans)
+
+* Deprecate using :header matcher in header_matchers plugin without :header_matcher_prefix app option (jeremyevans)
+
+* Deprecate using content_for multiple times with the same key in the content_for plugin unless :append plugin option is used (jeremyevans)
+
+* Deprecate use of :host matcher with regexp value in header_matchers plugin without :host_matcher_captures app option (jeremyevans)
+
+* Deprecate view_options plugin locals handling, move to the new branch_locals plugin (jeremyevans)
+
+* Deprecate render plugin locals handling, move to the new render_locals plugin (jeremyevans)
+
+* Deprecate the :ext render method and plugin option (jeremyevans)
+
+* Deprecate the view_subdirs plugin alias for the view_options plugin (jeremyevans)
+
+* Deprecate Stream#callback in the streaming plugin (jeremyevans)
+
+* Deprecate the automatic support for EventMachine in the streaming plugin (jeremyevans)
+
+* Deprecate static_path_info plugin, which has been a no-op in Roda 2 (jeremyevans)
+
+* Deprecate render plugin :escape option loading Erubis escaping support (jeremyevans)
+
+* Deprecate the per_thread_caching plugin (jeremyevans)
+
+* Deprecate the websockets plugin (jeremyevans)
+
+* Deprecate treating unsupported matchers as always matching (jeremyevans)
+
+* Deprecate ignoring unsupported match block return values (jeremyevans)
+
+* Deprecate the :format, :opt, and :optd default symbol matchers in the symbol_matchers plugin (jeremyevans)
+
+* Deprecate use of placeholders in string matchers by default, add placeholder_string_matchers plugin for it (jeremyevans)
+
 = 2.28.0 (2017-07-14)
 
 * Deprecate unneeded internal constants (jeremyevans)

data/README.rdoc

@@ -285,7 +285,7 @@ If a string contains any slashes, it matches one additional segment for each sla
   "foo/bar" # matches "/foo/bar"
   "foo/bar" # does not match "/foo/bard"
 
-For backwards compatibility, if a string contains a colon followed by any
+While deprecated by default, if a string contains a colon followed by any
 <tt>\\w</tt> characters, the colon and remaining <tt>\\w</tt> characters match any
 nonempty segment that contains at least one character:
 
@@ -303,8 +303,9 @@ symbol arguments, as it is faster and simpler:
   "foo", String # instead of "foo/:id"
   String, String     # instead of ":x/:y"
 
-It is possible in future versions of Roda, colons will not be treated specially
-in strings, and will just match a literal colon character.
+You can load the placeholder_string_matchers plugin to allow placeholders in
+strings without a deprecation warning.  The deprecated default handling of placeholders
+in strings will be removed in Roda 3.
 
 Note that other than colons followed by a <tt>\\w</tt> character, strings do no
 handle regular expression syntax, they are matched verbatim:
@@ -437,9 +438,8 @@ If +false+ or +nil+ is given directly as a matcher, it doesn't match anything.
 
 === Everything else
 
-Everything else matches anything.  Note that future versions of Roda will probably
-raise exceptions for unsupported matchers, so it is not recommended to rely on this
-behavior.
+Everything else matches anything, but such usage is deprecated.  In Roda 3, using
+an unsupported matcher will raise an error.
 
 == Optional segments
 
@@ -485,7 +485,25 @@ An alternative way to implement this is via a regexp:
   r.is "items", /(\d+)(?:\/(\d+))?/ do |item_id, optional_data|
   end
 
-== Status codes
+== Match/Route Block Return Values
+
+If the response body has already been written to by calling +response.write+
+directly, then any return value of a match block or route block is ignored.
+
+If the response body has not already been written to, then the match block
+or route block return value is inspected:
+
+String :: used as the response body
+nil, false :: ignored
+everything else :: also ignored, but this is deprecated and will raise an
+                   error starting in Roda 3
+
+Plugins can add support for additional match block and route block return
+values.  One example of this is the json plugin, which allows returning
+arrays and hashes in match and route blocks and converts those directly
+to JSON and uses the JSON as the response body.
+
+== Status Codes
 
 When it comes time to finalize a response,
 if a status code has not been set manually and anything has been written to the response,

data/doc/release_notes/2.29.0.txt

@@ -0,0 +1,156 @@
+= Deprecated Features
+
+Roda 2.29.0 will be the last minor release of Roda 2.  Roda 3.0.0
+will be released next month and will remove support for the following
+deprecated features.  All of these features will have deprecation
+warnings if used in Roda 2.29.0.
+
+* The use of placeholders in string matchers is now deprecated.
+  So code such as:
+
+    r.get "users/:user_id" do |id|
+    end
+
+  should be switched to using a class matcher such as String or
+  Integer:
+
+    r.get "users", Integer do |id|
+    end
+
+  or a symbol matcher:
+
+    r.get "users", :user_id do |id|
+    end
+
+  If you really want to keep support for placeholders in string
+  matchers, the support is available in the new
+  placeholder_string_matchers plugin.
+
+* The :format, :opt, and :optd default symbol matchers are now
+  deprecated in the symbol_matchers plugin.  These matchers
+  only made sense when placeholder string matchers are used,
+  which will no longer be the default behavior in Roda 3. These
+  methods can be defined manually if you are going to use the
+  placeholder_string_matchers plugin and still want to use
+  these symbol matchers:
+
+    symbol_matcher(:format, /(?:\.(\w+))?/)
+    symbol_matcher(:opt, /(?:\/([^\/]+))?/)
+    symbol_matcher(:optd, /(?:\/(\d+))?/)
+
+* Ignoring unsupported match block return values is now deprecated.
+  Doing so can hide errors and make debugging more difficult.  If you
+  get a deprecation warning related to this, just make sure the match
+  block returns nil or false to specify the match block return value
+  should be ignored.
+
+* Treating unsupported matchers as always matching is now deprecated.
+  Doing so can hide errors and make debugging more difficult. If you
+  get a deprecation warning related to this, switch the matcher to
+  true instead of an unsupported object.
+
+* The render plugin's handling of plugin level locals and merging of
+  template and layout locals is now deprecated.  Users of these
+  features should switch to the new render_locals plugin.
+
+* The view_options plugin's handling of per-branch view and layout
+  locals is now deprecated.  Users of these feature should switch to
+  the new branch_locals plugin.
+
+* The render plugin's support for Erubis escaping is now deprecated.
+  In Roda 3, the render plugin :escape option will use Erubi escaping.
+  Switch to using :escape=>:erubi temporarily to avoid the deprecation
+  warning.
+
+* Using the render plugin to render a template that is outside one of
+  the allowed paths is now deprecated unless the :check_paths option
+  has been set to false.  In Roda 3, the default behavior will change
+  to checking that template files are in one of the allowed paths.
+
+* The :ext option in the render plugin is now deprecated, users should
+  switch to using the :engine option, which has always had priority.
+
+* Using the :cache=>true option to the view/render method in the
+  render plugin is now deprecated if the :cache=>nil/false option
+  was given when loading the plugin.  In Roda 3, the default behavior
+  will change so that the :cache=>nil/false plugin option still
+  allows caching via the :cache=>true method option.  Users can use
+  the :explicit_cache=>true render plugin option instead of the
+  :cache=>nil render plugin option to work around the deprecation
+  warning.
+
+* Attempting to use multi_route while routing with a namespace that
+  hasn't yet been defined is now deprecated.  The previous behavior
+  was to ignore undefined namespaces, but that is more likely to
+  hide an error than be desired behavior.  In Roda 3, using an
+  undefined namespace will raise an error.
+
+* The streaming plugin's support for EventMachine is now deprecated,
+  as is related support for Stream#callback.  The streaming plugin
+  will be much simpler in Roda 3 by dropping this support.
+
+* Calling content_for in the content_for plugin multiple times with
+  the same argument is now deprecated unless the content_for
+  plugin :append option is used to specify behavior.  The default
+  behavior in Roda 3 will change to appending to the existing
+  content instead of overwriting the existing content.
+
+* The :host matcher in the header_matchers plugin is now deprecated
+  when using a regexp value unless the :host_matcher_captures app
+  option is used.  In Roda 3, the :host matcher will automatically
+  yield any regexp captures to the match block.
+
+* The :header matcher in the header_matchers plugin is now deprecated
+  unless the :header_matcher_prefix app option is used.  In Roda 3,
+  the :header matcher will always prefix the argument given with
+  HTTP_.
+
+* The websockets plugin is now deprecated.  It was one of the less
+  commonly used plugins, and the tests for it were subject to race
+  conditions and failed occassionally, and even when they worked
+  they almost doubled the testing time.  Anyone wanting to use it
+  should consider maintaining it as an external plugin.
+
+* The per_thread_caching, static_path_info, and view_subdirs
+  plugins are now deprecated.  static_path_info has been a no-op since
+  Roda 3, view_subdirs is just an alias for view_options, and
+  per_thread_caching doesn't change behavior and is unlikely to
+  significantly increase performance.
+
+* Additional internal constants are now deprecated. Deprecation
+  warnings for accessing these constants will only be displayed on
+  ruby 2.3+.
+
+= Forward Compatibility
+
+Roda 3.0.0 will also include some behavior changes which will not
+have deprecation warnings:
+
+* Ruby 1.8.7 support will be dropped.  Ruby 1.9.2 will be the new
+  minimum supported version.
+
+* Subclassing a Roda app that uses the render plugin will always
+  use a copy of the superclass's template cache.
+
+* The assets plugin will default to using subresource integrity
+  using SHA256 for compiled assets, and using SHA256 instead of
+  SHA1 for compiled asset hashes.
+
+* Using an Roda app as middleware will now always use a subclass
+  of the app for the middleware.
+
+* public_send will be used instead of send internally unless it is
+  expected that private methods will be called.
+
+* The match methods added by the symbol_matchers and hash_matchers
+  plugins will be private instead of public.
+
+= New Features
+
+* The render plugin now has the :layout_opts=>:views plugin option
+  respect the :root app option.
+
+* RodaPlugins::OPTS and RodaPlugins::EMPTY_ARRAY have been added.
+  These are a frozen empty hash and a frozen empty array, and
+  they are designed for use in plugins so that similar objects are
+  not needed to be defined separately in each plugin.

data/lib/roda.rb

@@ -65,9 +65,19 @@ class Roda
   # Module in which all Roda plugins should be stored. Also contains logic for
   # registering and loading plugins.
   module RodaPlugins
+    OPTS = {}.freeze
+    EMPTY_ARRAY = [].freeze
+
     # Stores registered plugins
     @plugins = RodaCache.new
 
+    class << self
+      # Make warn a public method, as it is used for deprecation warnings.
+      # Roda::RodaPlugins.warn can be overridden for custom handling of
+      # deprecation warnings.
+      public :warn
+    end
+
     # If the registered plugin already exists, use it.  Otherwise,
     # require it and return it.  This raises a LoadError if such a
     # plugin doesn't exist, or a RodaError if it exists but it does
@@ -740,7 +750,16 @@ class Roda
         # colon tokens for placeholders.
         def _match_string(str)
           if str.index(":") && placeholder_string_matcher?
-            consume(self.class.cached_matcher(str){Regexp.escape(str).gsub(/:(\w+)/){|m| _match_symbol_regexp($1)}})
+            # RODA3: Remove
+            not_warned = true
+            consume(self.class.cached_matcher(str){Regexp.escape(str).gsub(/:(\w+)/) do |m|
+              match = $1
+              if not_warned
+                nor_warned = false
+                RodaPlugins.warn("Placeholder symbol matchers are deprecated by default and will be removed in Roda 3 (matcher used: #{str.inspect}). Use the placeholder_symbol_matchers plugin or split the string and use separate symbol matchers or String class matchers for the placeholders")
+              end
+              _match_symbol_regexp(match)
+            end})
           else
             rp = @remaining_path
             if rp.start_with?("/#{str}")
@@ -752,6 +771,7 @@ class Roda
                 @remaining_path = ""
               when Integer
                 # :nocov:
+                # RODA3: Remove
                 # Ruby 1.8 support
                 if rp[last].chr == "/"
                   @remaining_path = rp[last, rp.length]
@@ -781,8 +801,7 @@ class Roda
         # Match any nonempty segment.  This should be called without an argument.
         alias _match_class_String _match_symbol
 
-        # The regular expression to use for matching symbols.  By default, any non-empty
-        # segment matches.
+        # RODA3: Remove
         def _match_symbol_regexp(s)
           "([^\\/]+)"
         end
@@ -821,6 +840,8 @@ class Roda
           else
             if roda_class.opts[:unsupported_block_result] == :raise
               raise RodaError, "unsupported block result: #{result.inspect}"
+            else
+              RodaPlugins.warn("Unsupported match block return result: #{result.inspect}.  This is currently ignored, but will raise an error in Roda 3.  Have the block return nil or false to ignore the result.")
             end
           end
         end
@@ -933,6 +954,7 @@ class Roda
           if roda_class.opts[:unsupported_matcher] == :raise
             raise RodaError, "unsupported matcher: #{matcher.inspect}"
           end
+          RodaPlugins.warn("Unsupported matcher used: #{matcher.inspect}.  This currently always matches, but will raise an error in Roda 3.  Switch to using true if you want the matcher to always match.")
           matcher
         end
       end

data/lib/roda/plugins/_erubis_escaping.rb

@@ -4,6 +4,8 @@ require 'erubis'
 
 class Roda
   module RodaPlugins
+    warn 'Using the render plugin :escape option for Erubis escaping support is deprecated.  In Roda 3, the :escape option will use Erubi escaping support.  You can turn on the Roda 3 behavior by using :escape=>:erubi.'
+
     # The _erubis_escaping plugin handles escaping of <tt><%= %></tt> inside
     # ERB templates.  It is an internal plugin that should not be loaded
     # directlyn by user code.

data/lib/roda/plugins/_symbol_regexp_matchers.rb

@@ -0,0 +1,22 @@
+# frozen-string-literal: true
+
+#
+class Roda
+  module RodaPlugins
+    # The _symbol_regexp_matchers plugin is designed for internal use by other plugins,
+    # for the historical behavior of a symbol matching an arbitrary segment by default
+    # using a regexp.
+    module SymbolRegexpMatchers
+      module RequestMethods
+        # The regular expression to use for matching symbols.  By default, any non-empty
+        # segment matches.
+        def _match_symbol_regexp(s)
+          "([^\\/]+)"
+        end
+      end
+    end
+
+    register_plugin(:_symbol_regexp_matchers, SymbolRegexpMatchers)
+  end
+end
+

data/lib/roda/plugins/assets.rb

@@ -306,8 +306,9 @@ class Roda
         :compiled_css_dir => nil,
         :compiled_js_dir  => nil,
       }.freeze
-      EMPTY_ATTRS = {}.freeze
 
+      EMPTY_ATTRS = {}.freeze
+      RodaPlugins.deprecate_constant(self, :EMPTY_ATTRS)
       JS_END = "\"></script>".freeze
       RodaPlugins.deprecate_constant(self, :JS_END)
       CSS_END = "\" />".freeze
@@ -656,7 +657,7 @@ class Roda
         # When the assets are not compiled, this will result in a separate
         # tag for each asset file.  When the assets are compiled, this will
         # result in a single tag to the compiled asset file.
-        def assets(type, attrs = EMPTY_ATTRS)
+        def assets(type, attrs = OPTS)
           ltype = type.is_a?(Array) ? type[0] : type
 
           o = self.class.assets_opts

data/lib/roda/plugins/branch_locals.rb

@@ -0,0 +1,74 @@
+# frozen-string-literal: true
+
+#
+class Roda
+  module RodaPlugins
+    # The branch_locals plugin allows you to override view and layout
+    # locals for specific branches and routes.
+    #
+    #   plugin :render
+    #   plugin :render_locals, :render=>{:footer=>'Default'}, :layout=>{:title=>'Main'}
+    #   plugin :branch_locals
+    #
+    #   route do |r|
+    #     r.on "users" do
+    #       set_layout_locals :title=>'Users'
+    #       set_view_locals :footer=>'(c) Roda'
+    #     end
+    #   end
+    #
+    # The locals you specify in the set_layout_locals and set_view_locals methods
+    # have higher precedence than the render_locals plugin options, but lower precedence
+    # than options you directly pass to the view/render methods.
+    module BranchLocals
+      # Load the render_locals plugin before this plugin, since this plugin
+      # works by overriding methods in the render_locals plugin.
+      def self.load_dependencies(app)
+        app.plugin :render_locals
+      end
+
+      module InstanceMethods
+        # Update the default layout locals to use in this branch.
+        def set_layout_locals(opts)
+          if locals = @_layout_locals
+            @_layout_locals = Hash[locals].merge!(opts)
+          else
+            @_layout_locals = opts
+          end
+        end
+
+        # Update the default view locals to use in this branch.
+        def set_view_locals(opts)
+          if locals = @_view_locals
+            @_view_locals = Hash[locals].merge!(opts)
+          else
+            @_view_locals = opts
+          end
+        end
+
+        private
+
+        # Make branch specific view locals override render_locals plugin defaults.
+        def render_locals
+          locals = super
+          if @_view_locals
+            locals = Hash[locals].merge!(@_view_locals)
+          end
+          locals
+        end
+
+        # Make branch specific layout locals override render_locals plugin defaults.
+        def layout_locals
+          locals = super
+          if @_view_locals
+            locals = Hash[locals].merge!(@_layout_locals)
+          end
+          locals
+        end
+      end
+    end
+
+    register_plugin(:branch_locals, BranchLocals)
+  end
+end
+