Skip to content

Commit 2b68381

Browse files
Blacksmoke16Blacksmoke16
authored
Website integration (#365)
1 parent 80d2019 commit 2b68381

File tree

5 files changed

+115
-89
lines changed

5 files changed

+115
-89
lines changed

‎.gitignore‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
/docs/
21
/lib/
32
/bin/
43
/.shards/

‎docs/README.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
The `Athena::Negotiation` component allows an application to support [content negotiation](https://tools.ietf.org/html/rfc7231#section-5.3).
2+
The component has no dependencies and is framework agnostic; supporting various negotiators.
3+
4+
## Installation
5+
6+
First, install the component by adding the following to your `shard.yml`, then running `shards install`:
7+
8+
```yaml
9+
dependencies:
10+
athena-negotiation:
11+
github: athena-framework/negotiation
12+
version: ~> 0.1.0
13+
```
14+
15+
## Usage
16+
17+
The main type of [Athena::Negotiation][] is [ANG::AbstractNegotiator][] which is used to implement negotiators for each `Accept*` header.
18+
`Athena::Negotiation` exposes class level getters for each negotiator; that return a lazily initialized singleton instance.
19+
Each negotiator exposes two methods: [ANG::AbstractNegotiator#best][] and [ANG::AbstractNegotiator#ordered_elements][].
20+
21+
### Media Type
22+
23+
```crystal
24+
negotiator = ANG.negotiator
25+
26+
accept_header = "text/html, application/xhtml+xml, application/xml;q=0.9"
27+
priorities = ["text/html; charset=UTF-8", "application/json", "application/xml;q=0.5"]
28+
29+
accept = negotiator.best(accept_header, priorities).not_nil!
30+
31+
accept.media_range # => "text/html"
32+
accept.parameters # => {"charset" => "UTF-8"}
33+
```
34+
35+
The [ANG::Negotiator][] type returns an [ANG::Accept][], or `nil` if negotiating the best media type has failed.
36+
37+
### Character Set
38+
39+
```crystal
40+
negotiator = ANG.charset_negotiator
41+
42+
accept_header = "ISO-8859-1, UTF-8; q=0.9"
43+
priorities = ["iso-8859-1;q=0.3", "utf-8;q=0.9", "utf-16;q=1.0"]
44+
45+
accept = negotiator.best(accept_header, priorities).not_nil!
46+
47+
accept.charset # => "utf-8"
48+
accept.quality # => 0.9
49+
```
50+
51+
The [ANG::CharsetNegotiator][] type returns an [ANG::AcceptCharset][], or `nil` if negotiating the best character set has failed.
52+
53+
### Encoding
54+
55+
```crystal
56+
negotiator = ANG.encoding_negotiator
57+
58+
accept_header = "gzip;q=1.0, identity; q=0.5, *;q=0"
59+
priorities = ["gzip", "foo"]
60+
61+
accept = negotiator.best(accept_header, priorities).not_nil!
62+
63+
accept.coding # => "gzip"
64+
```
65+
66+
The [ANG::EncodingNegotiator][] type returns an [ANG::AcceptEncoding][], or `nil` if negotiating the best encoding has failed.
67+
68+
### Language
69+
70+
```crystal
71+
negotiator = ANG.language_negotiator
72+
73+
accept_header = "en; q=0.1, fr; q=0.4, zh-Hans-CN; q=0.9, de; q=0.2"
74+
priorities = ["de", "zh-Hans-CN", "en"]
75+
76+
accept = negotiator.best(accept_header, priorities).not_nil!
77+
78+
accept.language # => "zh"
79+
accept.region # => "cn"
80+
accept.script # => "hans"
81+
```
82+
83+
The [ANG::LanguageNegotiator][] type returns an [ANG::AcceptLanguage][], or `nil` if negotiating the best language has failed.

‎mkdocs.yml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
INHERIT: ../../../mkdocs-common.yml
2+
3+
site_name: Negotiation
4+
site_url: https://athenaframework.org/Negotiation/
5+
repo_url: https://github.com/athena-framework/negotiation
6+
7+
nav:
8+
- Introduction: README.md
9+
- Back to Manual: project://.
10+
- API:
11+
- Aliases: aliases.md
12+
- Top Level: top_level.md
13+
- '*'
14+
15+
plugins:
16+
- search
17+
- section-index
18+
- literate-nav
19+
- gen-files:
20+
scripts:
21+
- ../../../gen_doc_stubs.py
22+
- mkdocstrings:
23+
default_handler: crystal
24+
custom_templates: ../../../docs/templates
25+
handlers:
26+
crystal:
27+
crystal_docs_flags:
28+
- ./docs/index.cr
29+
- ./lib/athena-negotiation/src/athena-negotiation.cr
30+
source_locations:
31+
lib/athena-negotiation: https://github.com/athena-framework/negotiation/blob/v{shard_version}/{file}#L{line}

‎shard.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,4 +14,4 @@ description: |
1414
Framework agnostic content negotiation library.
1515
1616
authors:
17-
- George Dietrich <george@dietrich.app>
17+
- George Dietrich <dev@dietrich.pub>

‎src/athena-negotiation.cr‎

Lines changed: 0 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -14,93 +14,6 @@ require "./exceptions/*"
1414
alias ANG = Athena::Negotiation
1515

1616
# The `Athena::Negotiation` component allows an application to support [content negotiation](https://tools.ietf.org/html/rfc7231#section-5.3).
17-
# The component has no dependencies and is framework agnostic; supporting various negotiators.
18-
#
19-
# ## Getting Started
20-
#
21-
# If using this component within the [Athena Framework][Athena::Framework], it is already installed and required for you.
22-
# Checkout the [manual](../architecture/negotiation.md) for some additional information on how to use it within the framework.
23-
#
24-
# If using it outside of the framework, you will first need to add it as a dependency:
25-
#
26-
# ```yaml
27-
# dependencies:
28-
# athena-negotiation:
29-
# github: athena-framework/negotiation
30-
# version: ~> 0.1.0
31-
# ```
32-
#
33-
# Then run `shards install`, being sure to require it via `require "athena-negotiation"`.
34-
#
35-
# ## Usage
36-
#
37-
# The main type of `Athena::Negotiation` is `ANG::AbstractNegotiator` which is used to implement negotiators for each `Accept*` header.
38-
# `Athena::Negotiation` exposes class level getters for each negotiator; that return a lazily initialized singleton instance.
39-
# Each negotiator exposes two methods: `ANG::AbstractNegotiator#best` and `ANG::AbstractNegotiator#ordered_elements`.
40-
#
41-
# ### Media Type
42-
#
43-
# ```
44-
# negotiator = ANG.negotiator
45-
#
46-
# accept_header = "text/html, application/xhtml+xml, application/xml;q=0.9"
47-
# priorities = ["text/html; charset=UTF-8", "application/json", "application/xml;q=0.5"]
48-
#
49-
# accept = negotiator.best(accept_header, priorities).not_nil!
50-
#
51-
# accept.media_range # => "text/html"
52-
# accept.parameters # => {"charset" => "UTF-8"}
53-
# ```
54-
#
55-
# The `ANG::Negotiator` type returns an `ANG::Accept`, or `nil` if negotiating the best media type has failed.
56-
#
57-
# ### Character Set
58-
#
59-
# ```
60-
# negotiator = ANG.charset_negotiator
61-
#
62-
# accept_header = "ISO-8859-1, UTF-8; q=0.9"
63-
# priorities = ["iso-8859-1;q=0.3", "utf-8;q=0.9", "utf-16;q=1.0"]
64-
#
65-
# accept = negotiator.best(accept_header, priorities).not_nil!
66-
#
67-
# accept.charset # => "utf-8"
68-
# accept.quality # => 0.9
69-
# ```
70-
#
71-
# The `ANG::CharsetNegotiator` type returns an `ANG::AcceptCharset`, or `nil` if negotiating the best character set has failed.
72-
#
73-
# ### Encoding
74-
#
75-
# ```
76-
# negotiator = ANG.encoding_negotiator
77-
#
78-
# accept_header = "gzip;q=1.0, identity; q=0.5, *;q=0"
79-
# priorities = ["gzip", "foo"]
80-
#
81-
# accept = negotiator.best(accept_header, priorities).not_nil!
82-
#
83-
# accept.coding # => "gzip"
84-
# ```
85-
#
86-
# The `ANG::EncodingNegotiator` type returns an `ANG::AcceptEncoding`, or `nil` if negotiating the best encoding has failed.
87-
#
88-
# ### Language
89-
#
90-
# ```
91-
# negotiator = ANG.language_negotiator
92-
#
93-
# accept_header = "en; q=0.1, fr; q=0.4, zh-Hans-CN; q=0.9, de; q=0.2"
94-
# priorities = ["de", "zh-Hans-CN", "en"]
95-
#
96-
# accept = negotiator.best(accept_header, priorities).not_nil!
97-
#
98-
# accept.language # => "zh"
99-
# accept.region # => "cn"
100-
# accept.script # => "hans"
101-
# ```
102-
#
103-
# The `ANG::LanguageNegotiator` type returns an `ANG::AcceptLanguage`, or `nil` if negotiating the best language has failed.
10417
module Athena::Negotiation
10518
VERSION = "0.1.4"
10619

0 commit comments

Comments
 (0)