Skip to main content

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}