cadkit_dxf/lib.rs
1//! DXF reader and writer (ASCII and binary) for the cadkit model.
2//!
3//! Contract used by the `cadkit` facade: [`sniff()`], [`read()`], [`write()`].
4//!
5//! * [`read`] accepts ASCII and binary DXF from R12 (AC1009) to 2018 (AC1032) and maps it to
6//! a [`cadkit_core::Document`]. Geometry of planar entities is converted to world
7//! coordinates; see `docs/dxf/NOTES.md` for every mapping decision.
8//! * [`write()`] produces ASCII DXF in one of the [`DxfVersion`]s.
9//! * [`native`] exposes the group-code tokenizer for scanners and oracles.
10
11pub mod native;
12mod ocs;
13mod reader;
14mod writer;
15
16use cadkit_core::{Document, ReadOptions, Result, Summary, Warning};
17
18/// DXF output version.
19#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
20#[non_exhaustive]
21pub enum DxfVersion {
22 /// AutoCAD R12 (AC1009).
23 R12,
24 /// AutoCAD 2000 (AC1015).
25 R2000,
26 /// AutoCAD 2004 (AC1018).
27 R2004,
28 /// AutoCAD 2007 (AC1021).
29 R2007,
30 /// AutoCAD 2010 (AC1024).
31 R2010,
32 /// AutoCAD 2013 (AC1027).
33 R2013,
34 /// AutoCAD 2018 (AC1032).
35 #[default]
36 R2018,
37}
38
39impl DxfVersion {
40 /// The `$ACADVER` string of this version (for example `"AC1015"`).
41 pub fn acadver(self) -> &'static str {
42 match self {
43 DxfVersion::R12 => "AC1009",
44 DxfVersion::R2000 => "AC1015",
45 DxfVersion::R2004 => "AC1018",
46 DxfVersion::R2007 => "AC1021",
47 DxfVersion::R2010 => "AC1024",
48 DxfVersion::R2013 => "AC1027",
49 DxfVersion::R2018 => "AC1032",
50 }
51 }
52}
53
54/// Returns true when `bytes` look like DXF (ASCII or binary).
55///
56/// Only the first few groups are inspected: binary files by their sentinel, ASCII files by
57/// `0` / `SECTION` (after optional `999` comments).
58pub fn sniff(bytes: &[u8]) -> bool {
59 native::sniff(bytes)
60}
61
62/// Inspects the DXF `HEADER` section without decoding tables, blocks, or entities.
63pub fn inspect(bytes: &[u8], options: &ReadOptions) -> Result<Summary> {
64 reader::inspect(bytes, options)
65}
66
67/// Reads a DXF file into the format-neutral model.
68///
69/// Fails only when no useful document can be produced (not DXF, limits exceeded, or no
70/// section could be read); damaged or truncated files yield a partial document with
71/// `dxf.truncated` warnings.
72pub fn read(bytes: &[u8], options: &ReadOptions) -> Result<Document> {
73 reader::read(bytes, options)
74}
75
76/// Options for DXF output.
77#[derive(Debug, Clone, PartialEq, Eq, Default)]
78#[non_exhaustive]
79pub struct WriteOptions {
80 /// Target DXF release (`R2018` by default).
81 pub version: DxfVersion,
82 /// Optional legacy `$DWGCODEPAGE`, WHATWG, or OEM encoding label (for example
83 /// `"ANSI_1254"`, `"windows-1254"`, `"DOS857"`, or `"cp857"`) for pre-R2007 output.
84 /// Characters representable in that 8-bit encoding are emitted directly as raw bytes;
85 /// unrepresentable characters remain `\U+XXXX` escapes.
86 pub codepage: Option<String>,
87}
88
89impl WriteOptions {
90 /// Creates DXF output options for `version`.
91 #[must_use]
92 pub fn new(version: DxfVersion) -> Self {
93 Self {
94 version,
95 codepage: None,
96 }
97 }
98
99 /// Sets the target DXF release.
100 #[must_use]
101 pub fn with_version(mut self, version: DxfVersion) -> Self {
102 self.version = version;
103 self
104 }
105
106 /// Sets an explicit legacy `$DWGCODEPAGE` / WHATWG / OEM output encoding for pre-R2007 DXF.
107 #[must_use]
108 pub fn with_codepage(mut self, codepage: Option<String>) -> Self {
109 self.codepage = codepage;
110 self
111 }
112}
113
114/// Writes `doc` as ASCII/UTF-8 DXF text.
115pub fn write(doc: &Document, version: DxfVersion) -> Result<String> {
116 writer::write(doc, version).map(|(text, _)| text)
117}
118
119/// Like [`write()`], but also returns the warnings for everything that could not be
120/// represented (skipped unknown entities, undefined block references, ...).
121pub fn write_with_report(doc: &Document, version: DxfVersion) -> Result<(String, Vec<Warning>)> {
122 writer::write(doc, version)
123}
124
125/// Writes `doc` as DXF bytes using `options` (honoring legacy 8-bit `codepage` on pre-R2007 versions).
126pub fn write_bytes(doc: &Document, options: &WriteOptions) -> Result<Vec<u8>> {
127 writer::write_bytes(doc, options).map(|(bytes, _)| bytes)
128}
129
130/// Like [`write_bytes()`], returning both the encoded DXF bytes and conversion warnings.
131pub fn write_bytes_with_report(
132 doc: &Document,
133 options: &WriteOptions,
134) -> Result<(Vec<u8>, Vec<Warning>)> {
135 writer::write_bytes(doc, options)
136}