sensible_routes 0.0.4 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5b2b6d14f70eb338bdd255790623beca7edf1c78
-  data.tar.gz: 6dff7a06c8524339679489b0a13fec5f4100a26c
+  metadata.gz: dfd1aaef7634b1e7600e7182b5e7b7d4995e57fa
+  data.tar.gz: abfceb1ddc01aae9e6c412fdf1e4c45819631f36
 SHA512:
-  metadata.gz: 58ede276c02d1e49b8113a875f0248681652327b76d145a4d2d8bee97a19ad4b6a0894dfe2929c75a7131d8b2aef4483fd514ce26a6b42666421a34883b0f543
-  data.tar.gz: cdc09925a68c5eb1086f6faed37ea39cb11915bd36d790cd79b68168aeeb5a197d50c47d8c3715c196d742b5462353fcab6da390345dfaa4861161309015f155
+  metadata.gz: 6ca1e8254e6b61b32e404c3bbf49c745335a4311f266d668359645bad782acf7265025a341bfd5cd86f85e949974b87c523348dd16393a1f90429ab203af19a0
+  data.tar.gz: 31baf0a4a3aab003ac013ef94148f7743699794b82da87e7e602188daeb4e96ed2b1c15753877944aeaabf0ecf6dc97bff58c560b5e6a203f3b5ee2a6c9859e0

data/README.md

@@ -1,39 +1,29 @@
-# Sensible::Routes
+# `sensible_routes`
+Simple and comprehensible route introspection library for Rails.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/sensible/routes`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+## Huh?
+In a stock Rails app, `rake routes` is essentially the only way to get any introspection of routes. There's no programmatic access to them in detail,
+beyond basic route helpers. This gem aims to make detailed programmatic introspection possible.
 
 ## Installation
+Add the following line to your Gemfile and run `bundle install`:
 
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'sensible-routes'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install sensible-routes
+    gem 'sensible_routes'
+    
+Then, create a new initializer (say `config/initializers/sensible_routes.rb`), with this as its only content:
 
+    SensibleRoute.hook_rails
+    
 ## Usage
+At a basic level, you can get a list of your application's routes in a useful form with this:
 
-TODO: Write usage instructions here
+    Rails.sensible_routes
+    
+That returns a SensibleRouteCollection, which is array-like in that it responds to many of the same methods. You can also filter the collection down
+further - see the API documentation for full details.
 
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/sensible-routes.
+## Contributions
+Welcome. Ping me a PR. For large changes you should probably open an issue first to discuss.
 
 ## License
-
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Available under the terms of the MIT license.

data/lib/sensible_routes/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class SensibleRoutes
-  VERSION = '0.0.4'
+  VERSION = '0.1.0'
 end

data/lib/sensible_routes.rb

@@ -1,8 +1,16 @@
 # frozen_string_literal: true
 
+# Representation of a single route. Readers:
+# @path: the normalized, parameterized path for the route (i.e. /labels/12/edit)
+# @url_details: controller and action, plus any non-default parameter formats as regexes
+# @parameters: an array of parameter names
+# @verb: HTTP verb (GET, POST, etc)
+# @request_line: minus the protocol, the HTTP request line (i.e. GET /labels/12/edit).
 class SensibleRoute
-  attr_reader :path, :url_details, :parameters, :verb
+  attr_reader :path, :url_details, :parameters, :verb, :request_line
 
+  # Initialize a new SensibleRoute.
+  # @param rt  a Journey route, as used internally by Rails
   def initialize(rt)
     @parameters = []
 
@@ -30,13 +38,20 @@ class SensibleRoute
     @path = parts.join
     @url_details = rt.requirements
     @verb = rt.verb
+    @request_line = "#{@verb} #{@path}"
     @regex = Regexp.new "^#{matcher.join}$"
   end
 
+  # Given a path (such as /labels/12/edit), detect whether that path is a match for this route
+  # (i.e. the route is actually /labels/:id/edit, but /labels/12/edit is a match for that).
+  # @param path  the path string to test
+  # @return boolean
   def match?(path)
     @regex.match?(path)
   end
 
+  # For use in gem initialization - call this once Rails is fully loaded so that Rails.sensible_routes
+  # can be set up.
   def self.hook_rails
     Rails.instance_eval <<EOF
       cache.delete :sensible_routes
@@ -52,7 +67,10 @@ EOF
   end
 end
 
+# An array-like collection of SensibleRoutes.
 class SensibleRouteCollection
+  # Initialize a new route collection. For an empty collection, call with no arguments; for a
+  # collection built from an existing array of routes, call with the routes: option.
   def initialize(**opts)
     @routes = if opts[:routes]
                 opts[:routes]
@@ -61,22 +79,35 @@ class SensibleRouteCollection
               end
   end
 
+  # Add a route to the collection.
+  # @param new  the route to add
   def add(new)
     @routes << new
   end
 
+  # Get an array representation of the collection.
+  # @return Array
   def to_a
     @routes
   end
 
+  # Filter the collection to only those entries that match the given block.
+  # @param &block  a block that returns true to retain an element, or false to reject it
+  # @return SensibleRouteCollection
   def select(&block)
     self.class.new(routes: @routes.select(&block))
   end
 
+  # Map over the collection, applying the given block as a transformation to each element.
+  # @param &block  a block to apply to each element; the return value will be included in the returned array
+  # @return Array
   def map(&block)
     @routes.map(&block)
   end
 
+  # Iterate through the collection, performing the specified operation with each element.
+  # @param &block  a block is required; it will be passed the current element as an argument
+  # @return self
   def each
     @routes.each do |rt|
       yield rt
@@ -84,18 +115,31 @@ class SensibleRouteCollection
     self
   end
 
+  # Find a match from the current route collection for a given path string. Useful for finding the current
+  # route being executed.
+  # @param path  the path string to find a matching route for
+  # @return SensibleRoute
   def match_for(path)
     @routes.select { |rt| rt.match?(path) }.first
   end
 
+  # Find the route that responds to the provided url_details (action and controller names).
+  # @param url_details  the name of a controller and action to find the route for
+  # @return SensibleRoute
   def route_for(**url_details)
     @routes.select { |rt| url_details <= rt.url_details }.first
   end
 
+  # Filter the collection down to only the routes served by the specified controller.
+  # @param controller  the controller name whose routes should be returned
+  # @return SensibleRouteCollection
   def controller(controller)
     self.class.new(routes: @routes.select { |rt| rt.url_details[:controller] == controller.to_s })
   end
 
+  # Given a list of path strings, return a new collection with their corresponding routes removed.
+  # @param paths  a list of path strings to find routes for and remove
+  # @return SensibleRouteCollection
   def without(*paths)
     routes = paths.map { |p| match_for p }
     self.class.new(routes: @routes - routes)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sensible_routes
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.1.0
 platform: ruby
 authors:
 - ArtOfCode-
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-06-28 00:00:00.000000000 Z
+date: 2018-07-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -102,7 +102,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 2.6.12
 signing_key: 
 specification_version: 4
 summary: Simple and comprehensible route introspection library for Rails.