Seg

Segment matcher for paths.

Description

Seg provides two methods for consuming and capturing path segments. A path is a string that starts with a slash and contains segments separated by slashes, for example /foo/bar/baz or /users/42.

Usage

Consider this interactive session:

>> s = Seg.new("/users/42")
=> #<Seg ...>

>> s.prev
=> ""

>> s.curr
=> "/users/42"

>> s.consume("users")
=> true

>> s.prev
=> "/users"

>> s.curr
=> "/42"

>> s.consume("42")
=> true

>> s.prev
=> "/users/42"

>> s.curr
=> ""

The previous example shows how to walk the path by providing segments to consume. In the following example, we'll see what happens when we try to consume a segment with a string that doesn't match:

>> s = Seg.new("/users/42")
=> #<Seg ...>

>> s.prev
=> ""

>> s.curr
=> "/users/42"

>> s.consume("admin")
=> false

>> s.prev
=> ""

>> s.curr
=> "/users/42"

As you can see, the command fails and the prev and curr strings are not altered. Now we'll see how to capture segment values:

>> s = Seg.new("/users/42")
=> #<Seg ...>

>> captures = {}
=> {}

>> s.prev
=> ""

>> s.curr
=> "/users/42"

>> s.capture(:foo, captures)
=> true

>> s.prev
=> "/users"

>> s.curr
=> "/42"

>> s.capture(:bar, captures)
=> true

>> s.prev
=> "/users/42"

>> s.curr
=> ""

>> captures
=> {:foo=>"users", :bar=>42}

It is also possible to extract the next segment from the path. The method extract returns the next segment, if available, or nil otherwise:

>> s = Seg.new("/users/42")
=> #<Seg ...>

>> s.prev
=> ""

>> s.curr
=> "/users/42"

>> s.extract
=> "users"

>> s.prev
=> "/users"

>> s.curr
=> "/42"

>> s.extract
=> "42"

>> s.prev
=> "/users/42"

>> s.curr
=> ""

You can also go back by using the methods retract and restore, which are the antidote to extract and consume respectively.

Let's see how retract works:

>> s = Seg.new("/users/42")
=> #<Seg ...>

>> s.prev
=> ""

>> s.curr
=> "/users/42"

>> s.extract
=> "users"

>> s.prev
=> "/users"

>> s.curr
=> "/42"

>> s.retract
=> "users"

>> s.prev
=> ""

>> s.curr
=> "/users/42"

And now restore:

>> s = Seg.new("/users/42")
=> #<Seg ...>

>> s.prev
=> ""

>> s.curr
=> "/users/42"

>> s.extract
=> "users"

>> s.prev
=> "/users"

>> s.curr
=> "/42"

>> s.restore("foo")
=> false

>> s.restore("users")
=> true

>> s.prev
=> ""

>> s.curr
=> "/users/42"

See also

Syro is a routing library that uses Seg for matching the request path.

Installation

$ gem install seg