actionpack 7.1.3.4 → 7.2.0.beta1

data/lib/action_dispatch/routing/polymorphic_routes.rb

@@ -1,104 +1,111 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionDispatch
   module Routing
-    # = Action Dispatch Routing \PolymorphicRoutes
+    # # Action Dispatch Routing PolymorphicRoutes
     #
-    # Polymorphic URL helpers are methods for smart resolution to a named route call when
-    # given an Active Record model instance. They are to be used in combination with
-    # ActionController::Resources.
+    # Polymorphic URL helpers are methods for smart resolution to a named route call
+    # when given an Active Record model instance. They are to be used in combination
+    # with ActionController::Resources.
     #
-    # These methods are useful when you want to generate the correct URL or path to a RESTful
-    # resource without having to know the exact type of the record in question.
+    # These methods are useful when you want to generate the correct URL or path to
+    # a RESTful resource without having to know the exact type of the record in
+    # question.
     #
-    # Nested resources and/or namespaces are also supported, as illustrated in the example:
+    # Nested resources and/or namespaces are also supported, as illustrated in the
+    # example:
     #
-    #   polymorphic_url([:admin, @article, @comment])
+    #     polymorphic_url([:admin, @article, @comment])
     #
     # results in:
     #
-    #   admin_article_comment_url(@article, @comment)
+    #     admin_article_comment_url(@article, @comment)
+    #
+    # ## Usage within the framework
     #
-    # == Usage within the framework
+    # Polymorphic URL helpers are used in a number of places throughout the Rails
+    # framework:
     #
-    # Polymorphic URL helpers are used in a number of places throughout the \Rails framework:
+    # *   `url_for`, so you can use it with a record as the argument, e.g.
+    #     `url_for(@article)`;
+    # *   ActionView::Helpers::FormHelper uses `polymorphic_path`, so you can write
+    #     `form_for(@article)` without having to specify `:url` parameter for the
+    #     form action;
+    # *   `redirect_to` (which, in fact, uses `url_for`) so you can write
+    #     `redirect_to(post)` in your controllers;
+    # *   ActionView::Helpers::AtomFeedHelper, so you don't have to explicitly
+    #     specify URLs for feed entries.
     #
-    # * <tt>url_for</tt>, so you can use it with a record as the argument, e.g.
-    #   <tt>url_for(@article)</tt>;
-    # * ActionView::Helpers::FormHelper uses <tt>polymorphic_path</tt>, so you can write
-    #   <tt>form_for(@article)</tt> without having to specify <tt>:url</tt> parameter for the form
-    #   action;
-    # * <tt>redirect_to</tt> (which, in fact, uses <tt>url_for</tt>) so you can write
-    #   <tt>redirect_to(post)</tt> in your controllers;
-    # * ActionView::Helpers::AtomFeedHelper, so you don't have to explicitly specify URLs
-    #   for feed entries.
     #
-    # == Prefixed polymorphic helpers
+    # ## Prefixed polymorphic helpers
     #
-    # In addition to <tt>polymorphic_url</tt> and <tt>polymorphic_path</tt> methods, a
-    # number of prefixed helpers are available as a shorthand to <tt>action: "..."</tt>
-    # in options. Those are:
+    # In addition to `polymorphic_url` and `polymorphic_path` methods, a number of
+    # prefixed helpers are available as a shorthand to `action: "..."` in options.
+    # Those are:
+    #
+    # *   `edit_polymorphic_url`, `edit_polymorphic_path`
+    # *   `new_polymorphic_url`, `new_polymorphic_path`
     #
-    # * <tt>edit_polymorphic_url</tt>, <tt>edit_polymorphic_path</tt>
-    # * <tt>new_polymorphic_url</tt>, <tt>new_polymorphic_path</tt>
     #
     # Example usage:
     #
-    #   edit_polymorphic_path(@post)           # => "/posts/1/edit"
-    #   polymorphic_path(@post, format: :pdf)  # => "/posts/1.pdf"
+    #     edit_polymorphic_path(@post)           # => "/posts/1/edit"
+    #     polymorphic_path(@post, format: :pdf)  # => "/posts/1.pdf"
     #
-    # == Usage with mounted engines
+    # ## Usage with mounted engines
     #
     # If you are using a mounted engine and you need to use a polymorphic_url
     # pointing at the engine's routes, pass in the engine's route proxy as the first
     # argument to the method. For example:
     #
-    #   polymorphic_url([blog, @post])  # calls blog.post_path(@post)
-    #   form_for([blog, @post])         # => "/blog/posts/1"
+    #     polymorphic_url([blog, @post])  # calls blog.post_path(@post)
+    #     form_for([blog, @post])         # => "/blog/posts/1"
     #
     module PolymorphicRoutes
-      # Constructs a call to a named RESTful route for the given record and returns the
-      # resulting URL string. For example:
+      # Constructs a call to a named RESTful route for the given record and returns
+      # the resulting URL string. For example:
+      #
+      #     # calls post_url(post)
+      #     polymorphic_url(post) # => "http://example.com/posts/1"
+      #     polymorphic_url([blog, post]) # => "http://example.com/blogs/1/posts/1"
+      #     polymorphic_url([:admin, blog, post]) # => "http://example.com/admin/blogs/1/posts/1"
+      #     polymorphic_url([user, :blog, post]) # => "http://example.com/users/1/blog/posts/1"
+      #     polymorphic_url(Comment) # => "http://example.com/comments"
       #
-      #   # calls post_url(post)
-      #   polymorphic_url(post) # => "http://example.com/posts/1"
-      #   polymorphic_url([blog, post]) # => "http://example.com/blogs/1/posts/1"
-      #   polymorphic_url([:admin, blog, post]) # => "http://example.com/admin/blogs/1/posts/1"
-      #   polymorphic_url([user, :blog, post]) # => "http://example.com/users/1/blog/posts/1"
-      #   polymorphic_url(Comment) # => "http://example.com/comments"
+      # #### Options
       #
-      # ==== Options
+      # *   `:action` - Specifies the action prefix for the named route: `:new` or
+      #     `:edit`. Default is no prefix.
+      # *   `:routing_type` - Allowed values are `:path` or `:url`. Default is `:url`.
       #
-      # * <tt>:action</tt> - Specifies the action prefix for the named route:
-      #   <tt>:new</tt> or <tt>:edit</tt>. Default is no prefix.
-      # * <tt>:routing_type</tt> - Allowed values are <tt>:path</tt> or <tt>:url</tt>.
-      #   Default is <tt>:url</tt>.
       #
-      # Also includes all the options from <tt>url_for</tt>. These include such
-      # things as <tt>:anchor</tt> or <tt>:trailing_slash</tt>. Example usage
-      # is given below:
+      # Also includes all the options from `url_for`. These include such things as
+      # `:anchor` or `:trailing_slash`. Example usage is given below:
       #
-      #   polymorphic_url([blog, post], anchor: 'my_anchor')
-      #     # => "http://example.com/blogs/1/posts/1#my_anchor"
-      #   polymorphic_url([blog, post], anchor: 'my_anchor', script_name: "/my_app")
-      #     # => "http://example.com/my_app/blogs/1/posts/1#my_anchor"
+      #     polymorphic_url([blog, post], anchor: 'my_anchor')
+      #       # => "http://example.com/blogs/1/posts/1#my_anchor"
+      #     polymorphic_url([blog, post], anchor: 'my_anchor', script_name: "/my_app")
+      #       # => "http://example.com/my_app/blogs/1/posts/1#my_anchor"
       #
-      # For all of these options, see the documentation for {url_for}[rdoc-ref:ActionDispatch::Routing::UrlFor].
+      # For all of these options, see the documentation for
+      # [url_for](rdoc-ref:ActionDispatch::Routing::UrlFor).
       #
-      # ==== Functionality
+      # #### Functionality
       #
-      #   # an Article record
-      #   polymorphic_url(record)  # same as article_url(record)
+      #     # an Article record
+      #     polymorphic_url(record)  # same as article_url(record)
       #
-      #   # a Comment record
-      #   polymorphic_url(record)  # same as comment_url(record)
+      #     # a Comment record
+      #     polymorphic_url(record)  # same as comment_url(record)
       #
-      #   # it recognizes new records and maps to the collection
-      #   record = Comment.new
-      #   polymorphic_url(record)  # same as comments_url()
+      #     # it recognizes new records and maps to the collection
+      #     record = Comment.new
+      #     polymorphic_url(record)  # same as comments_url()
       #
-      #   # the class of a record will also map to the collection
-      #   polymorphic_url(Comment) # same as comments_url()
+      #     # the class of a record will also map to the collection
+      #     polymorphic_url(Comment) # same as comments_url()
       #
       def polymorphic_url(record_or_hash_or_array, options = {})
         if Hash === record_or_hash_or_array

data/lib/action_dispatch/routing/redirection.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "active_support/core_ext/array/extract_options"
 require "rack/utils"
 require "action_controller/metal/exceptions"
@@ -146,55 +148,58 @@ module ActionDispatch
     module Redirection
       # Redirect any path to another path:
       #
-      #   get "/stories" => redirect("/posts")
+      #     get "/stories" => redirect("/posts")
       #
-      # This will redirect the user, while ignoring certain parts of the request, including query string, etc.
-      # <tt>/stories</tt>, <tt>/stories?foo=bar</tt>, etc all redirect to <tt>/posts</tt>.
+      # This will redirect the user, while ignoring certain parts of the request,
+      # including query string, etc. `/stories`, `/stories?foo=bar`, etc all redirect
+      # to `/posts`.
       #
-      # The redirect will use a <tt>301 Moved Permanently</tt> status code by
-      # default. This can be overridden with the +:status+ option:
+      # The redirect will use a `301 Moved Permanently` status code by default. This
+      # can be overridden with the `:status` option:
       #
-      #   get "/stories" => redirect("/posts", status: 307)
+      #     get "/stories" => redirect("/posts", status: 307)
       #
       # You can also use interpolation in the supplied redirect argument:
       #
-      #   get 'docs/:article', to: redirect('/wiki/%{article}')
+      #     get 'docs/:article', to: redirect('/wiki/%{article}')
       #
-      # Note that if you return a path without a leading slash then the URL is prefixed with the
-      # current SCRIPT_NAME environment variable. This is typically '/' but may be different in
-      # a mounted engine or where the application is deployed to a subdirectory of a website.
+      # Note that if you return a path without a leading slash then the URL is
+      # prefixed with the current SCRIPT_NAME environment variable. This is typically
+      # '/' but may be different in a mounted engine or where the application is
+      # deployed to a subdirectory of a website.
       #
       # Alternatively you can use one of the other syntaxes:
       #
-      # The block version of redirect allows for the easy encapsulation of any logic associated with
-      # the redirect in question. Either the params and request are supplied as arguments, or just
-      # params, depending of how many arguments your block accepts. A string is required as a
-      # return value.
+      # The block version of redirect allows for the easy encapsulation of any logic
+      # associated with the redirect in question. Either the params and request are
+      # supplied as arguments, or just params, depending of how many arguments your
+      # block accepts. A string is required as a return value.
       #
-      #   get 'jokes/:number', to: redirect { |params, request|
-      #     path = (params[:number].to_i.even? ? "wheres-the-beef" : "i-love-lamp")
-      #     "http://#{request.host_with_port}/#{path}"
-      #   }
+      #     get 'jokes/:number', to: redirect { |params, request|
+      #       path = (params[:number].to_i.even? ? "wheres-the-beef" : "i-love-lamp")
+      #       "http://#{request.host_with_port}/#{path}"
+      #     }
       #
-      # Note that the <tt>do end</tt> syntax for the redirect block wouldn't work, as Ruby would pass
-      # the block to +get+ instead of +redirect+. Use <tt>{ ... }</tt> instead.
+      # Note that the `do end` syntax for the redirect block wouldn't work, as Ruby
+      # would pass the block to `get` instead of `redirect`. Use `{ ... }` instead.
       #
-      # The options version of redirect allows you to supply only the parts of the URL which need
-      # to change, it also supports interpolation of the path similar to the first example.
+      # The options version of redirect allows you to supply only the parts of the URL
+      # which need to change, it also supports interpolation of the path similar to
+      # the first example.
       #
-      #   get 'stores/:name',       to: redirect(subdomain: 'stores', path: '/%{name}')
-      #   get 'stores/:name(*all)', to: redirect(subdomain: 'stores', path: '/%{name}%{all}')
-      #   get '/stories', to: redirect(path: '/posts')
+      #     get 'stores/:name',       to: redirect(subdomain: 'stores', path: '/%{name}')
+      #     get 'stores/:name(*all)', to: redirect(subdomain: 'stores', path: '/%{name}%{all}')
+      #     get '/stories', to: redirect(path: '/posts')
       #
-      # This will redirect the user, while changing only the specified parts of the request,
-      # for example the +path+ option in the last example.
-      # <tt>/stories</tt>, <tt>/stories?foo=bar</tt>, redirect to <tt>/posts</tt> and <tt>/posts?foo=bar</tt> respectively.
+      # This will redirect the user, while changing only the specified parts of the
+      # request, for example the `path` option in the last example. `/stories`,
+      # `/stories?foo=bar`, redirect to `/posts` and `/posts?foo=bar` respectively.
       #
-      # Finally, an object which responds to call can be supplied to redirect, allowing you to reuse
-      # common redirect routes. The call method must accept two arguments, params and request, and return
-      # a string.
+      # Finally, an object which responds to call can be supplied to redirect,
+      # allowing you to reuse common redirect routes. The call method must accept two
+      # arguments, params and request, and return a string.
       #
-      #   get 'accounts/:name' => redirect(SubdomainRedirector.new('api'))
+      #     get 'accounts/:name' => redirect(SubdomainRedirector.new('api'))
       #
       def redirect(*args, &block)
         options = args.extract_options!

data/lib/action_dispatch/routing/route_set.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "action_dispatch/journey"
 require "active_support/core_ext/object/to_query"
 require "active_support/core_ext/module/redefine_method"
@@ -10,12 +12,28 @@ require "action_dispatch/routing/endpoint"
 
 module ActionDispatch
   module Routing
-    # :stopdoc:
+    # The RouteSet contains a collection of Route instances, representing the routes
+    # typically defined in `config/routes.rb`.
     class RouteSet
-      # Since the router holds references to many parts of the system
-      # like engines, controllers and the application itself, inspecting
-      # the route set can actually be really slow, therefore we default
-      # alias inspect to to_s.
+      # Returns a Route matching the given requirements, or `nil` if none are found.
+      #
+      # This is intended for use by tools such as Language Servers.
+      #
+      # Given the routes are defined as:
+      #
+      #   resources :posts
+      #
+      # Then the following will return the Route for the `show` action:
+      #
+      #   Rails.application.routes.from_requirements(controller: "posts", action: "show")
+      def from_requirements(requirements)
+        routes.find { |route| route.requirements == requirements }
+      end
+      # :stopdoc:
+
+      # Since the router holds references to many parts of the system like engines,
+      # controllers and the application itself, inspecting the route set can actually
+      # be really slow, therefore we default alias inspect to to_s.
       alias inspect to_s
 
       class Dispatcher < Routing::Endpoint
@@ -144,8 +162,8 @@ module ActionDispatch
           routes.length
         end
 
-        # Given a +name+, defines name_path and name_url helpers.
-        # Used by 'direct', 'resolve', and 'polymorphic' route helpers.
+        # Given a `name`, defines name_path and name_url helpers. Used by 'direct',
+        # 'resolve', and 'polymorphic' route helpers.
         def add_url_helper(name, defaults, &block)
           helper = CustomUrlHelper.new(name, defaults, &block)
           path_name = :"#{name}_path"
@@ -301,18 +319,18 @@ module ActionDispatch
         end
 
         private
-          # Create a URL helper allowing ordered parameters to be associated
-          # with corresponding dynamic segments, so you can do:
+          # Create a URL helper allowing ordered parameters to be associated with
+          # corresponding dynamic segments, so you can do:
           #
-          #   foo_url(bar, baz, bang)
+          #     foo_url(bar, baz, bang)
           #
           # Instead of:
           #
-          #   foo_url(bar: bar, baz: baz, bang: bang)
+          #     foo_url(bar: bar, baz: baz, bang: bang)
           #
           # Also allow options hash, so you can do:
           #
-          #   foo_url(bar, baz, bang, sort_by: 'baz')
+          #     foo_url(bar, baz, bang, sort_by: 'baz')
           #
           def define_url_helper(mod, name, helper, url_strategy)
             mod.define_method(name) do |*args|
@@ -386,6 +404,7 @@ module ActionDispatch
       def eager_load!
         router.eager_load!
         routes.each(&:eager_load!)
+        formatter.eager_load!
         nil
       end
 
@@ -470,10 +489,9 @@ module ActionDispatch
         include UrlFor
       end
 
-      # Contains all the mounted helpers across different
-      # engines and the `main_app` helper for the application.
-      # You can include this in your classes if you want to
-      # access routes for other engines.
+      # Contains all the mounted helpers across different engines and the `main_app`
+      # helper for the application. You can include this in your classes if you want
+      # to access routes for other engines.
       def mounted_helpers
         MountedHelpers
       end
@@ -563,13 +581,11 @@ module ActionDispatch
 
           url_helpers = routes.named_routes.url_helpers_module
 
-          # Make named_routes available in the module singleton
-          # as well, so one can do:
+          # Make named_routes available in the module singleton as well, so one can do:
           # Rails.application.routes.url_helpers.posts_path
           extend url_helpers
 
-          # Any class that includes this module will get all
-          # named routes...
+          # Any class that includes this module will get all named routes...
           include url_helpers
 
           if supports_path
@@ -584,9 +600,8 @@ module ActionDispatch
             redefine_singleton_method(:_routes) { routes }
           end
 
-          # And an instance method _routes. Note that
-          # UrlFor (included in this module) add extra
-          # conveniences for working with @_routes.
+          # And an instance method _routes. Note that UrlFor (included in this module) add
+          # extra conveniences for working with @_routes.
           define_method(:_routes) { @_routes || routes }
 
           define_method(:_generate_paths_by_default) do
@@ -595,12 +610,12 @@ module ActionDispatch
 
           private :_generate_paths_by_default
 
-          # If the module is included more than once (for example, in a subclass
-          # of an ancestor that includes the module), ensure that the `_routes`
-          # singleton and instance methods return the desired route set by
-          # including a new copy of the module (recursively if necessary). Note
-          # that this method is called for each inclusion, whereas the above
-          # `included` block is run only for the initial inclusion of each copy.
+          # If the module is included more than once (for example, in a subclass of an
+          # ancestor that includes the module), ensure that the `_routes` singleton and
+          # instance methods return the desired route set by including a new copy of the
+          # module (recursively if necessary). Note that this method is called for each
+          # inclusion, whereas the above `included` block is run only for the initial
+          # inclusion of each copy.
           def self.included(base)
             super
             if base.respond_to?(:_routes) && !base._routes.equal?(@_proxy._routes)
@@ -716,14 +731,14 @@ module ActionDispatch
         end
 
         def normalize_options!
-          # If an explicit :controller was given, always make :action explicit
-          # too, so that action expiry works as expected for things like
+          # If an explicit :controller was given, always make :action explicit too, so
+          # that action expiry works as expected for things like
           #
-          #   generate({controller: 'content'}, {controller: 'content', action: 'show'})
+          #     generate({controller: 'content'}, {controller: 'content', action: 'show'})
           #
-          # (the above is from the unit tests). In the above case, because the
-          # controller was explicitly given, but no action, the action is implied to
-          # be "index", not the recalled action of "show".
+          # (the above is from the unit tests). In the above case, because the controller
+          # was explicitly given, but no action, the action is implied to be "index", not
+          # the recalled action of "show".
 
           if options[:controller]
             options[:action]     ||= "index"
@@ -735,10 +750,9 @@ module ActionDispatch
           end
         end
 
-        # This pulls :controller, :action, and :id out of the recall.
-        # The recall key is only used if there is no key in the options
-        # or if the key in the options is identical. If any of
-        # :controller, :action or :id is not found, don't pull any
+        # This pulls :controller, :action, and :id out of the recall. The recall key is
+        # only used if there is no key in the options or if the key in the options is
+        # identical. If any of :controller, :action or :id is not found, don't pull any
         # more keys from the recall.
         def normalize_controller_action_id!
           use_recall_for(:controller) || return
@@ -746,8 +760,8 @@ module ActionDispatch
           use_recall_for(:id)
         end
 
-        # if the current controller is "foo/bar/baz" and controller: "baz/bat"
-        # is specified, the controller becomes "foo/baz/bat"
+        # if the current controller is "foo/bar/baz" and controller: "baz/bat" is
+        # specified, the controller becomes "foo/baz/bat"
         def use_relative_controller!
           if !named_route && different_controller? && !controller.start_with?("/")
             old_parts = current_controller.split("/")
@@ -789,8 +803,8 @@ module ActionDispatch
           end
       end
 
-      # Generate the path indicated by the arguments, and return an array of
-      # the keys that were not used to generate it.
+      # Generate the path indicated by the arguments, and return an array of the keys
+      # that were not used to generate it.
       def extra_keys(options, recall = {})
         generate_extras(options, recall).last
       end
@@ -827,7 +841,7 @@ module ActionDispatch
         url_for(options, route_name, PATH, nil, reserved)
       end
 
-      # The +options+ argument must be a hash whose keys are *symbols*.
+      # The `options` argument must be a hash whose keys are **symbols**.
       def url_for(options, route_name = nil, url_strategy = UNKNOWN, method_name = nil, reserved = RESERVED_OPTIONS)
         options = default_url_options.merge options
 
@@ -860,7 +874,7 @@ module ActionDispatch
         params = route_with_params.params
 
         if options.key? :params
-          if options[:params]&.respond_to?(:to_hash)
+          if options[:params].respond_to?(:to_hash)
             params.merge! options[:params]
           else
             params[:params] = options[:params]

data/lib/action_dispatch/routing/routes_proxy.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "active_support/core_ext/array/extract_options"
 
 module ActionDispatch
@@ -46,10 +48,10 @@ module ActionDispatch
         end
       end
 
-      # Keeps the part of the script name provided by the global
-      # context via ENV["SCRIPT_NAME"], which `mount` doesn't know
-      # about since it depends on the specific request, but use our
-      # script name resolver for the mount point dependent part.
+      # Keeps the part of the script name provided by the global context via
+      # [ENV]("SCRIPT_NAME"), which `mount` doesn't know about since it depends on the
+      # specific request, but use our script name resolver for the mount point
+      # dependent part.
       def merge_script_names(previous_script_name, new_script_name)
         return new_script_name unless previous_script_name