nmea_0183_rs/lib.rs
1#![cfg_attr(
2 not(test),
3 deny(
4 clippy::panic,
5 clippy::expect_used,
6 clippy::todo,
7 clippy::unimplemented,
8 clippy::unreachable
9 )
10)]
11//! # nmea-0183-rs
12//!
13//! Bidirectional NMEA 0183 parser/encoder with AIS decoding and transponder-message encoding.
14//!
15//! ## Architecture
16//!
17//! ```text
18//! raw line ──→ parse_frame() ──→ NmeaFrame { prefix, talker, sentence_type, fields }
19//! │
20//! ┌──────────────┼──────────────┐
21//! ▼ ▼ ▼
22//! $ + known $ + unknown ! AIVDM/AIVDO AIS app sentences
23//! │ │ │ │
24//! ▼ ▼ ▼ ▼
25//! Typed struct Raw fields AisMessage enum AIS sentence struct
26//! ```
27//!
28//! ## Public API
29//!
30//! - [`parse_frame`] / [`encode_frame`] — device-compatible frame APIs (always available)
31//! - [`parse_frame_strict`] / [`validate_sentence`] / [`encode_frame_strict`] — strict frame-envelope APIs (always available)
32//! - `NmeaSentence` — dispatch enum for all typed NMEA sentences (requires an NMEA feature)
33//! - `NmeaEncodable` — trait providing compatible and strict wire encoding (requires an NMEA feature)
34//! - `ais` — AIS decoder, transponder-message encoder, and `!`-prefixed AIS application sentences (requires `ais`, `abm`, or `bbm`)
35//!
36//! `NmeaFrame::to_sentence()` re-encodes envelope data, including tag blocks,
37//! while normalizing checksums and CRLF. Keep the original line for exact bytes.
38//! `NmeaSentence` and `ais::sentences::AisSentence` also expose compatible and
39//! strict encoding; their `Unknown` variants own and preserve the captured envelope.
40//! Typed variants require the original frame to retain tags and the original talker.
41//! NMEA and ABM/BBM structs implement `Default` for construction with partial data.
42//! Their field parsers return `Self` directly; missing or malformed fields remain optional.
43//!
44//! With `ais`, `AisParser::decode()` distinguishes ignored frames,
45//! pending fragments, messages and `AisDecodeError` through a `Result`.
46//! Use one parser per physical source.
47//! Position timestamps use `ais::messages::PositionTimestamp`, preserving the
48//! unavailable, manual-input, dead-reckoning and inoperative states.
49//!
50//! ## Partial construction and enum encoding
51//!
52//! ```
53//! # #[cfg(feature = "dpt")]
54//! # {
55//! use nmea_0183_rs::{NmeaSentence, parse_frame};
56//! use nmea_0183_rs::nmea::Dpt;
57//! let value = NmeaSentence::Dpt(Dpt { depth: Some(4.1), ..Default::default() });
58//! let output = value.to_sentence_strict("SD")?;
59//! assert_eq!(NmeaSentence::parse(&parse_frame(&output)?), value);
60//! # }
61//! # Ok::<(), Box<dyn std::error::Error>>(())
62//! ```
63//!
64//! Strict validation covers the shared frame envelope. It does not validate every
65//! formatter's field semantics, serial transport settings, transmission timing,
66//! or multipart reassembly outside the AIS parser.
67//!
68//! ## Features
69//!
70//! - `nmea` (default): all 93 standard NMEA sentence types
71//! - `nmea_proprietary` (default) — all 16 proprietary NMEA sentence types
72//! - `ais` (default) — decoding for all numeric AIS Types 1-27, encoder support for Types 1/2/3, 4, 5, 9, 11, 12, 14, 18, 19, 21, 24 and 27, plus ABM, BBM and VSD sentences
73//! - Release 0.9.5 adds STN, XTR, ZDL, and ZFO: 101 NMEA formatters
74//! (85 standard, 16 proprietary) and 1076 passing all-features tests,
75//! including doctests
76//! - Release 0.9.6 adds ALM, FSI, MSK, and MSS: 105 NMEA formatters
77//! (89 standard, 16 proprietary) and 1113 passing all-features tests,
78//! including doctests
79//! - Release 0.9.7 adds HRM, NAK, ROR, and SPW, bringing coverage to
80//! 109 NMEA formatters (93 standard, 16 proprietary) and 1242 passing
81//! all-features tests, including doctests
82//! - `dbs`, `dbt`, `dpt`, … — individual sentence types
83
84mod compliance;
85mod error;
86mod frame;
87
88// Single source of truth for the "any NMEA sentence feature is active" predicate.
89// Add new sentence feature names here when wiring a new type.
90macro_rules! nmea_item {
91 ($item:item) => {
92 #[cfg(any(
93 feature = "nmea",
94 feature = "aam",
95 feature = "ack",
96 feature = "acn",
97 feature = "ala",
98 feature = "alc",
99 feature = "alf",
100 feature = "alm",
101 feature = "alr",
102 feature = "arc",
103 feature = "apb",
104 feature = "bec",
105 feature = "bod",
106 feature = "bwc",
107 feature = "bwr",
108 feature = "bww",
109 feature = "dbk",
110 feature = "dbs",
111 feature = "dbt",
112 feature = "dor",
113 feature = "dpt",
114 feature = "dsc",
115 feature = "dse",
116 feature = "dsi",
117 feature = "dsr",
118 feature = "dtm",
119 feature = "eve",
120 feature = "fir",
121 feature = "fsi",
122 feature = "gbs",
123 feature = "gfa",
124 feature = "gga",
125 feature = "gll",
126 feature = "gmp",
127 feature = "gns",
128 feature = "grs",
129 feature = "gsa",
130 feature = "gsv",
131 feature = "gst",
132 feature = "hbt",
133 feature = "hdg",
134 feature = "hdm",
135 feature = "hdt",
136 feature = "hmr",
137 feature = "hms",
138 feature = "hrm",
139 feature = "hsc",
140 feature = "mda",
141 feature = "msk",
142 feature = "mss",
143 feature = "mta",
144 feature = "mtw",
145 feature = "mwd",
146 feature = "mwv",
147 feature = "nak",
148 feature = "osd",
149 feature = "pashr",
150 feature = "pcdin",
151 feature = "pgrme",
152 feature = "pgrmt",
153 feature = "phtro",
154 feature = "pklid",
155 feature = "pklds",
156 feature = "pklsh",
157 feature = "pknds",
158 feature = "pknid",
159 feature = "pknsh",
160 feature = "pkwdwpl",
161 feature = "pmtk",
162 feature = "prdid",
163 feature = "psoncms",
164 feature = "pskpdpt",
165 feature = "rma",
166 feature = "rmb",
167 feature = "rmc",
168 feature = "ror",
169 feature = "rot",
170 feature = "rpm",
171 feature = "rsa",
172 feature = "rsd",
173 feature = "rte",
174 feature = "spw",
175 feature = "stn",
176 feature = "ths",
177 feature = "trd",
178 feature = "tll",
179 feature = "tlb",
180 feature = "ttd",
181 feature = "ttm",
182 feature = "txt",
183 feature = "vbw",
184 feature = "vdr",
185 feature = "ver",
186 feature = "vhw",
187 feature = "vlw",
188 feature = "vpw",
189 feature = "vtg",
190 feature = "vwr",
191 feature = "vwt",
192 feature = "vsd",
193 feature = "wcv",
194 feature = "wnc",
195 feature = "wpl",
196 feature = "xdr",
197 feature = "xte",
198 feature = "xtr",
199 feature = "zda",
200 feature = "zdl",
201 feature = "zfo",
202 feature = "ztg",
203 ))]
204 $item
205 };
206}
207
208nmea_item! { pub mod nmea; }
209
210#[cfg(any(feature = "ais", feature = "abm", feature = "bbm"))]
211pub mod ais;
212
213pub use compliance::*;
214pub use error::*;
215pub use frame::*;
216
217nmea_item! { pub use nmea::NmeaSentence; }
218nmea_item! { pub use nmea::NmeaEncodable; }
219
220#[cfg(all(test, any(feature = "mwd", feature = "xdr")))]
221mod test_support {
222 include!(concat!(
223 env!("CARGO_MANIFEST_DIR"),
224 "/tests/support/bounded.rs"
225 ));
226}