mirror of
https://gitea.invidious.io/iv-org/shard-radix.git
synced 2024-08-15 00:43:21 +00:00
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.
129 lines
3.3 KiB
Markdown
129 lines
3.3 KiB
Markdown
# Radix Tree
|
|
|
|
[Radix tree](https://en.wikipedia.org/wiki/Radix_tree) implementation for
|
|
Crystal language
|
|
|
|
[](https://travis-ci.org/luislavena/radix)
|
|
[](http://docrystal.org/github.com/luislavena/radix)
|
|
|
|
## Installation
|
|
|
|
Add this to your application's `shard.yml`:
|
|
|
|
```yaml
|
|
dependencies:
|
|
radix:
|
|
github: luislavena/radix
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Building Trees
|
|
|
|
You can associate a *payload* with each path added to the tree:
|
|
|
|
```crystal
|
|
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:
|
|
|
|
```crystal
|
|
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:
|
|
|
|
```crystal
|
|
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):
|
|
|
|
```crystal
|
|
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:
|
|
|
|
```crystal
|
|
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:
|
|
|
|
```crystal
|
|
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](https://github.com/julienschmidt/httprouter) and
|
|
[spriet2000/vertx-http-router](https://github.com/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
|
|
|
|
1. Fork it ( https://github.com/luislavena/radix/fork )
|
|
2. Create your feature branch (`git checkout -b my-new-feature`)
|
|
3. Commit your changes (`git commit -am 'Add some feature'`)
|
|
4. Push to the branch (`git push origin my-new-feature`)
|
|
5. Create a new Pull Request
|
|
|
|
## Contributors
|
|
|
|
- [Luis Lavena](https://github.com/luislavena) - creator, maintainer
|