9003075ec7
After Crystal 0.15, compiler will require declare the types used
by instance variables on classes.
This require changes to the usage of `Radix::Tree` by introducing
the type of payload elements it will handle:
# Will only support symbols as payload
tree = Radix::Tree(Symbol).new
tree.add "/", :root
# Error: cannot add node with anything other than Symbol
tree.add "/meaning-of-life", 42
The changes ensure future compatibility with Crystal and also
enforces a more declarative usage of `Radix::Tree`.
If necessary, you can combine multiple types to ensure a tree
can contain all the wide range of payloads you need:
tree = Radix::Tree.new(Foo | Bar | Symbol).new
tree.add "/", :root
tree.add "/foo", foo_instance
This change includes:
- Tree, Node and Result has been updated to require types.
- Node is capable of have optional payload (from defined type).
- Documentation has been updated to reflect this change.
3.3 KiB
Radix Tree
Radix tree implementation for Crystal language
Installation
Add this to your application's shard.yml:
dependencies:
radix:
github: luislavena/radix
Usage
Building Trees
You can associate a payload with each path added to the tree:
require "radix"
tree = Radix::Tree(Symbol).new
tree.add "/products", :products
tree.add "/products/featured", :featured
result = tree.find "/products/featured"
if result.found?
puts result.payload # => :featured
end
The types allowed for payload are defined on Tree definition:
tree = Radix::Tree(Symbol).new
# Good, since Symbol is allowed as payload
tree.add "/", :root
# Compilation error, Int32 is not allowed
tree.add "/meaning-of-life", 42
Can combine multiple types if needed:
tree = Radix::Tree(Int32 | String | Symbol).new
tree.add "/", :root
tree.add "/meaning-of-life", 42
tree.add "/hello", "world"
Lookup and placeholders
You can also extract values from placeholders (as named segments or globbing):
tree.add "/products/:id", :product
result = tree.find "/products/1234"
if result.found?
puts result.params["id"]? # => "1234"
end
Please see Radix::Tree#add documentation for more usage examples.
Caveats
Pretty much all Radix implementations have their limitations and this project is no exception.
When designing and adding paths to a Tree, please consider that two different named parameters cannot share the same level:
tree.add "/", :root
tree.add "/:post", :post
tree.add "/:category/:post", :category_post # => Radix::Tree::SharedKeyError
This is because different named parameters at the same level will result in
incorrect params when lookup is performed, and sometimes the value for
post or category parameters will not be stored as expected.
To avoid this issue, usage of explicit keys that differentiate each path is recommended.
For example, following a good SEO practice will be consider /:post as
absolute permalink for the post and have a list of categories which links to
the permalinks of the posts under that category:
tree.add "/", :root
tree.add "/:post", :post # this is post permalink
tree.add "/categories", :categories # list of categories
tree.add "/categories/:category", :category # listing of posts under each category
Implementation
This project has been inspired and adapted from julienschmidt/httprouter and spriet2000/vertx-http-router Go and Java implementations, respectively.
Changes to logic and optimizations have been made to take advantage of Crystal's features.
Contributing
- Fork it ( https://github.com/luislavena/radix/fork )
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request
Contributors
- Luis Lavena - creator, maintainer