headers/
lib.rs

1#![deny(missing_docs)]
2#![deny(missing_debug_implementations)]
3#![cfg_attr(test, deny(warnings))]
4#![cfg_attr(all(test, feature = "nightly"), feature(test))]
5
6//! # Typed HTTP Headers
7//!
8//! hyper has the opinion that headers should be strongly-typed, because that's
9//! why we're using Rust in the first place. To set or get any header, an object
10//! must implement the `Header` trait from this module. Several common headers
11//! are already provided, such as `Host`, `ContentType`, `UserAgent`, and others.
12//!
13//! # Why Typed?
14//!
15//! Or, why not stringly-typed? Types give the following advantages:
16//!
17//! - More difficult to typo, since typos in types should be caught by the compiler
18//! - Parsing to a proper type by default
19//!
20//! # Defining Custom Headers
21//!
22//! ## Implementing the `Header` trait
23//!
24//! Consider a Do Not Track header. It can be true or false, but it represents
25//! that via the numerals `1` and `0`.
26//!
27//! ```
28//! extern crate http;
29//! extern crate headers;
30//!
31//! use headers::{Header, HeaderName, HeaderValue};
32//!
33//! struct Dnt(bool);
34//!
35//! impl Header for Dnt {
36//!     fn name() -> &'static HeaderName {
37//!          &http::header::DNT
38//!     }
39//!
40//!     fn decode<'i, I>(values: &mut I) -> Result<Self, headers::Error>
41//!     where
42//!         I: Iterator<Item = &'i HeaderValue>,
43//!     {
44//!         let value = values
45//!             .next()
46//!             .ok_or_else(headers::Error::invalid)?;
47//!
48//!         if value == "0" {
49//!             Ok(Dnt(false))
50//!         } else if value == "1" {
51//!             Ok(Dnt(true))
52//!         } else {
53//!             Err(headers::Error::invalid())
54//!         }
55//!     }
56//!
57//!     fn encode<E>(&self, values: &mut E)
58//!     where
59//!         E: Extend<HeaderValue>,
60//!     {
61//!         let s = if self.0 {
62//!             "1"
63//!         } else {
64//!             "0"
65//!         };
66//!
67//!         let value = HeaderValue::from_static(s);
68//!
69//!         values.extend(std::iter::once(value));
70//!     }
71//! }
72//! ```
73
74#[cfg(all(test, feature = "nightly"))]
75extern crate test;
76
77pub use headers_core::{Error, Header};
78
79pub use mime::Mime;
80
81#[doc(hidden)]
82pub use http::HeaderMap;
83
84#[doc(hidden)]
85pub use http::header::{HeaderName, HeaderValue};
86
87#[macro_use]
88mod util;
89mod common;
90mod map_ext;
91
92pub use self::common::*;
93pub use self::map_ext::HeaderMapExt;
headers/lib.rs

headers/
lib.rs
