module Athena::Routing

Overview

Athena's Routing component, ART for short, allows mapping HTTP requests to particular ART::Routes. This component is primarily intended to be used as a basis for a routing implementation for a framework, handling the majority of the heavy lifting.

The routing component supports various ways to control which routes are matched, including:

• Regex patterns
• host header values
• HTTP method/scheme
• Request format/locale
• Dynamic callbacks

Using the routing component involves adding ART::Route instances to an ART::RouteCollection. The collection is then compiled via ART.compile. An ART::Matcher::URLMatcherInterface or ART::Matcher::RequestMatcherInterface could then be used to determine which route matches a given path or ART::Request. For example:

# Create a new route collection and add a route with a single parameter to it.
routes = ART::RouteCollection.new
routes.add "blog_show", ART::Route.new "/blog/{slug}"

# Compile the routes.
ART.compile routes

# Represents the request in an agnostic data format.
# In practice this would be created from the current `ART::Request`.
context = ART::RequestContext.new

# Match a request by path.
matcher = ART::Matcher::URLMatcher.new context
matcher.match "/blog/foo-bar" # => {"_route" => "blog_show", "slug" => "foo-bar"}

It is also possible to go the other way, generate a URL based on its name and set of parameters:

# Generating routes based on route name and parameters is also possible.
generator = ART::Generator::URLGenerator.new context
generator.generate "blog_show", slug: "bar-baz", source: "Crystal" # => "/blog/bar-baz?source=Crystal"

See the related types for more detailed information.

Simple Webapp

The Routing component also provides ART::RoutingHandler which can be used to add basic routing functionality to a HTTP::Server. This can be a good choice for super simple web applications that do not need any additional frameworky features.

Getting Started

If using this component within the [Athena Framework][Athena::Framework], it is already installed and required for you. Checkout the manual for some additional information on how to use it within the framework.

If using it outside of the framework, you will first need to add it as a dependency:

dependencies:
  athena-routing:
    github: athena-framework/routing
    version: ~> 0.1.0

Then run shards install, being sure to require it via require "athena-routing".

From here you would want to create an ART::RouteCollection, register routes with it, [compile][Athena::Routing.compile(routes)] it. Then an ART::Matcher::URLMatcherInterface or ART::Matcher::RequestMatcherInterface could then be used to determine which route matches a given path or ART::Request.

TIP: Consider using the annotations provided by the component within ART::Annotations to handle route registration.

Defined in:

annotations.cr
athena-routing.cr
ext/regex.cr

Constant Summary

VERSION = "0.1.8"

Class Method Summary

• .compile(routes : ART::RouteCollection) : Nil

  Before ART::Routes can be matched or generated, they must first be compiled.

Class Method Detail