refactor(cli): parse cadcraft-cli arguments with clap, following RFC-0012 (#2268)

* test(cli): pin today's command-line behaviour

The later commits change these tests on purpose, so each behaviour change shows in their diff.

* refactor(cli): split main.rs into modules, move only

- output: outln!, stdout state, atomic write, export helpers, view/window helpers
- args: USAGE, option validation, framing options, MCP argument parsing and its tests
- info, convert, sample, mcp: one subcommand each
- perf: synthetic drawing, Rng, perf subcommands
- run: run subcommand and {last} handle chaining
- main: crate docs, mod lines, install_io, open, main, cli, unit tests

No behaviour change.

* refactor(cli): typed errors and run(args, out, err)

cadcraft-cli is now a library plus a thin binary. `cadcraft_cli::run(args, out, err)
-> i32` is the whole program; main.rs only passes `args_os()` and the process
streams. Handlers write through a `Streams` wrapper (output.rs) instead of the
process streams; it keeps the closed-stdout semantics (drop later output, carry
on, a closed pipe is not an error, other write errors are reported once and make
the exit code 1). `mcp` still speaks MCP on the real stdin/stdout.

Errors are typed (thiserror): CliError (error.rs) wraps EngineError, DocError,
IoError, io::Error and the per-module WindowError, ArgsError, RunError,
OutputError and PerfError. `run` prints `error: {e}` and exits 1.

The usage text and the "unknown option/argument" messages stay as one
transitional CliError::Usage(String), printed without the `error: ` prefix.
USAGE stays a const; step 4 (clap) removes both. The engine's IoHooks take
`Result<_, String>`, so the three `.map_err(|e| e.to_string())` in install_io
remain. The hooks are set-once (OnceLock), so installing them on every `run`
call is harmless.

tests/it/usage.rs calls `run` in-process with Vec<u8> writers; the headless mcp
case runs through the binary (it reads the real stdin) and a non-Unicode
argument test is new.

Behaviour changes (old -> new):
- Every error line other than the usage-class ones gains the prefix `error: `
  (e.g. `--view needs ...` -> `error: --view needs ...`, `unknown command
  `x`` -> `error: unknown command `x``, `invalid parameters for `open`: ...`
  -> `error: invalid parameters ...`, `unsupported file type` likewise).
- `cadcraft-cli: cannot connect to HOST:PORT: e` -> `error: cannot connect to
  HOST:PORT: e` (the old prefix is replaced).
- A non-Unicode argument: panic, exit 101 -> `error: argument "..." is not
  valid Unicode`, exit 1.
- Unchanged: usage text, `X: unknown option --y`, `unknown option --y`,
  `mcp: unknown argument ...` (no prefix); warnings and `wrote ...` lines;
  the `cadcraft-cli: can't write to stdout: e` report; exit codes.

* refactor(cli): parse arguments with clap

Replace the hand-written parser (USAGE, validate_options, OptionSpec,
framing_option, parse_mcp_args, CliError::Usage) with clap derive types
in args.rs: a Cli parser and one Args struct per subcommand, with the
framing flags (--window, --view) in a FramingArgs struct flattened into
convert and run. USAGE's framing and --cmd chaining text moves into the
subcommands' and flags' doc comments and run's long help, so --help
carries it. `commands` moves from an inline closure to commands.rs.
`command()` exposes the clap definition for man pages and completions.

clap reads the arguments as OsStrings. Help and --version go to stdout
with exit 0; usage errors are clap's, on stderr with exit 2. A bare
--help or -h before `--` shows the subcommand's help even after a
mistake on the line (`run --script --help`). run opens its drawings
(FILEs, --sample, --metric) and runs its steps (--script, --script-file,
--cmd) in command-line order, from ArgMatches::indices_of. Values stay
strings checked by the handlers, with their messages and exit 1
(--window, --view, --cmd JSON, sample names, perf counts). The last of a
repeated flag wins (args_override_self on every subcommand but mcp).

Behaviour changes:

Help and version
- --help, -h, help: the USAGE page -> clap's help, first line
  "cadcraft-cli: headless CADCraft".
- bare cadcraft-cli: USAGE on stderr, exit 1 -> clap's help on stderr,
  exit 2.
- <subcommand> --help / -h, help <subcommand>: "unknown option --help"
  (exit 1), the USAGE page (convert, help <subcommand>) or a file named
  -h (info -h, run -h) -> that subcommand's help, stdout, exit 0.
- <subcommand> --version: "unknown option --version", exit 1 -> clap's
  unexpected argument, exit 2.

Usage errors (exit 1 -> exit 2, clap's messages)
- Unknown subcommand, empty subcommand, unknown top-level flag: USAGE ->
  "error: unrecognized subcommand 'foo'" / "error: unexpected argument
  '--bogus' found".
- Unknown flag on any subcommand: "info: unknown option --bogus",
  "unknown option --bogus", "mcp: unknown argument --bogus" or USAGE
  (convert) -> "error: unexpected argument '--bogus' found".
- A short flag where a file is expected (info -x): opened as a file ->
  unexpected argument; `--` before it keeps it a file name.
- A value flag at the end or followed by a flag (--window, --view,
  --script, --script-file, --cmd, --save, --export, --connect): "error:
  --script needs text" and the like, or the next flag taken as the
  value (--window --view, --script --sample, --cmd --sample,
  --script-file --sample) -> "error: a value is required for '--script
  <TEXT>' but none was supplied". --connect followed by an unknown flag
  (--connect --foo, --connect -v) names that flag instead (clap reports
  the unknown argument, not the missing value).
- mcp --connect with an empty value: "error: --connect needs HOST:PORT
  ..." -> "error: invalid value ' ' for '--connect <HOST:PORT>':
  expected HOST:PORT (...)"; --connect=-v likewise.
- mcp --connect twice: "error: --connect given more than once" ->
  "error: the argument '--connect <HOST:PORT>' cannot be used multiple
  times".
- mcp --lazy / --launch without --connect: "error: --lazy and --launch
  need --connect HOST:PORT" -> "error: the following required arguments
  were not provided: --connect <HOST:PORT>".
- Missing positionals (info, convert with 0 or 1 files, sample with 0
  or 1 arguments): USAGE -> "error: the following required arguments
  were not provided".
- Extra positionals: convert with three files (USAGE), and info,
  commands, perf, sample, which ignored the extra argument -> "error:
  unexpected argument 'extra' found".
- perf -5: opened as a file -> unexpected argument '-5'.
- A non-Unicode argument where text is expected: "error: argument ... is
  not valid Unicode", exit 1 -> "error: invalid UTF-8 was detected in
  one or more arguments", exit 2.

Accepted where they were errors
- --x=v is a spelling of --x v for every value flag (--window, --view,
  --script, --script-file, --cmd, --save, --export, --connect); before
  it was an unknown option or USAGE. A value starting with - needs the
  = form (--cmd=-x).
- commands --: "unknown option --" -> `--` ends the options (all
  commands listed).
- run --view extents --view current: "use only one of --window and
  --view" -> the last wins, like every other repeat.

Other
- run --sample --sample opens one sample drawing (was two): repeated
  flags are last-wins.
- run checks --window/--view values before opening any drawing, so a
  bad framing value is reported ahead of a missing file.
- `-h` after a mistake shows the long help (`--help`): the retry asks
  for --help.

Unchanged: --window with --view, framing without an image output,
--view's case-insensitivity, all value messages (--window numbers,
--view values, --cmd JSON, {last}, sample names, --script-file read
errors), multiple FILEs, --sample with --metric or a FILE, last-wins
for --save, --export, --window, --script/--cmd order, and `\n` in
--script.

clap forced: exit 2 for usage errors, its message wording, and the
unknown-flag-over-missing-value precedence above.

* refactor(cli): reject repeated flags, long version (photocraft#7071 decisions)

Behaviour changes, old -> new:
- --save, --export, --window, --view, --sample, --metric, --lazy, --launch given twice:
  last one won -> usage error, exit 2 ("the argument ... cannot be used multiple times").
  --connect was already rejected. --script, --script-file, --cmd and run's FILEs still repeat.
- --version / -V: "cadcraft-cli <version>" -> "cadcraft-cli <version> (<sha>)", sha from
  CADCRAFT_BUILD_SHA or "dev", as the desktop app prints it.
- "cadcraft-cli version" is an unrecognized-subcommand usage error (as before; now tested).
- A value starting with "-" needs the = form for every value flag (as before, tested).
  --window -10,-10,10,10 stays a usage error ("unexpected argument -1"); write
  --window=-10,-10,10,10. clap's allow_negative_numbers does not accept a comma list, and
  allow_hyphen_values would let --window swallow the next flag, so neither is set. The
  --window help text names the = form.

* refactor(cli): typed values and flag relations

Step 6 of #2228: values are parsed into their types and flag relations
are checked at parse time, so a bad value or combination is a usage
error (exit 2) naming the flag, before any work starts. The handlers
receive typed values only. Runtime failures (files, the engine, a
`{last}` with no earlier handle) stay exit 1.

- --window parses to a Bounds2 (parse_window plus cadcraft_io's
  check_window); its WindowError is the value parser's error.
- --view is a ValueEnum (extents, current), case-insensitive; the long
  help lists what each value does.
- --window conflicts_with --view. In run, --window/--view require
  --export (an ArgGroup "framing" with requires). A framing flag with
  an output that isn't an image (convert's OUT, run's --export) is a
  UsageError turned into a clap error by into_clap (ArgumentConflict).
- sample's name is a ValueEnum (bracket, floorplan); `floor` stays a
  hidden alias.
- perf's N|FILE is one typed positional: a value that parses as a
  count is one, clamped to 1..=20000000 as before (so `perf 0` still
  times one entity); anything else is a drawing.
- --cmd 'id {json}' parses to an id and a serde_json::Value (default
  {}); `{last}` is still filled in when the command runs.
- Paths are PathBufs (info FILE, convert IN/OUT, run FILEs,
  --script-file, --save, --export, sample OUT, perf FILE). The engine
  and io crates take file names as text, so a path that isn't valid
  Unicode is refused by the handler, naming the file (exit 1).
- Deleted: check_framed_output, the --view match, ArgsError,
  CliError::Window/Args/UnknownSample, RunError::CmdJson,
  PerfError::BadCount.
- run's FILEs, --sample and --metric still combine (each opens another
  drawing, the last is current): neither photocraft#7071 nor RFC-0012 requires
  otherwise.

Behaviour changes (old -> new):
- --window with a bad value (wrong count, not a number, NaN/inf,
  reversed corners, beyond 1e12): exit 1 `error: --window ...` ->
  exit 2 `error: invalid value 'V' for '--window <x0,y0,x1,y1>':
  <reason>`. The reasons no longer repeat the flag or the value.
- --view with a bad value: exit 1 `error: --view needs `extents` or
  `current`` -> exit 2 `error: invalid value 'V' for '--view
  <extents|current>'` plus clap's possible-values line.
- --window with --view: exit 1 `error: use only one of --window and
  --view` -> exit 2 `error: the argument '--window <x0,y0,x1,y1>'
  cannot be used with '--view <extents|current>'`.
- run --window/--view without --export: exit 1 `error: --window/--view
  need an image output ...` -> exit 2 `error: the following required
  arguments were not provided: --export <OUT.png>`.
- A framing flag with a non-image output: exit 1 `error:
  --window/--view only apply to image output (png, svg, pdf), not
  `OUT`` -> exit 2 `error: --window only applies to image output (png,
  svg, pdf), not `OUT`` (or --view: the message names the flag given).
- sample with an unknown name: exit 1 `error: unknown sample `X`
  (bracket, floorplan)` -> exit 2 `error: invalid value 'X' for
  '<bracket|floorplan>'` plus the possible values. sample's help lists
  the possible values.
- --cmd with JSON that doesn't parse: exit 1 `error: --cmd ID:
  <serde error>`, after the earlier steps ran -> exit 2 `error: invalid
  value 'V' for '--cmd <id {json}>': <serde error>`, before anything
  runs.
- --cmd with an empty id (`--cmd=` or `--cmd ' {}'`): exit 1 `error:
  unknown command `` ` -> exit 2 `... expected a command id, then
  optionally its JSON parameters`.
- An empty path argument (info "", sample bracket "", perf "", ...):
  exit 1 from the engine or io -> exit 2 `error: a value is required
  for '<FILE>' but none was supplied` (clap's PathBuf parser).
- A path that isn't valid Unicode: exit 2 `error: invalid UTF-8 was
  detected ...` -> exit 1 `error: PATH: the file name is not valid
  Unicode` (text values that aren't Unicode stay exit 2). A non-Unicode
  --save or --export is refused before any drawing opens.
- perf's help gives the count range.

Tests: usage.rs rows above moved to exit 2 with clap's messages; new
rows for --view with a non-image output, run's framing with a dxf
--export, an empty --cmd id, bad --cmd JSON after a good step, a
`{last}` with no earlier handle, --window beyond 1e12, case-sensitive
sample names and empty paths. The non-Unicode test covers both a path
(exit 1) and text (exit 2). Unit tests: the --window parser tests moved
to args.rs; new ones for --cmd values and perf targets; framing_options
checks the clap error kinds.

* refactor(cadcraft): move launch-argument parsing into launch_args

Moves the hand-written parser (the argument loop, control_port_from, control_flag and their tests) from main.rs into launch_args.rs, which returns LaunchArgs. No behaviour change.

* refactor(cadcraft): parse launch flags with clap (RFC-0012)

Replaces the hand-written loop in launch_args.rs with clap derive types, as photocraft's launch_args.rs does. --help is generated from the doc comments and lists the other CADCRAFT_* variables.

Behaviour changes (old -> new):
- An unknown flag (--sampel) was opened as a file; it is now a usage error on stderr, exit 2, before the window opens. A file starting with "-" goes after "--".
- A repeated --control or --sample was accepted (last wins); it is now exit 2.
- A bad port (--control abc, 70000, -1) was logged and the control channel left off; it is now exit 2. The same for CADCRAFT_CONTROL_PORT, and the error names the variable when the value came from it.
- A bare --control (no value) kept CADCRAFT_CONTROL_PORT's port with a warning; it is now exit 2 ("a value is required"). A following flag is never taken as the value.
- An empty or blank CADCRAFT_CONTROL_PORT was logged as a bad port; it is now unset.
- --control=7979 is accepted (the equals form was opened as a file before).
- --version / -V and --help stop parsing at once and exit 0; version text is unchanged ("cadcraft <version> (<sha>)").
- -psn_* (Finder process serial number) is dropped instead of opened as a file.
- A file name that is not valid Unicode used to panic in std::env::args(); it is now read from args_os and reported with a log warning, not opened, because CadApp::open_path takes text.

Copied from photocraft's crates/automation/src/args.rs: blank_env_is_unset and name_env_vars unchanged (name_env_vars gets a local use for ContextKind/ContextValue); control_port and NotAPort unchanged. allow_negative_numbers is set on --control as in photocraft, so -1 is a bad value rather than a missing one.

* feat(cli): shell completions and man pages

Adds examples/man-and-completions.rs, which writes cadcraft-cli's bash, zsh, fish, elvish and
PowerShell completions (clap_complete) and man pages (clap_mangen: cadcraft-cli.1 and one per
subcommand) into a directory. clap_complete and clap_mangen are dev-dependencies, so the binary
is unchanged.

packaging/linux/package.sh builds the example in its own cargo run, runs it (through $EMULATOR
for cross builds; warns and leaves the files out without one) and installs the man pages and the
bash, zsh and fish completions into the staged tree. nfpm.yaml already ships the whole
usr/share tree, so it needs no change.

CADCraft has no FreeBSD packaging, so there is no FreeBSD script to update. macOS and Windows
packaging are untouched.

tests/man_and_completions.rs checks the generated file names.

* ci(cli): check the command-line code with ast-grep (RFC-0012)

Adds ast-grep rules from RFC-0012, run by craft-common-actions'
reusable ast-grep workflow (Linux, no Rust build, path-filtered):

- clap-error-message: a string literal, format!, .to_string() or
  SCREAMING_CASE const passed to Command::error / Error::raw
- clap-error-message-variable: the same message built into a variable
  first, in the same function
- string-error: Result<_, String>, Err(format!(..)), Err(".."),
  Err(x.to_string())
- args-os: std::env::args(), which panics on non-Unicode arguments

Scan paths: apps/cadcraft-cli/src, apps/cadcraft/src/launch_args.rs,
apps/cadcraft/src/main.rs. Rule tests run first in CI.

Source: photocraft#9750 at d16686cd. Only the scan paths and the
workflow path filters differ from it.

Fixes: none needed. The rule tests pass (4 passed) and the scan finds
nothing in the scanned paths.

* docs(cli): cadcraft-cli page, following RFC-0012

docs/cli.md: --help is the reference; exit codes, streams, usage
errors, values starting with -, paths, completions and man pages; the
environment variables (none for cadcraft-cli, CADCRAFT_CONTROL_PORT for
the desktop app's --control); and the rules not followed yet, with the
reason. The README links it.

* feat(cli): refuse an output that replaces an input

RFC-0012 rule 1.6: nothing destructive by default.

Behaviour change: `convert a.dxf a.dxf`, `run a.dxf … --save a.dxf` and
`run a.dxf … --export a.dxf` used to overwrite the input. They are now a
usage error (exit 2, `error: …` on stderr, nothing opened or written)
unless `--in-place` is given. "Same file" is file identity (same-file
crate), so `dir/./a.dxf` and a symlink to the input count. An output
that does not exist, or a failed identity check, is not refused; the
open or write reports the real error. Replacing an existing file that
is not an input is still allowed.

Scope: `--save` and `--export` only. A save that a --cmd or script runs
(for example `saveas`) is the engine's and is not checked.

Every write the CLI makes (convert OUT, --save, --export, sample OUT) resolves
an existing output first, so writing through a symlink updates the file it
points to and the link stays a link; the atomic rename used to replace the
link with a regular file, leaving the target (with --in-place, the input)
unchanged.

* feat(cli): --compact for JSON output

RFC-0012 rule 1.3: info and commands pretty-print their JSON by
default; --compact prints it on one line. run prints one JSON line per
--cmd result (JSON lines, one result per step), as its help and the
README document, so it takes no --compact. mcp's stdout is the MCP
protocol and is unchanged.

Behaviour change: info and commands accept --compact (it was an
unknown flag, exit 2). Their default output is unchanged.

docs/cli.md says which subcommand prints which form, and lists perf's
text table (no --json) and saves a --cmd or script runs (not checked
by --in-place) under "Not followed yet".

* fix(cadcraft): one Switch parser for boolean environment switches

CADCRAFT_VSYNC, CADCRAFT_SYSTEM_CURSOR, CADCRAFT_WAYLAND and
CADCRAFT_NO_NATIVE_MENU each had their own idea of "on". They now share
cadcraft_ui_egui::switch::Switch: 1/on/true/yes is On, 0/off/false/no is
Off (case- and space-insensitive), unset or blank is Default, and any
other value is Default and logged with the variable name. The ENVIRONMENT
help text says the same for all four.

Behaviour changes (old -> new):
- CADCRAFT_WAYLAND=0 counted as on (any value did); now only On keeps
  native Wayland.
- CADCRAFT_NO_NATIVE_MENU=0 counted as on (any value did); now only On
  keeps the menus inside the window.
- CADCRAFT_SYSTEM_CURSOR treated every value except ""/0/false/off as on;
  now only the On spellings do, and an unknown value is logged.
- CADCRAFT_VSYNC is unchanged except that an unknown value is logged.

* fix(cli): keep paths as paths until a file is opened

A path is now text only where text is needed.

- cadcraft: FileNames.unreadable is Vec<PathBuf>, logged with {:?}
  (escaped bytes) instead of a lossy rendering.
- cadcraft-cli: unicode() is called only inside open(), the one place
  that sends a path to the engine as JSON. convert, sample and run
  --save/--export pass the output as &Path. write_atomic, export,
  export_framed and OutputError::Write take or hold a Path/PathBuf;
  errors use .display(), and the `wrote ...` line uses .display().
- Dropped the dead find_subcommand lookup in launch_args (LaunchArgs has
  no subcommands).
- docs/cli.md: non-Unicode names are refused only where a drawing is
  opened.

Behaviour change: an output name that is not valid Unicode used to be
refused (exit 1); it is now written under that exact name. Opening such
a drawing is still refused.

Lossy strings that remain (all feed APIs that take text and only look at
the extension, never at the path the bytes are written to):
- cadcraft_io::write / write_framed (name picks the format) in sample.rs
  and output.rs::export_framed;
- cadcraft_io::is_image in convert.rs, run.rs and args.rs (framing flag
  check);
- cadcraft_engine::cmd::file::drops_unknown in export_framed.
These go away when cadcraft_io and the engine take impl AsRef<Path>
(the A1 follow-up). A non-Unicode extension is not a known format either
way, so it is rejected as an unsupported type, as before.

* refactor(cadcraft): read the environment once into Env

The desktop app reads its CADCRAFT_* variables once at startup into
apps/cadcraft/src/env.rs `Env` and passes the values on; no library crate
reads a CADCRAFT_* variable at run time any more.

- One `VARS` table (name, help line) feeds both the reader and the
  Environment section of `cadcraft --help`. A test checks that every
  variable the reader asks for is in the table, that every table entry
  sets a field, and that the help lists every entry.
- vsync goes to `gpu::surface_config`, the system cursor to
  `CadApp::set_system_cursor_default` (Options reset and Reset Palettes go
  back to it), FONTALT/FONTFALLBACK to the `cadcraft_fonts::ttf` setters
  (re-exported as `cadcraft_engine::fonts`), the settings directory to the
  new `cadcraft_engine::settings_dir::set`, and to `Workspace::load`.
- The three copies of the settings-directory rule (main.rs, workspace.rs,
  the engine's plotter folder) are one: `settings_dir::platform`.
- `Switch::from_env` is gone; `Switch::parse` stays.
- The child-process tests for CADCRAFT_CONTROL_PORT are replaced by tests
  that inject the variable lookup (`blank_env_is_unset`) or point
  `--control`'s fallback at PATH.

cadcraft-cli: plotter configurations matter to its output (`run --cmd plot`
or a script's PLOT with a user device, and the same through `mcp`), and the
font variables change how convert/run/sample draw text. So, following
RFC-0012 rule 1.7, the variables become fallbacks of flags declared with
`env =`: --config-dir (CADCRAFT_CONFIG_DIR), --fontalt (CADCRAFT_FONTALT)
and --fontfallback (CADCRAFT_FONTFALLBACK) on convert, run, mcp and sample.

Behaviour changes:
- CADCRAFT_CONFIG_DIR set but empty counts as unset everywhere: the
  workspace file and the plotter folder use the platform folder (was:
  workspace persistence and the plotter folder off). Logs and autosave
  already treated it so.
- The workspace file and the plotter folder ignore a relative
  XDG_CONFIG_HOME, as logs and autosave did (was: used it).
- A blank CADCRAFT_LOCALE means the system's languages (was: [""]).
- cadcraft-cli: the three variables apply only to convert, run, mcp and
  sample, as flag fallbacks (was: read by the engine and fonts in every
  subcommand, perf included). A font variable that isn't valid Unicode is
  a usage error naming the flag (was: ignored).

* refactor(io): one Format enum for file extensions

`cadcraft_doc::Format` (re-exported as `cadcraft_io::Format`) is the one
place that maps a file name's extension to a format: Dxf, Dwg, Dwt, Svg,
Svgz, Png, Pdf. `from_path` is ASCII case-insensitive; no extension (or a
trailing dot) is Dxf; an unknown extension is None. `READ` and `WRITE`
list the formats `read` and `write` accept. It lives in cadcraft-doc
because the engine depends on cadcraft-io only for tests.

Each place used to match on its own lower-cased extension string and now
matches on Format, with the same results:
- io::read: svg/svgz -> SVG reader, dxf/none -> DXF reader, other ->
  try DXF, else Unsupported(ext).
- io::write_with: dxf/none -> DXF, dwg -> DWG bridge, other with binary
  -> error, rest -> write_framed.
- io::write_framed: dwt -> DWG; dxf/none/dwg -> write_with; svg, png,
  pdf -> image writers; other -> Unsupported(ext).
- io::is_image: svg, png, pdf (not svgz, which is read only).
- engine file.rs is_dxf, drops_unknown (dwg, dwt), is_drawing_file
  (dxf, dwg, dwt, none).

Behaviour change (help text only): the CLI help lists the formats from
Format::READ / Format::WRITE instead of hand-written lists. `info` and
`convert IN` now name svg and svgz as readable, and `convert`, `sample`,
`run --save` and `run --export` name dwt (and `sample` pdf) as writable.
A test checks each file argument's help names every format of its list.

* refactor: one version string for the app and the CLI

cadcraft_engine::build_version() builds "<version> (<commit>)" once; the
desktop app's --version, its start-up log line and cadcraft-cli --version
all use it. No change in output.

* refactor(cli): share the environment helpers with the CLI

Move blank_env_is_unset and name_env_vars from the desktop app into
cadcraft_mcp::args and apply them in the CLI parser.

Behaviour changes (old -> new):
- Empty or blank CADCRAFT_FONTALT / CADCRAFT_FONTFALLBACK: reached clap as
  Some("") -> counts as unset.
- A bad value from an environment variable: the error named the flag ->
  names the variable.
- CADCRAFT_CONFIG_DIR is unchanged: empty still means no settings folder.
- Desktop app: unchanged; it uses the shared helpers.

* refactor: pass paths, not text, through io, engine and open_path

cadcraft_io::{read, write, write_with, write_framed, is_image}, the engine's
drops_unknown/is_drawing_file/read_text_file and CadApp::open_path take
paths (impl AsRef<Path> / &Path). The desktop launch arguments and the CLI
no longer convert paths to text to call them.

Behaviour changes (old -> new):
- A dropped file whose name is not valid Unicode opened with a "can't
  read" error naming a mangled path; it now opens natively. (Its path is
  not remembered for QSAVE, which then asks where to save.)
- A launch argument that is not valid Unicode was logged and skipped; it
  now opens like any other.
- A .dwt export builds the .dwg name as a path, not formatted text.
- On the web, a non-Unicode path passed to open_path reports "the path
  is not valid Unicode" instead of a lossy name.
- Opening errors print path.display().

FileNames and LaunchArgs::file_names are removed; the launch tests assert
the parsed PathBufs. New io test: non-Unicode names pick the format by
extension.

* docs(cli): CADCRAFT_CONFIG_DIR is the one flag fallback where empty isn't unset

* fix(engine): refuse a drawing path that isn't valid Unicode

read_file opened such a path with no saved path, so QSAVE could not save back to it.
It now returns an open error naming the file before reading it. The ui-egui opener
already reports read_file errors like any other failed open.

* fix(cli): report a failed write of help or version

A write error on help or version output (other than a closed pipe) now exits 1 and
tries to say so on stderr; it was ignored and exited with the clap code. A closed pipe
keeps the clap exit code.

* fix(cli): --connect needs HOST:PORT

--connect example.com was accepted and failed later. It is now a usage error (exit 2)
unless the value is a non-empty host (or a bracketed IPv6 address) and a u16 port.
The host is not resolved.

* docs(cli): run prints no line for a command with no result

* refactor(cli): explicit imports and smaller functions for the stricter lints

Lints: clippy::wildcard_imports, too_many_arguments, cognitive_complexity (30).

Replaced the non-test `use super::*;` in args, commands, convert, info,
output, perf and run with explicit imports; lib.rs keeps only the imports
its non-test code uses, and its test module imports the rest itself. The
`super::*` in the test modules stays.

A clippy run with all three lints and threshold 30 reports nothing in
apps/cadcraft-cli or in code this branch added, so no function needed
splitting.
This commit is contained in:
aiongg
2026-10-27 21:28:53 -04:00
committed by GitHub
parent 3929d94d89
commit 5654240729
70 changed files with 4228 additions and 1414 deletions
+26
View File
@@ -0,0 +1,26 @@
# Structural rules for the command-line code (RFC-0012): lint/ast-grep's rule tests, then a scan.
# Seconds, no Rust build.
name: ast-grep
on:
push:
branches: [main]
paths: ["lint/ast-grep/**", "apps/cadcraft-cli/src/**", "apps/cadcraft/src/launch_args.rs", "apps/cadcraft/src/main.rs", ".github/workflows/ast-grep.yml"]
pull_request:
paths: ["lint/ast-grep/**", "apps/cadcraft-cli/src/**", "apps/cadcraft/src/launch_args.rs", "apps/cadcraft/src/main.rs", ".github/workflows/ast-grep.yml"]
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ast-grep-${{ github.ref }}
cancel-in-progress: true
jobs:
scan:
# Tracked at @main like the other shared workflows.
uses: storytold/craft-common-actions/.github/workflows/ast-grep.yml@main
with:
config: lint/ast-grep/sgconfig.yml
paths: apps/cadcraft-cli/src apps/cadcraft/src/launch_args.rs apps/cadcraft/src/main.rs
Generated
+159
View File
@@ -196,6 +196,56 @@ dependencies = [
"libc",
]
[[package]]
name = "anstream"
version = "1.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
dependencies = [
"anstyle",
"anstyle-parse",
"anstyle-query",
"anstyle-wincon",
"colorchoice",
"is_terminal_polyfill",
"utf8parse",
]
[[package]]
name = "anstyle"
version = "1.0.14"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
[[package]]
name = "anstyle-parse"
version = "1.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"
dependencies = [
"utf8parse",
]
[[package]]
name = "anstyle-query"
version = "1.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
dependencies = [
"windows-sys 0.61.2",
]
[[package]]
name = "anstyle-wincon"
version = "3.0.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
dependencies = [
"anstyle",
"once_cell_polyfill",
"windows-sys 0.61.2",
]
[[package]]
name = "anyhow"
version = "1.0.104"
@@ -571,6 +621,7 @@ dependencies = [
"cadcraft-mcp",
"cadcraft-ui-egui",
"chrono",
"clap",
"craft-ui",
"craft-update",
"craft-window",
@@ -583,6 +634,7 @@ dependencies = [
"rfd",
"serde_json",
"sys-locale",
"thiserror 2.0.21",
"windows",
"winit",
"winresource",
@@ -597,7 +649,12 @@ dependencies = [
"cadcraft-io",
"cadcraft-mcp",
"cadcraft-render",
"clap",
"clap_complete",
"clap_mangen",
"same-file",
"serde_json",
"thiserror 2.0.21",
]
[[package]]
@@ -710,6 +767,7 @@ dependencies = [
"cadcraft-engine",
"cadcraft-io",
"cadcraft-render",
"clap",
"getrandom 0.4.3",
"log",
"serde_json",
@@ -863,6 +921,65 @@ dependencies = [
"num-traits",
]
[[package]]
name = "clap"
version = "4.6.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "aa8876b300ab35ba921adea3dfd70157a46249b33f95c9084ae5709785478946"
dependencies = [
"clap_builder",
"clap_derive",
]
[[package]]
name = "clap_builder"
version = "4.6.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ec0797fb7aeb1406c84efac526901f7ec3ead2124f946b494e72879d4b54704d"
dependencies = [
"anstream",
"anstyle",
"clap_lex",
"strsim",
]
[[package]]
name = "clap_complete"
version = "4.6.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "037e2a1a92236d0aff7e845093f64661d6df4c02c9fcc61a60e9e1d736fa392f"
dependencies = [
"clap",
]
[[package]]
name = "clap_derive"
version = "4.6.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f9c751b79415d4e559e3d1fcf128e09e720eb673a06d26cf6f392d37d75b66e0"
dependencies = [
"heck",
"proc-macro2",
"quote",
"syn 3.0.9",
]
[[package]]
name = "clap_lex"
version = "1.1.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1c133bc6a41be0d194c306b5506d15e6feeea7b1d6604bd3f8310dfb2ca96486"
[[package]]
name = "clap_mangen"
version = "0.3.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "211d617eaa4b735c96c9e0228fcbdb5120ef623f2b8cb67ffb84c3e02dbc28a4"
dependencies = [
"clap",
"roff",
]
[[package]]
name = "clipboard-win"
version = "5.4.3"
@@ -907,6 +1024,12 @@ version = "1.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3d7b894f5411737b7867f4827955924d7c254fc9f4d91a6aad6b097804b1018b"
[[package]]
name = "colorchoice"
version = "1.0.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
[[package]]
name = "colored"
version = "2.2.0"
@@ -2085,6 +2208,12 @@ dependencies = [
"stable_deref_trait",
]
[[package]]
name = "heck"
version = "0.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
[[package]]
name = "hermit-abi"
version = "0.5.3"
@@ -2387,6 +2516,12 @@ dependencies = [
"once_cell",
]
[[package]]
name = "is_terminal_polyfill"
version = "1.70.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
[[package]]
name = "itertools"
version = "0.15.0"
@@ -3241,6 +3376,12 @@ version = "1.21.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
[[package]]
name = "once_cell_polyfill"
version = "1.70.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
[[package]]
name = "open"
version = "5.4.5"
@@ -3813,6 +3954,12 @@ dependencies = [
"windows-sys 0.52.0",
]
[[package]]
name = "roff"
version = "1.1.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "323c417e1d9665a65b263ec744ba09030cfb277e9daa0b018a4ab62e57bc8189"
[[package]]
name = "ron"
version = "0.12.2"
@@ -4328,6 +4475,12 @@ dependencies = [
"unicode-properties",
]
[[package]]
name = "strsim"
version = "0.11.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
[[package]]
name = "subsetter"
version = "0.2.6"
@@ -4801,6 +4954,12 @@ version = "1.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
[[package]]
name = "utf8parse"
version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
[[package]]
name = "uuid"
version = "1.29.0"
+4
View File
@@ -29,9 +29,13 @@ craft-docpath = { version = "0.1.0", git = "https://github.com/storytold/craft-l
# PDF writing (krilla) for plots, and reading them back in tests. The root patches below pin
# craft-pdf's patched backends to the same revision (Cargo ignores dependency-local patches).
craft-pdf = { version = "=0.1.0", git = "https://github.com/storytold/craft-libs", rev = "92d392cff132eaf53e13afff77f38b5c11b73aa0", default-features = false }
clap = { version = "4", features = ["derive", "env"] }
clap_complete = "4.6.11"
clap_mangen = { version = "0.3.3", features = ["env"] }
# foundation
thiserror = "2"
same-file = "1"
serde = { version = "1", features = ["derive", "rc"] }
serde_json = { version = "1", features = ["float_roundtrip"] }
log = "0.4"
+4 -1
View File
@@ -196,7 +196,7 @@ crashed survives the next start. The file stops growing at 16 MiB. `--version` w
| Variable | Effect |
|---|---|
| `CADCRAFT_CONFIG_DIR` | Use this directory instead of the platform settings directory (the log goes to its `logs/`) |
| `CADCRAFT_CONFIG_DIR` | Use this directory instead of the platform settings directory (the log goes to its `logs/`); empty means no settings folder (no log file, autosave, workspace or plotters) |
| `RUST_LOG` | Log levels for standard error and the log file. Default: `info` for CADCraft's own crates, `warn` for everything else. env_logger-style directives replace that, e.g. `RUST_LOG=debug`, `RUST_LOG=warn,cadcraft_io=trace` or `RUST_LOG=info,wgpu_core=warn`; a directive ending in `*` covers every target starting with it (`cadcraft*=debug`). `cadcraft_engine=debug` also logs every command-line message. |
The logger is `apps/cadcraft/src/logging.rs`; the web build logs to the browser console instead.
@@ -238,6 +238,9 @@ MCP tools include `command_line` (type at the prompt), `execute` (any command wi
To run LISP routines, scripts and alias files, or to drive CADCraft from your own programs, see
[docs/customization.md](docs/customization.md).
`cadcraft-cli --help` documents every subcommand and flag; exit codes, streams, environment
variables and its RFC-0012 conventions are in [docs/cli.md](docs/cli.md).
## Architecture
```text
+17
View File
@@ -6,6 +6,14 @@ edition.workspace = true
license.workspace = true
publish = false
[lib]
name = "cadcraft_cli"
path = "src/lib.rs"
[[bin]]
name = "cadcraft-cli"
path = "src/main.rs"
[lints]
workspace = true
@@ -14,4 +22,13 @@ cadcraft-engine = { workspace = true }
cadcraft-io = { workspace = true }
cadcraft-mcp = { workspace = true }
cadcraft-render = { workspace = true }
clap = { workspace = true }
same-file = { workspace = true }
serde_json = { workspace = true }
thiserror = { workspace = true }
[dev-dependencies]
# Shell completions and man pages (examples/man-and-completions.rs, for the Linux packages); not
# in the binary.
clap_complete = { workspace = true }
clap_mangen = { workspace = true }
@@ -0,0 +1,41 @@
//! Writes cadcraft-cli's shell completions ([`clap_complete`]: bash, zsh, fish, elvish,
//! PowerShell) and man pages ([`clap_mangen`]: `cadcraft-cli.1` and one per subcommand, such as
//! `cadcraft-cli-convert.1`) into a directory. The Linux packages ship them
//! (`packaging/linux/package.sh`):
//!
//! ```sh
//! cargo run -p cadcraft-cli --example man-and-completions -- <out-dir>
//! ```
use std::path::Path;
use std::process::ExitCode;
use clap::ValueEnum;
use clap_complete::Shell;
fn main() -> ExitCode {
let mut args = std::env::args_os().skip(1);
let (Some(dir), None) = (args.next(), args.next()) else {
eprintln!("usage: man-and-completions <out-dir>");
return ExitCode::from(2);
};
let dir = Path::new(&dir);
match generate(dir) {
Ok(()) => ExitCode::SUCCESS,
Err(e) => {
eprintln!("error: {}: {e}", dir.display());
ExitCode::FAILURE
}
}
}
pub(crate) fn generate(dir: &Path) -> std::io::Result<()> {
std::fs::create_dir_all(dir)?;
let mut cmd = cadcraft_cli::command();
for &shell in Shell::value_variants() {
clap_complete::generate_to(shell, &mut cmd, "cadcraft-cli", dir)?;
}
// A fresh command: `clap_complete::generate_to` built `cmd`, adding the `help` subcommand,
// which `clap_mangen` would otherwise give pages of its own (`cadcraft-cli-help-convert.1`).
clap_mangen::generate_to(cadcraft_cli::command(), dir)
}
+786
View File
@@ -0,0 +1,786 @@
//! The command line, as clap types. Values are parsed into their types here and the relations
//! between flags are checked, so a bad value or combination is a usage error (exit 2) naming the
//! flag, before any work starts; the handlers receive typed values only. A flag a subcommand
//! doesn't take is a usage error too, so a typo can't be silently ignored. A value flag never takes
//! the next flag as its value: a value starting with `-` is written `--save=-out.dxf` (or
//! `./-out.dxf`).
use std::ffi::{OsStr, OsString};
use std::path::{Path, PathBuf};
use cadcraft_engine::geom::{Bounds2, Vec2};
use cadcraft_io::Format;
use cadcraft_mcp::args::{blank_env_is_unset, name_env_vars};
use clap::builder::{OsStringValueParser, PathBufValueParser, TypedValueParser};
use clap::error::ErrorKind;
use clap::parser::ValueSource;
use clap::{ArgAction, ArgGroup, ArgMatches, Args, CommandFactory, FromArgMatches, Parser, Subcommand, ValueEnum};
use serde_json::Value;
/// Help text that names the formats of `list`, built once from [`Format::READ`] or [`Format::WRITE`]
/// so it can't drift from what the code accepts.
fn with_formats(cell: &'static std::sync::OnceLock<String>, before: &str, list: &[Format], after: &str) -> &'static str {
cell.get_or_init(|| format!("{before}({}){after}", Format::list(list)))
}
/// The drawing an input argument names.
fn read_help() -> &'static str {
static C: std::sync::OnceLock<String> = std::sync::OnceLock::new();
with_formats(&C, "The drawing to read ", Format::READ, "")
}
fn open_help() -> &'static str {
static C: std::sync::OnceLock<String> = std::sync::OnceLock::new();
with_formats(&C, "Drawings to open ", Format::READ, "")
}
fn write_help() -> &'static str {
static C: std::sync::OnceLock<String> = std::sync::OnceLock::new();
with_formats(&C, "The file to write; its extension picks the format ", Format::WRITE, "")
}
fn save_help() -> &'static str {
static C: std::sync::OnceLock<String> = std::sync::OnceLock::new();
with_formats(&C, "Save the drawing to this file; its extension picks the format ", Format::WRITE, "")
}
fn export_help() -> &'static str {
static C: std::sync::OnceLock<String> = std::sync::OnceLock::new();
with_formats(&C, "Export the drawing to this file; its extension picks the format ", Format::WRITE, "")
}
fn convert_about() -> &'static str {
static C: std::sync::OnceLock<String> = std::sync::OnceLock::new();
with_formats(&C, "Convert a drawing; OUT's extension picks the format ", Format::WRITE, "")
}
fn convert_long_about() -> &'static str {
static C: std::sync::OnceLock<String> = std::sync::OnceLock::new();
C.get_or_init(|| {
format!(
"{}\n\nImage output (png 2400x1600, svg, pdf) shows model space, fitted to the drawing extents unless\n--window or --view says otherwise.",
convert_about()
)
})
}
/// cadcraft-cli: headless CADCraft
#[derive(Parser)]
#[command(name = "cadcraft-cli", version = cadcraft_engine::build_version(), arg_required_else_help = true)]
pub(crate) struct Cli {
#[command(subcommand)]
pub(crate) command: Command,
}
#[derive(Subcommand)]
pub(crate) enum Command {
Info(InfoArgs),
Convert(ConvertArgs),
Run(RunArgs),
Commands(CommandsArgs),
Mcp(McpArgs),
Perf(PerfArgs),
Sample(SampleArgs),
}
/// Print a drawing's summary as JSON
#[derive(Args)]
pub(crate) struct InfoArgs {
#[arg(help = read_help())]
pub(crate) file: PathBuf,
/// One line of JSON instead of pretty-printed
#[arg(long)]
pub(crate) compact: bool,
}
/// Convert a drawing; OUT's extension picks the format
#[derive(Args)]
#[command(about = convert_about(), long_about = convert_long_about())]
pub(crate) struct ConvertArgs {
#[arg(value_name = "IN", help = read_help())]
pub(crate) input: PathBuf,
#[arg(value_name = "OUT", help = write_help())]
pub(crate) output: PathBuf,
#[command(flatten)]
pub(crate) framing: FramingArgs,
/// Allow an output that is an input file, replacing the original
#[arg(long)]
pub(crate) in_place: bool,
#[command(flatten)]
pub(crate) settings: Settings,
}
/// The settings the desktop app reads from its environment, for the subcommands that draw or run
/// commands. A variable is the flag's fallback; an empty one counts as unset, except
/// `CADCRAFT_CONFIG_DIR`.
#[derive(Args)]
#[command(next_help_heading = "Settings")]
pub(crate) struct Settings {
/// The settings folder; plotter configurations are in its `plotters` folder (default: the
/// platform's settings folder). An empty value means no settings folder
// Not RFC-0012 rule 1.7's "an empty variable counts as unset": an empty value is the
// documented way to run with no settings folder (isolated runs, tests), and it predates the
// CLI port. Keep it out of any blanket treatment of empty variables.
#[arg(long, value_name = "DIR", env = "CADCRAFT_CONFIG_DIR", value_parser = OsStringValueParser::new().map(PathBuf::from))]
pub(crate) config_dir: Option<PathBuf>,
/// The font that replaces a missing one (FONTALT)
#[arg(long, value_name = "FONT", env = "CADCRAFT_FONTALT")]
pub(crate) fontalt: Option<String>,
/// The fonts tried, in order, for characters a font lacks, comma-separated (FONTFALLBACK)
#[arg(long, value_name = "FONTS", env = "CADCRAFT_FONTFALLBACK")]
pub(crate) fontfallback: Option<String>,
}
impl Settings {
/// Install the settings for this run; an unset one is the default. An empty or blank
/// `--config-dir` is no settings folder.
pub(crate) fn apply(&self) {
cadcraft_engine::settings_dir::set(self.settings_dir());
cadcraft_engine::fonts::ttf::set_font_alt(self.fontalt.as_deref().unwrap_or(""));
cadcraft_engine::fonts::ttf::set_fallback_fonts(self.fontfallback.as_deref().unwrap_or(""));
}
/// The settings folder: `--config-dir`, else the platform's; `None` when the flag is empty or
/// blank.
fn settings_dir(&self) -> Option<PathBuf> {
match &self.config_dir {
Some(dir) if dir.to_str().is_some_and(|d| d.trim().is_empty()) => None,
Some(dir) => Some(dir.clone()),
None => cadcraft_engine::settings_dir::platform(|k| std::env::var_os(k)),
}
}
}
// What part of model space an image shows: shared by `convert` and `run`.
#[derive(Args)]
pub(crate) struct FramingArgs {
/// Show this rectangle (drawing units, x0<x1, y0<y1), centred and scaled to fit the image
/// without distortion. A negative x0 needs the `=` form: --window=-10,0,10,5
#[arg(long, value_name = "x0,y0,x1,y1", value_parser = parse_window, conflicts_with = "view")]
pub(crate) window: Option<Bounds2>,
/// What part of model space the image shows (case-insensitive)
#[arg(long, value_name = "extents|current", value_enum, ignore_case = true)]
pub(crate) view: Option<ViewMode>,
}
/// `--view`.
#[derive(Clone, Copy, Debug, PartialEq, ValueEnum)]
pub(crate) enum ViewMode {
/// Always fit the drawing extents
Extents,
/// The current view, as last set by zoom, pan or view.set (a freshly opened drawing's view is
/// its extents plus a 10% margin)
Current,
}
/// Open drawings (or start a new one), run scripts and commands in order, save or export the result
///
/// Drawings open in the order given, and the last one is current; without any, a new imperial
/// drawing is used. --script, --script-file and --cmd steps run in the order given, and each
/// --cmd prints its JSON result on one line (JSON lines); a command with no result prints nothing.
/// An image --export (png 2400x1600, svg, pdf) shows model space:
/// the current view if the steps changed it (zoom, pan, view.set…), otherwise the drawing
/// extents, unless --window or --view says otherwise.
#[derive(Args)]
#[command(group(ArgGroup::new("framing").args(["window", "view"]).multiple(true).requires("export")))]
#[command(after_long_help = r#"--cmd chaining:
A --cmd parameter value of exactly "{last}" is replaced with the last object handle an
earlier --cmd in the same run returned, so a command can act on what the previous one made:
--cmd 'mview {"p1":[20,20],"p2":[200,150]}' prints {"viewports":["100"]}
--cmd 'viewport.set {"handle":"{last}","scale":1}' changes viewport 100
It works in any parameter, at any depth (e.g. "handles":["{last}"]); every other string is
passed unchanged. With no earlier returned handle the run fails and says so."#)]
pub(crate) struct RunArgs {
#[arg(value_name = "FILE", help = open_help())]
pub(crate) files: Vec<PathBuf>,
/// Open the built-in sample drawing
#[arg(long)]
pub(crate) sample: bool,
/// Start a new metric drawing
#[arg(long)]
pub(crate) metric: bool,
/// Command-line script text to run (`\n` separates lines)
#[arg(long, value_name = "TEXT", action = ArgAction::Append)]
pub(crate) script: Vec<String>,
/// A script file (.scr) to run
#[arg(long, value_name = "F.scr", action = ArgAction::Append)]
pub(crate) script_file: Vec<PathBuf>,
/// An engine command and its JSON parameters (default {}); see "--cmd chaining" in --help
#[arg(long, value_name = "id {json}", action = ArgAction::Append, value_parser = cmd_step)]
pub(crate) cmd: Vec<CmdStep>,
#[arg(long, value_name = "OUT.dxf", help = save_help())]
pub(crate) save: Option<PathBuf>,
#[arg(long, value_name = "OUT.png", help = export_help())]
pub(crate) export: Option<PathBuf>,
#[command(flatten)]
pub(crate) framing: FramingArgs,
/// Allow an output that is an input file, replacing the original
#[arg(long)]
pub(crate) in_place: bool,
#[command(flatten)]
pub(crate) settings: Settings,
/// The drawings, in command-line order, set by [`parse`].
#[arg(skip)]
pub(crate) drawings: Vec<Drawing>,
/// The steps, in command-line order, set by [`parse`].
#[arg(skip)]
pub(crate) steps: Vec<Step>,
}
/// A drawing `run` opens.
#[derive(Clone, Debug, PartialEq)]
pub(crate) enum Drawing {
File(PathBuf),
Sample,
Metric,
}
/// A `--script`, `--script-file` or `--cmd` of `run`.
#[derive(Clone, Debug, PartialEq)]
pub(crate) enum Step {
Script(String),
ScriptFile(PathBuf),
Cmd(CmdStep),
}
/// `--cmd 'id {json}'`: an engine command and its parameters. `{last}` placeholders are filled in
/// when it runs.
#[derive(Clone, Debug, PartialEq)]
pub(crate) struct CmdStep {
pub(crate) id: String,
pub(crate) params: Value,
}
/// Print the command catalog as JSON
#[derive(Args)]
pub(crate) struct CommandsArgs {
/// Only the commands whose id or label contains this text (case-insensitive)
pub(crate) filter: Option<String>,
/// One line of JSON instead of pretty-printed
#[arg(long)]
pub(crate) compact: bool,
}
/// Run the MCP server on stdio: a headless drawing session, or a bridge to the running app
#[derive(Args)]
pub(crate) struct McpArgs {
/// Bridge to the app's control channel (its --control port, e.g. 127.0.0.1:7979)
#[arg(long, value_name = "HOST:PORT", value_parser = connect_addr)]
pub(crate) connect: Option<String>,
/// Reach the app at the first call instead of at startup, so the server can start before the
/// app is open
#[arg(long, requires = "connect")]
pub(crate) lazy: bool,
/// Like --lazy, and a call that finds nothing at HOST:PORT opens the app with that control
/// port first (macOS)
#[arg(long, requires = "connect")]
pub(crate) launch: bool,
#[command(flatten)]
pub(crate) settings: Settings,
}
/// Time the engine on a synthetic N-entity drawing (default 200000), or the canvas display-list
/// build of a drawing, zoomed in step by step
#[derive(Args)]
pub(crate) struct PerfArgs {
/// An entity count (clamped to 1-20000000), or a drawing to time
#[arg(value_name = "N|FILE", value_parser = PathBufValueParser::new().map(perf_target))]
pub(crate) target: Option<PerfTarget>,
}
/// What `perf` times.
#[derive(Clone, Debug, PartialEq)]
pub(crate) enum PerfTarget {
/// A synthetic drawing with this many entities, within [`MAX_PERF_COUNT`].
Count(usize),
File(PathBuf),
}
/// The largest synthetic drawing `perf` builds.
const MAX_PERF_COUNT: usize = 20_000_000;
/// `perf N|FILE`: a value that reads as a count is one, clamped to 1..=[`MAX_PERF_COUNT`] so `perf
/// 0` still times something; anything else is a drawing.
fn perf_target(p: PathBuf) -> PerfTarget {
match p.to_str().and_then(|t| t.parse::<usize>().ok()) {
Some(n) => PerfTarget::Count(n.clamp(1, MAX_PERF_COUNT)),
None => PerfTarget::File(p),
}
}
/// Write a built-in sample drawing
#[derive(Args)]
pub(crate) struct SampleArgs {
/// Which sample
#[arg(value_name = "bracket|floorplan", value_enum)]
pub(crate) name: SampleName,
#[arg(value_name = "OUT", help = write_help())]
pub(crate) output: PathBuf,
#[command(flatten)]
pub(crate) settings: Settings,
}
/// `sample`'s drawings.
#[derive(Clone, Copy, Debug, PartialEq, ValueEnum)]
pub(crate) enum SampleName {
Bracket,
#[value(alias = "floor")]
Floorplan,
}
/// What part of model space an image export shows.
#[derive(Clone, Copy, Debug, PartialEq)]
pub(crate) enum Framing {
/// `run`: the current view if the commands changed it, else the extents. `convert`: extents.
Auto,
Extents,
Current,
Window(Bounds2),
}
/// Why a `--window` value is refused: clap prints it after the flag and its value (exit 2).
#[derive(Debug, thiserror::Error)]
pub(crate) enum WindowError {
#[error("expected four numbers x0,y0,x1,y1")]
NeedsFour,
#[error("{name} must be a finite number, got `{value}`")]
NotFinite { name: &'static str, value: String },
#[error("need x0 < x1 and y0 < y1 (lower-left corner first)")]
Order,
#[error(transparent)]
Limits(#[from] cadcraft_io::IoError),
}
/// Why a value is refused: clap prints it after the flag and its value (exit 2).
#[derive(Debug, thiserror::Error)]
pub(crate) enum ValueError {
#[error("expected HOST:PORT (the app's --control port, e.g. 127.0.0.1:7979)")]
Connect,
#[error("expected a command id, then optionally its JSON parameters")]
CmdId,
#[error(transparent)]
CmdJson(#[from] serde_json::Error),
}
/// Why `parse` refuses flags clap accepted: clap prints it as a usage error (exit 2).
#[derive(Debug, thiserror::Error)]
enum UsageError {
/// The framing flags choose what an image shows; a drawing file has nothing to frame.
#[error("{flag} only applies to image output (png, svg, pdf), not `{}`", .out.display())]
FramingNeedsImage { flag: &'static str, out: PathBuf },
/// The output is one of the input files, so writing it would replace the original.
#[error("{} is an input file, so the result would replace the original: choose another output, or pass --in-place to overwrite it", .0.display())]
OutIsInput(PathBuf),
}
impl UsageError {
fn into_clap(self, cmd: &mut clap::Command) -> clap::Error {
let kind = match self {
Self::FramingNeedsImage { .. } | Self::OutIsInput(_) => ErrorKind::ArgumentConflict,
};
cmd.error(kind, self)
}
}
/// Parse `--window x0,y0,x1,y1` (min corner first). Hostile values are errors, never panics.
pub(crate) fn parse_window(text: &str) -> Result<Bounds2, WindowError> {
let parts: Vec<&str> = text.split(',').map(str::trim).collect();
let [x0, y0, x1, y1] = parts.as_slice() else {
return Err(WindowError::NeedsFour);
};
let num = |name: &'static str, v: &str| -> Result<f64, WindowError> {
match v.parse::<f64>() {
Ok(n) if n.is_finite() => Ok(n),
_ => Err(WindowError::NotFinite { name, value: v.to_string() }),
}
};
let (x0, y0, x1, y1) = (num("x0", x0)?, num("y0", y0)?, num("x1", x1)?, num("y1", y1)?);
if !(x0 < x1 && y0 < y1) {
return Err(WindowError::Order);
}
let w = Bounds2 { min: Vec2::new(x0, y0), max: Vec2::new(x1, y1) };
cadcraft_io::check_window(&w)?;
Ok(w)
}
/// `run --cmd 'id {json}'`: the id up to the first space, then JSON parameters (default `{}`).
/// Whether they suit the command is the command's to say.
fn cmd_step(s: &str) -> Result<CmdStep, ValueError> {
let (id, json) = s.split_once(' ').unwrap_or((s, "{}"));
if id.is_empty() {
return Err(ValueError::CmdId);
}
Ok(CmdStep { id: id.to_string(), params: serde_json::from_str(json)? })
}
impl FramingArgs {
/// The framing `--window` or `--view` asks for (clap refuses both together).
pub(crate) fn framing(&self) -> Framing {
match (self.window, self.view) {
(Some(w), _) => Framing::Window(w),
(None, Some(ViewMode::Extents)) => Framing::Extents,
(None, Some(ViewMode::Current)) => Framing::Current,
(None, None) => Framing::Auto,
}
}
/// The framing flag given, if any.
fn flag(&self) -> Option<&'static str> {
if self.window.is_some() {
Some("--window")
} else if self.view.is_some() {
Some("--view")
} else {
None
}
}
}
/// A framing flag given with an output that isn't an image (the extension decides). `run` without
/// `--export` is clap's `requires` error.
fn framing_error(cli: &Cli) -> Option<UsageError> {
let (framing, out): (&FramingArgs, Option<&Path>) = match &cli.command {
Command::Convert(c) => (&c.framing, Some(&c.output)),
Command::Run(r) => (&r.framing, r.export.as_deref()),
_ => return None,
};
let (flag, out) = (framing.flag()?, out?);
(!cadcraft_io::is_image(out)).then(|| UsageError::FramingNeedsImage { flag, out: out.to_path_buf() })
}
/// An output that is the same file as an input, without `--in-place`. An output that doesn't exist
/// can't be an input, and an I/O error in the comparison is left to the open or write that follows.
fn out_is_input(cli: &Cli) -> Option<UsageError> {
let same = |input: &Path, out: &Path| out.exists() && same_file::is_same_file(input, out).unwrap_or(false);
match &cli.command {
Command::Convert(c) if !c.in_place && same(&c.input, &c.output) => Some(UsageError::OutIsInput(c.output.clone())),
Command::Run(r) if !r.in_place => {
let inputs = r.drawings.iter().filter_map(|d| if let Drawing::File(f) = d { Some(f) } else { None });
let inputs: Vec<&PathBuf> = inputs.collect();
[&r.save, &r.export].into_iter().flatten().find(|out| inputs.iter().any(|i| same(i, out))).map(|out| UsageError::OutIsInput(out.clone()))
}
_ => None,
}
}
/// The backend `cadcraft-cli mcp` serves from.
#[derive(Debug, PartialEq, Eq)]
pub(crate) enum McpTarget {
/// An in-process drawing session (no `--connect`).
Headless,
/// The running app's control channel at `HOST:PORT`; `lazy`: reached at the first call;
/// `launch`: opened then if it isn't running.
Connect { addr: String, lazy: bool, launch: bool },
}
impl McpArgs {
pub(crate) fn target(&self) -> McpTarget {
match &self.connect {
// `--launch` connects at the first call too (the app opens then).
Some(addr) => McpTarget::Connect { addr: addr.clone(), lazy: self.lazy || self.launch, launch: self.launch },
None => McpTarget::Headless,
}
}
}
/// `mcp --connect`: an empty, flag-like or port-less address is an error, never a silent fall back
/// to a headless session (#103). The host is not resolved here.
fn connect_addr(s: &str) -> Result<String, ValueError> {
let s = s.trim();
let valid = !s.starts_with('-')
&& s.rsplit_once(':').is_some_and(|(host, port)| {
let host = host.strip_prefix('[').and_then(|h| h.strip_suffix(']')).unwrap_or(host);
!host.is_empty() && port.parse::<u16>().is_ok()
});
if valid { Ok(s.to_string()) } else { Err(ValueError::Connect) }
}
/// The values of `id` with their command-line indices.
fn indexed<'a, T: Clone + Send + Sync + 'static>(m: &'a ArgMatches, id: &str) -> impl Iterator<Item = (usize, &'a T)> {
let at = m.indices_of(id).into_iter().flatten();
let values = m.try_get_many::<T>(id).ok().flatten().into_iter().flatten();
at.zip(values)
}
/// The command-line index of flag `id`, when it was given.
fn flag_index(m: &ArgMatches, id: &str) -> Option<usize> {
if m.value_source(id) == Some(ValueSource::CommandLine) { m.indices_of(id).and_then(Iterator::last) } else { None }
}
/// `run`'s drawings and steps back in command-line order: clap keeps each flag's values apart,
/// their indices say how they interleave.
fn run_order(m: &ArgMatches) -> (Vec<Drawing>, Vec<Step>) {
let mut drawings: Vec<(usize, Drawing)> = indexed(m, "files").map(|(i, f): (_, &PathBuf)| (i, Drawing::File(f.clone()))).collect();
drawings.extend(flag_index(m, "sample").map(|i| (i, Drawing::Sample)));
drawings.extend(flag_index(m, "metric").map(|i| (i, Drawing::Metric)));
drawings.sort_by_key(|d| d.0);
let mut steps: Vec<(usize, Step)> = indexed(m, "script").map(|(i, s): (_, &String)| (i, Step::Script(s.clone()))).collect();
steps.extend(indexed(m, "script_file").map(|(i, s): (_, &PathBuf)| (i, Step::ScriptFile(s.clone()))));
steps.extend(indexed(m, "cmd").map(|(i, c): (_, &CmdStep)| (i, Step::Cmd(c.clone()))));
steps.sort_by_key(|s| s.0);
(drawings.into_iter().map(|d| d.1).collect(), steps.into_iter().map(|s| s.1).collect())
}
/// Parse the arguments (without the binary name). clap reads them as `OsString`s: a path need not
/// be valid Unicode, text must. A bare `--help` or `-h` is help even after a mistake on the same
/// line (`run --script --help`): clap reports the mistake first.
pub(crate) fn parse(args: &[OsString]) -> Result<Cli, clap::Error> {
parse_with(command(|k| std::env::var_os(k)), args)
}
/// The command line. An empty or blank variable counts as unset, except `CADCRAFT_CONFIG_DIR`:
/// empty means no settings folder. `var` looks a variable up.
fn command(var: impl Fn(&OsStr) -> Option<OsString> + Copy) -> clap::Command {
let blank = move |a: clap::Arg| if a.get_id() == "config_dir" { a } else { blank_env_is_unset(a, var) };
Cli::command().mut_args(blank).mut_subcommands(|s| s.mut_args(blank))
}
/// [`parse`] with `cmd` from [`command`]; a bad value from a variable is a usage error naming the
/// variable.
fn parse_with(mut cmd: clap::Command, args: &[OsString]) -> Result<Cli, clap::Error> {
let argv = std::iter::once(OsString::from("cadcraft-cli")).chain(args.iter().cloned());
let matches = match cmd.try_get_matches_from_mut(argv) {
// `use_stderr`: a real error, not the help `-h` asked for (a retry would make it `--help`).
Err(e) if e.use_stderr() && args.iter().take_while(|a| *a != "--").any(|a| *a == "--help" || *a == "-h") => {
let help = [OsString::from("cadcraft-cli"), args.first().cloned().unwrap_or_default(), OsString::from("--help")];
return Err(cmd.try_get_matches_from_mut(help).err().unwrap_or(e));
}
matches => matches.map_err(|e| name_env_vars(e, &cmd, args))?,
};
let mut cli = Cli::from_arg_matches(&matches)?;
if let (Command::Run(r), Some((_, m))) = (&mut cli.command, matches.subcommand()) {
(r.drawings, r.steps) = run_order(m);
}
if let Some(e) = framing_error(&cli).or_else(|| out_is_input(&cli)) {
if let Some(sub) = matches.subcommand_name().and_then(|n| cmd.find_subcommand_mut(n)) {
return Err(e.into_clap(sub));
}
return Err(e.into_clap(&mut cmd));
}
Ok(cli)
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
fn parse_args(a: &[&str]) -> Result<Cli, clap::Error> {
parse(&a.iter().map(OsString::from).collect::<Vec<_>>())
}
fn mcp(a: &[&str]) -> Result<McpTarget, clap::Error> {
let args: Vec<&str> = std::iter::once("mcp").chain(a.iter().copied()).collect();
match parse_args(&args)?.command {
Command::Mcp(m) => Ok(m.target()),
_ => panic!("{a:?} is not mcp"),
}
}
/// Every file argument's help names each format of the list it uses.
#[test]
fn help_names_every_format() {
let cli = Cli::command();
let help = |sub: &str, arg: &str| {
let a = cli.find_subcommand(sub).and_then(|c| c.get_arguments().find(|a| a.get_id() == arg)).expect("argument exists");
a.get_help().map(|h| h.to_string()).unwrap_or_default()
};
let cases: [(&str, &str, &[Format]); 8] = [
("info", "file", Format::READ),
("convert", "input", Format::READ),
("convert", "output", Format::WRITE),
("run", "files", Format::READ),
("run", "save", Format::WRITE),
("run", "export", Format::WRITE),
("sample", "output", Format::WRITE),
("convert", "", Format::WRITE),
];
for (sub, arg, list) in cases {
let text = if arg.is_empty() {
cli.find_subcommand(sub).and_then(|c| c.get_about()).map(|a| a.to_string()).unwrap_or_default()
} else {
help(sub, arg)
};
for f in list {
assert!(text.contains(f.extension()), "`{sub} {arg}` help `{text}` lacks {}", f.extension());
}
}
}
#[test]
fn mcp_without_connect_is_headless() {
assert_eq!(mcp(&[]).unwrap(), McpTarget::Headless);
}
#[test]
fn mcp_connect_with_address_selects_remote() {
let to = |addr: &str, lazy, launch| McpTarget::Connect { addr: addr.into(), lazy, launch };
assert_eq!(mcp(&["--connect", "127.0.0.1:7979"]).unwrap(), to("127.0.0.1:7979", false, false));
assert_eq!(mcp(&["--connect", " localhost:7979 "]).unwrap(), to("localhost:7979", false, false));
assert_eq!(mcp(&["--lazy", "--connect", "localhost:7979"]).unwrap(), to("localhost:7979", true, false));
assert_eq!(mcp(&["--connect", "localhost:7979", "--launch"]).unwrap(), to("localhost:7979", true, true));
assert_eq!(mcp(&["--connect", "[::1]:7979"]).unwrap(), to("[::1]:7979", false, false));
// Without an app to reach they mean nothing: never a headless session.
for flag in ["--lazy", "--launch"] {
assert_eq!(mcp(&[flag]).unwrap_err().kind(), clap::error::ErrorKind::MissingRequiredArgument, "{flag}");
}
}
#[test]
fn mcp_connect_without_address_is_an_error_not_headless() {
for bad in [
&["--connect"][..],
&["--connect", ""],
&["--connect", " "],
&["--connect=-v"],
&["--connect", "example.com"],
&["--connect", ":7979"],
&["--connect", "host:99999"],
&["--connect", "[]:1"],
] {
let r = mcp(bad);
let Err(e) = r else { panic!("{bad:?} should be rejected, got {r:?}") };
assert_eq!(e.exit_code(), 2, "{bad:?}");
assert!(e.to_string().contains("--connect <HOST:PORT>"), "{bad:?}: {e}");
}
}
#[test]
fn mcp_rejects_unknown_and_repeated_arguments() {
assert!(mcp(&["--conect", "127.0.0.1:7979"]).is_err());
assert!(mcp(&["127.0.0.1:7979"]).is_err());
// clap names the unknown flag, not the value it left missing.
for flag in ["--foo", "-v"] {
assert_eq!(mcp(&["--connect", flag]).unwrap_err().kind(), clap::error::ErrorKind::UnknownArgument, "{flag}");
}
assert!(mcp(&["--connect", "127.0.0.1:1", "--connect", "127.0.0.1:2"]).is_err());
}
#[test]
fn run_keeps_command_line_order() {
let args =
["run", "a.dxf", "--script", "S1", "--metric", "--cmd", "c1", "b.dxf", "--script-file", "f.scr", "--sample", "--cmd", "c2 {\"n\":1}"];
let Command::Run(r) = parse_args(&args).unwrap().command else { panic!("not run") };
let file = |f: &str| Drawing::File(f.into());
let cmd = |id: &str, params| Step::Cmd(CmdStep { id: id.into(), params });
assert_eq!(r.drawings, [file("a.dxf"), Drawing::Metric, file("b.dxf"), Drawing::Sample]);
assert_eq!(r.steps, [Step::Script("S1".into()), cmd("c1", json!({})), Step::ScriptFile("f.scr".into()), cmd("c2", json!({"n": 1}))]);
}
#[test]
fn cmd_values() {
assert_eq!(cmd_step("line").unwrap(), CmdStep { id: "line".into(), params: json!({}) });
assert_eq!(cmd_step("line [1]").unwrap(), CmdStep { id: "line".into(), params: json!([1]) });
for bad in ["", " {}", "line {bad json", "line "] {
assert!(cmd_step(bad).is_err(), "`{bad}` should be rejected");
}
}
#[test]
fn perf_targets() {
let target = |a: &[&str]| -> Option<PerfTarget> {
let args: Vec<&str> = std::iter::once("perf").chain(a.iter().copied()).collect();
let Command::Perf(p) = parse_args(&args).unwrap().command else { panic!("not perf") };
p.target
};
assert_eq!(target(&[]), None);
assert_eq!(target(&["5"]), Some(PerfTarget::Count(5)));
assert_eq!(target(&["0"]), Some(PerfTarget::Count(1)));
assert_eq!(target(&["999999999"]), Some(PerfTarget::Count(MAX_PERF_COUNT)));
assert_eq!(target(&["a.dxf"]), Some(PerfTarget::File("a.dxf".into())));
assert_eq!(target(&["1e3"]), Some(PerfTarget::File("1e3".into())));
}
#[test]
fn framing_options() {
let framing = |out: &str, a: &[&str]| -> Result<Framing, clap::Error> {
let args: Vec<&str> = ["convert", "a.dxf", out].iter().chain(a).copied().collect();
let Command::Convert(c) = parse_args(&args)?.command else { panic!("not convert") };
Ok(c.framing.framing())
};
let b = |x0, y0, x1, y1| Bounds2::new(Vec2::new(x0, y0), Vec2::new(x1, y1));
assert_eq!(framing("b.png", &[]).unwrap(), Framing::Auto);
assert_eq!(framing("b.png", &["--view", "extents"]).unwrap(), Framing::Extents);
assert_eq!(framing("b.png", &["--view", "CURRENT"]).unwrap(), Framing::Current);
assert_eq!(framing("b.png", &["--window", "0,0,2,1"]).unwrap(), Framing::Window(b(0.0, 0.0, 2.0, 1.0)));
assert_eq!(framing("b.dxf", &[]).unwrap(), Framing::Auto);
let kind = |out: &str, a: &[&str]| framing(out, a).map(|_| ()).unwrap_err().kind();
assert_eq!(kind("b.png", &["--view", "selection"]), ErrorKind::InvalidValue);
assert_eq!(kind("b.png", &["--window", "0,0,2,1", "--view", "extents"]), ErrorKind::ArgumentConflict);
assert_eq!(kind("b.dxf", &["--view", "extents"]), ErrorKind::ArgumentConflict);
assert_eq!(kind("b.dxf", &["--window", "0,0,2,1"]), ErrorKind::ArgumentConflict);
}
#[test]
fn window_parses() {
let b = |x0, y0, x1, y1| Bounds2::new(Vec2::new(x0, y0), Vec2::new(x1, y1));
assert_eq!(parse_window("0,0,30,20").unwrap(), b(0.0, 0.0, 30.0, 20.0));
assert_eq!(parse_window(" -5.5, -1e3 ,2e3,4 ").unwrap(), b(-5.5, -1000.0, 2000.0, 4.0));
}
#[test]
fn hostile_window_is_an_error() {
for w in [
"",
"1,2,3",
"1,2,3,4,5",
"a,0,1,1",
"NaN,0,1,1",
"0,0,inf,1",
"0,0,1e400,1",
"0,0,0,1",
"0,0,1,0",
"5,0,1,1",
"0,5,1,1",
"-1e300,-1e300,1e300,1e300",
"0,0,1e-12,1e-12",
] {
assert!(parse_window(w).is_err(), "`{w}` should be rejected");
}
}
/// The subcommands that draw or run commands take the settings flags; the others refuse them.
#[test]
fn settings_flags() {
let Command::Convert(c) =
parse_args(&["convert", "a.dxf", "b.png", "--config-dir", "/p", "--fontalt", "Noto Sans", "--fontfallback="]).unwrap().command
else {
panic!("not convert")
};
assert_eq!(c.settings.config_dir, Some(PathBuf::from("/p")));
assert_eq!((c.settings.fontalt.as_deref(), c.settings.fontfallback.as_deref()), (Some("Noto Sans"), Some("")));
for empty in ["--config-dir=", "--config-dir= "] {
let Command::Run(r) = parse_args(&["run", "--sample", empty]).unwrap().command else { panic!("not run") };
assert_eq!(r.settings.settings_dir(), None, "`{empty}` is no settings folder");
}
let Command::Convert(c) = parse_args(&["convert", "a.dxf", "b.png", "--config-dir", "/p"]).unwrap().command else { panic!("not convert") };
assert_eq!(c.settings.settings_dir(), Some(PathBuf::from("/p")));
assert!(parse_args(&["sample", "bracket", "b.dxf", "--fontalt", "x"]).is_ok());
assert!(parse_args(&["mcp", "--config-dir", "/p"]).is_ok());
assert!(parse_args(&["info", "a.dxf", "--config-dir", "/p"]).is_err());
}
#[test]
fn blank_variables_count_as_unset_except_the_config_dir() {
let cmd = command(|_| Some("".into()));
for sub in cmd.get_subcommands().filter(|s| s.get_arguments().any(|a| a.get_id() == "fontalt")) {
let env = |id: &str| sub.get_arguments().find(|a| a.get_id() == id).and_then(|a| a.get_env());
assert_eq!((env("fontalt"), env("fontfallback")), (None, None), "{}", sub.get_name());
assert_eq!(env("config_dir"), Some(OsStr::new("CADCRAFT_CONFIG_DIR")), "{}", sub.get_name());
}
}
/// `--fontalt` falls back to `PATH` and rejects every value here, as a bad value from a
/// variable would; tests can't set a variable (`set_var` is unsafe).
#[test]
fn a_bad_value_from_a_variable_names_the_variable() {
// Cargo sets CARGO_PKG_NAME for every test binary, so the variable always has a value.
let reject = clap::builder::PossibleValuesParser::new(["never"]);
let cmd = || Cli::command().mut_subcommand("sample", |s| s.mut_arg("fontalt", |a| a.env("CARGO_PKG_NAME").value_parser(reject.clone())));
let args = |a: &[&str]| a.iter().map(OsString::from).collect::<Vec<_>>();
let text = parse_with(cmd(), &args(&["sample"])).err().map(|e| e.to_string()).unwrap_or_default();
assert!(text.contains("for 'CARGO_PKG_NAME'") && !text.contains("--fontalt"), "{text}");
let text = parse_with(cmd(), &args(&["sample", "--fontalt", "x"])).err().map(|e| e.to_string()).unwrap_or_default();
assert!(text.contains("--fontalt"), "{text}");
}
}
+17
View File
@@ -0,0 +1,17 @@
use super::args::CommandsArgs;
use super::error::Result;
use super::output::Streams;
use cadcraft_engine::Session;
use serde_json::Value;
pub(crate) fn commands(a: &CommandsArgs, io: &mut Streams) -> Result {
let s = Session::new();
let f = a.filter.as_ref().map(|x| x.to_ascii_lowercase());
let v: Vec<Value> = cadcraft_engine::command_specs()
.iter()
.filter(|c| f.as_ref().is_none_or(|f| c.id.contains(f.as_str()) || c.label.to_ascii_lowercase().contains(f.as_str())))
.map(|c| serde_json::to_value(c.info(&s)).unwrap_or_default())
.collect();
io.json(&Value::Array(v), a.compact);
Ok(())
}
+22
View File
@@ -0,0 +1,22 @@
use super::args::ConvertArgs;
use super::error::Result;
use super::output::{Streams, export_framed, export_window, skipped_message, undrawn_message};
use super::{open, unicode};
use cadcraft_engine::Session;
pub(crate) fn convert(a: &ConvertArgs, io: &mut Streams) -> Result {
let i = unicode(&a.input)?;
let framing = a.framing.framing();
let mut s = Session::empty();
open(&mut s, &a.input)?;
if let Some(m) = skipped_message(s.doc()?, i) {
io.errln(format_args!("{m}"));
}
if cadcraft_io::is_image(&a.output)
&& let Some(m) = undrawn_message(s.doc()?, i)
{
io.errln(format_args!("{m}"));
}
let window = export_window(&s, framing, None)?;
export_framed(&s, &a.output, window, io)
}
+29
View File
@@ -0,0 +1,29 @@
use crate::output::OutputError;
use crate::perf::PerfError;
use crate::run::RunError;
/// Why a subcommand failed: printed as `error: {e}`, exit 1.
#[derive(Debug, thiserror::Error)]
pub(crate) enum CliError {
#[error(transparent)]
Engine(#[from] cadcraft_engine::EngineError),
#[error(transparent)]
Doc(#[from] cadcraft_engine::doc::DocError),
#[error(transparent)]
Format(#[from] cadcraft_io::IoError),
#[error(transparent)]
Io(#[from] std::io::Error),
#[error(transparent)]
Run(#[from] RunError),
#[error(transparent)]
Output(#[from] OutputError),
#[error(transparent)]
Perf(#[from] PerfError),
/// The engine and io crates take file names as text.
#[error("{}: the file name is not valid Unicode", .0.display())]
NotUnicode(std::path::PathBuf),
#[error("cannot connect to {addr}: {source}")]
McpConnect { addr: String, source: std::io::Error },
}
pub(crate) type Result<T = (), E = CliError> = std::result::Result<T, E>;
+14
View File
@@ -0,0 +1,14 @@
use super::args::InfoArgs;
use super::error::Result;
use super::open;
use super::output::Streams;
use cadcraft_engine::Session;
use serde_json::json;
pub(crate) fn info(a: &InfoArgs, io: &mut Streams) -> Result {
let mut s = Session::empty();
open(&mut s, &a.file)?;
let v = s.execute("drawing.inspect", &json!({ "entities": false }))?;
io.json(&v, a.compact);
Ok(())
}
+315
View File
@@ -0,0 +1,315 @@
//! `cadcraft-cli`: headless CADCraft. The subcommands and their options are the clap types in
//! `args.rs`; `cadcraft-cli --help` lists them.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
use std::ffi::OsString;
use std::io::Write;
use cadcraft_engine::Session;
use serde_json::json;
mod args;
mod commands;
mod convert;
mod error;
mod info;
mod mcp;
mod output;
mod perf;
mod run;
mod sample;
#[cfg(test)]
use args::Framing;
use args::{Command, parse};
use clap::CommandFactory;
use commands::commands;
use convert::convert;
use error::Result;
use info::info;
use mcp::mcp;
use output::Streams;
#[cfg(test)]
use output::{export_window, model_views, write_atomic};
use perf::perf;
use run::run_cmds;
#[cfg(test)]
use run::{fill_last, returned_handle};
use sample::sample;
fn install_io() {
cadcraft_engine::cmd::file::set_io(cadcraft_engine::cmd::file::IoHooks {
read: |b, name| cadcraft_io::read(b, name).map_err(|e| e.to_string()),
write: |d, name| cadcraft_io::write(d, name).map_err(|e| e.to_string()),
plot: Some(|d, space, opts| cadcraft_io::plotter::plot(d, space, opts).map_err(|e| e.to_string())),
});
cadcraft_engine::cmd::file::set_write_as(|d, name, o| {
cadcraft_io::write_with(d, name, &cadcraft_io::SaveOptions { version: o.version, binary: o.binary }).map_err(|e| e.to_string())
});
// AutoLISP's entget, entmake and entmod see entities as DXF groups.
cadcraft_engine::cmd::file::set_entity_codec(cadcraft_engine::cmd::file::EntityCodec {
groups: cadcraft_io::entity_groups,
entity: cadcraft_io::entity_from_groups,
});
}
/// `path` as text, for the engine and io calls that take a file name as a string.
fn unicode(path: &std::path::Path) -> Result<&str> {
path.to_str().ok_or_else(|| error::CliError::NotUnicode(path.to_path_buf()))
}
fn open(s: &mut Session, path: &std::path::Path) -> Result {
s.execute("open", &json!({ "path": unicode(path)? }))?;
Ok(())
}
/// The command line's clap definition, for generating shell completions and man pages.
pub fn command() -> clap::Command {
args::Cli::command()
}
/// Run the CLI on its arguments (without the program name). Returns the process exit code (0 ok,
/// 1 failure, 2 usage). clap reads the arguments as they are: a value that is not valid Unicode
/// is a usage error, never a panic as with `std::env::args()`.
pub fn run<I, T>(args: I, out: &mut dyn Write, err: &mut dyn Write) -> i32
where
I: IntoIterator<Item = T>,
T: Into<OsString>,
{
let args: Vec<OsString> = args.into_iter().map(Into::into).collect();
// Help and `--version` (`help`, `-h`, `<subcommand> --help`, `-V`) come back as errors too,
// for `out`, exit 0: the subcommand never runs.
let cli = match parse(&args) {
Ok(cli) => cli,
Err(e) => {
let to: &mut dyn Write = if e.use_stderr() { err } else { out };
return match write!(to, "{}", e.render()) {
Err(w) if w.kind() != std::io::ErrorKind::BrokenPipe => {
let _ = writeln!(err, "error: can't write the output: {w}");
1
}
_ => e.exit_code(),
};
}
};
// The engine's hooks are set-once, so installing them on every call is harmless.
install_io();
match &cli.command {
Command::Convert(a) => a.settings.apply(),
Command::Run(a) => a.settings.apply(),
Command::Mcp(a) => a.settings.apply(),
Command::Sample(a) => a.settings.apply(),
Command::Info(_) | Command::Commands(_) | Command::Perf(_) => {}
}
let mut io = Streams::new(out, err);
let result = match &cli.command {
Command::Info(a) => info(a, &mut io),
Command::Convert(a) => convert(a, &mut io),
Command::Run(a) => run_cmds(a, &mut io),
Command::Commands(a) => commands(a, &mut io),
Command::Mcp(a) => mcp(a),
Command::Perf(a) => perf(a.target.as_ref(), &mut io),
Command::Sample(a) => sample(a, &mut io),
};
let mut code = 0;
if let Err(e) = result {
io.errln(format_args!("error: {e}"));
code = 1;
}
io.finish();
if io.stdout_failed() { 1 } else { code }
}
#[cfg(test)]
mod tests {
use super::*;
use cadcraft_engine::doc::Space;
use cadcraft_engine::geom::{Bounds2, Vec2};
fn scratch_dir(tag: &str) -> std::path::PathBuf {
let dir = std::env::temp_dir().join(format!("cadcraft-cli-{tag}-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).expect("create scratch dir");
dir
}
struct FailingWriter(std::io::ErrorKind);
impl Write for FailingWriter {
fn write(&mut self, _: &[u8]) -> std::io::Result<usize> {
Err(self.0.into())
}
fn flush(&mut self) -> std::io::Result<()> {
Ok(())
}
}
#[test]
fn a_failed_write_of_help_exits_1_unless_the_pipe_is_closed() {
let mut err = Vec::new();
assert_eq!(run(["--help"], &mut FailingWriter(std::io::ErrorKind::StorageFull), &mut err), 1);
assert!(String::from_utf8_lossy(&err).starts_with("error: "));
assert_eq!(run(["--help"], &mut FailingWriter(std::io::ErrorKind::BrokenPipe), &mut Vec::new()), 0);
}
#[test]
fn write_atomic_replaces_file_and_leaves_no_staging_files() {
let dir = scratch_dir("replace");
let out = dir.join("a.dxf");
write_atomic(&out, b"old").expect("create");
write_atomic(&out, b"new").expect("overwrite");
assert_eq!(std::fs::read(&out).expect("read"), b"new");
assert_eq!(std::fs::read_dir(&dir).expect("list").count(), 1);
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn write_atomic_failure_keeps_destination_and_cleans_up() {
let dir = scratch_dir("fail");
let out = dir.join("target");
std::fs::create_dir(&out).expect("dir as destination");
std::fs::write(out.join("keep"), b"x").expect("seed");
assert!(write_atomic(&out, b"new").is_err());
assert_eq!(std::fs::read(out.join("keep")).expect("kept"), b"x");
assert_eq!(std::fs::read_dir(&dir).expect("list").count(), 1);
let _ = std::fs::remove_dir_all(&dir);
}
fn b(x0: f64, y0: f64, x1: f64, y1: f64) -> Bounds2 {
Bounds2::new(Vec2::new(x0, y0), Vec2::new(x1, y1))
}
fn sample_session() -> Session {
let mut s = Session::empty();
s.open_drawing(cadcraft_engine::sample::default_sample(), "Bracket", None);
s
}
fn view_box(svg: &str) -> String {
let i = svg.find("viewBox=\"").map(|i| i + 9).unwrap_or(0);
svg[i..].split('"').next().unwrap_or("").to_string()
}
fn assert_near(a: Bounds2, e: Bounds2) {
let d = (a.min - e.min).len().max((a.max - e.max).len());
assert!(d < 1e-9, "{a:?} != {e:?}");
}
#[test]
fn last_placeholder_takes_the_previous_handle() {
let mut s = sample_session();
let r = s.execute("line", &json!({"points": [[0, 0], [10, 0]]})).unwrap();
let h = returned_handle(&s, &r).expect("LINE returns its handle");
assert_eq!(fill_last(&json!({"handle": "{last}"}), Some(h)).unwrap(), json!({"handle": h.hex()}));
// Nested, as in a selection list.
assert_eq!(fill_last(&json!({"handles": ["{last}", "1"]}), Some(h)).unwrap(), json!({"handles": [h.hex(), "1"]}));
// Only the exact token: a name or a sentence that merely contains it stays as written.
for p in [json!("last"), json!("{last} "), json!({"name": "last"})] {
assert_eq!(fill_last(&p, Some(h)).unwrap(), p);
}
// Nothing returned yet: an error, not a token passed to the command as a bad handle.
assert!(fill_last(&json!({"handle": "{last}"}), None).unwrap_err().to_string().contains("{last}"));
}
/// Handles are read from a result by looking the strings up in the drawing: counts and names
/// are not mistaken for handles, and `mview`'s `viewports` works like `handle`/`handles`.
#[test]
fn returned_handle_reads_only_real_handles() {
let mut s = Session::empty();
s.new_drawing(false);
s.execute("layout.set", &json!({"name": "Layout1"})).unwrap();
let r = s.execute("mview", &json!({"p1": [20, 20], "p2": [200, 150]})).unwrap();
let h = returned_handle(&s, &r).expect("mview returns its viewport handle");
assert!(r["viewports"].as_array().is_some_and(|a| a.iter().any(|v| v.as_str() == Some(h.hex().as_str()))), "{r}");
assert_eq!(returned_handle(&s, &json!({"changed": 3, "name": "A1"})), None);
// The most recent of several.
let a = s.execute("line", &json!({"points": [[0, 0], [1, 0]]})).unwrap();
let b = s.execute("line", &json!({"points": [[0, 0], [2, 0]]})).unwrap();
let (ha, hb) = (returned_handle(&s, &a).unwrap(), returned_handle(&s, &b).unwrap());
assert_eq!(returned_handle(&s, &json!({"handles": [ha.hex(), hb.hex()]})), Some(hb));
}
#[test]
fn default_framing_is_extents() {
// convert: nothing ran, always the extents.
let s = sample_session();
assert_eq!(export_window(&s, Framing::Auto, None).unwrap(), None);
// run: commands that leave the view alone keep the extents framing.
let mut s = sample_session();
let before = model_views(&s);
s.script("LINE 0,0 10,10\n\n").unwrap();
assert_eq!(export_window(&s, Framing::Auto, Some(&before)).unwrap(), None);
// A fresh drawing too.
let mut s = Session::empty();
s.new_drawing(false);
let before = model_views(&s);
s.execute("circle", &json!({"center": [0, 0], "radius": 5})).unwrap();
assert_eq!(export_window(&s, Framing::Auto, Some(&before)).unwrap(), None);
}
#[test]
fn zoom_window_frames_export() {
let mut s = sample_session();
let before = model_views(&s);
s.execute("zoom", &json!({"mode": "window", "p1": [0, 0], "p2": [30, 20]})).unwrap();
let w = export_window(&s, Framing::Auto, Some(&before)).unwrap().unwrap();
// The CLI viewport is 3:2, so a 3:2 window is shown exactly.
assert_near(w, b(0.0, 0.0, 30.0, 20.0));
assert_eq!(export_window(&s, Framing::Current, Some(&before)).unwrap(), Some(w));
// --view extents and --window override the zoom.
assert_eq!(export_window(&s, Framing::Extents, Some(&before)).unwrap(), None);
let explicit = b(1.0, 1.0, 2.0, 2.0);
assert_eq!(export_window(&s, Framing::Window(explicit), Some(&before)).unwrap(), Some(explicit));
// A taller window keeps its height; the 3:2 image adds room left and right.
s.execute("zoom", &json!({"mode": "center", "center": [5, 5], "height": 4})).unwrap();
assert_near(export_window(&s, Framing::Auto, Some(&before)).unwrap().unwrap(), b(2.0, 3.0, 8.0, 7.0));
}
#[test]
fn zoom_object_frames_the_selection() {
let mut s = sample_session();
let before = model_views(&s);
// The smallest entity with an area, selected then framed with ZOOM Object.
let d = s.doc().unwrap();
let bounds = |e: &cadcraft_engine::doc::Entity| cadcraft_engine::doc::entity_bounds(d, e, 0);
let e = d
.model
.iter()
.filter(|e| bounds(e).width() > 0.0 && bounds(e).height() > 0.0)
.min_by(|a, b| bounds(a).width().total_cmp(&bounds(b).width()))
.unwrap();
let (h, eb, ext) = (e.handle, bounds(e), d.extents(&Space::Model));
s.set_selection(vec![h]);
s.execute("zoom", &json!({"mode": "object"})).unwrap();
let w = export_window(&s, Framing::Auto, Some(&before)).unwrap().unwrap();
assert!(w.contains(eb.min) && w.contains(eb.max));
assert!(w.width() < ext.width() && w.height() < ext.height(), "{w:?} vs extents {ext:?}");
}
#[test]
fn run_export_honours_zoom() {
let dir = std::env::temp_dir().join(format!("cadcraft-cli-165-{}", std::process::id()));
std::fs::create_dir_all(&dir).unwrap();
let path = |n: &str| dir.join(n).to_string_lossy().to_string();
let run_svg = |extra: &[&str], out: &str| -> String {
let mut args: Vec<String> = ["run", "--sample"].iter().chain(extra).map(|a| a.to_string()).collect();
args.extend(["--export".to_string(), path(out)]);
assert_eq!(run(args, &mut Vec::new(), &mut Vec::new()), 0);
std::fs::read_to_string(path(out)).unwrap()
};
let base = run_svg(&[], "base.svg");
let zoomed = run_svg(&["--cmd", r#"zoom {"mode":"window","p1":[0,0],"p2":[30,20]}"#], "zoom.svg");
let window = run_svg(&["--window", "0,0,30,20"], "window.svg");
let forced = run_svg(&["--cmd", r#"zoom {"mode":"window","p1":[0,0],"p2":[30,20]}"#, "--view", "extents"], "forced.svg");
assert_ne!(view_box(&zoomed), view_box(&base));
assert_eq!(view_box(&zoomed), "0 0 30.000000 20.000000");
assert_eq!(zoomed, window);
assert_eq!(forced, base);
// Hostile --window: a usage error, nothing written.
let mut err = Vec::new();
assert_eq!(run(["run", "--sample", "--window", "0,0,NaN,1", "--export", &path("bad.png")], &mut Vec::new(), &mut err), 2);
assert!(String::from_utf8_lossy(&err).contains("--window"));
assert!(!dir.join("bad.png").exists());
let _ = std::fs::remove_dir_all(&dir);
}
}
File diff suppressed because it is too large Load Diff
+17
View File
@@ -0,0 +1,17 @@
use super::args::{McpArgs, McpTarget};
use super::error::{CliError, Result};
pub(crate) fn mcp(a: &McpArgs) -> Result {
let backend: Box<dyn cadcraft_mcp::Backend> = match a.target() {
McpTarget::Connect { addr, lazy: true, launch } => Box::new(cadcraft_mcp::Remote::lazy(&addr, launch)),
McpTarget::Connect { addr, .. } => match cadcraft_mcp::Remote::connect(&addr) {
Ok(r) => Box::new(r),
Err(source) => return Err(CliError::McpConnect { addr, source }),
},
McpTarget::Headless => Box::new(cadcraft_mcp::Headless::default()),
};
let stdin = std::io::stdin();
let stdout = std::io::stdout();
cadcraft_mcp::Server::new(backend).serve(stdin.lock(), stdout.lock())?;
Ok(())
}
+177
View File
@@ -0,0 +1,177 @@
use super::args::Framing;
use super::error::Result;
use cadcraft_engine::doc::Space;
use cadcraft_engine::geom::{Bounds2, Vec2};
use cadcraft_engine::{Session, View};
use std::io::Write;
use std::path::{Path, PathBuf};
/// The process's output streams. A write to stdout that fails never stops the program: once
/// stdout has failed, later output is dropped and the work goes on, so the rest of `run` (later
/// `--cmd` results, `--save`, `--export`) still happens and `cadcraft-cli run … --save out.dxf |
/// head` keeps the drawing. A reader that stopped early (a closed pipe, `cadcraft-cli commands |
/// head`) is not an error, as in ripgrep; any other write error is reported once on stderr and
/// makes the exit status 1.
pub(crate) struct Streams<'a> {
out: &'a mut dyn Write,
err: &'a mut dyn Write,
/// Set once a write to `out` has failed; later output is dropped.
gone: bool,
/// Set when `out` failed for a reason other than a closed reader.
failed: bool,
}
impl<'a> Streams<'a> {
pub(crate) fn new(out: &'a mut dyn Write, err: &'a mut dyn Write) -> Self {
Streams { out, err, gone: false, failed: false }
}
/// Write a line to stdout.
pub(crate) fn outln(&mut self, args: std::fmt::Arguments) {
if !self.gone
&& let Err(e) = writeln!(self.out, "{args}")
{
self.out_failed(e);
}
}
/// Write `v` to stdout: pretty-printed, or on one line with `compact` (`--compact`).
pub(crate) fn json(&mut self, v: &serde_json::Value, compact: bool) {
if compact {
self.outln(format_args!("{v}"));
} else {
self.outln(format_args!("{v:#}"));
}
}
/// Write a line to stderr. A failing stderr has nowhere to report to, so it is ignored.
pub(crate) fn errln(&mut self, args: std::fmt::Arguments) {
let _ = writeln!(self.err, "{args}");
}
/// Flush stdout (a pipe that closed during buffered output surfaces here).
pub(crate) fn finish(&mut self) {
if !self.gone
&& let Err(e) = self.out.flush()
{
self.out_failed(e);
}
}
/// Whether stdout failed for a reason other than a closed reader: the exit status is 1.
pub(crate) fn stdout_failed(&self) -> bool {
self.failed
}
fn out_failed(&mut self, e: std::io::Error) {
if std::mem::replace(&mut self.gone, true) || e.kind() == std::io::ErrorKind::BrokenPipe {
return;
}
self.errln(format_args!("cadcraft-cli: can't write to stdout: {e}"));
self.failed = true;
}
}
/// Why writing or framing an output failed.
#[derive(Debug, thiserror::Error)]
pub(crate) enum OutputError {
#[error("--view current: the drawing has no model-space view")]
NoModelView,
#[error("{}: {source}", path.display())]
Write { path: PathBuf, source: std::io::Error },
}
/// The model-space view of every open drawing, by drawing id (to tell whether commands changed it).
pub(crate) fn model_views(s: &Session) -> Vec<(u64, Option<View>)> {
s.docs.iter().map(|st| (st.uid, st.views.iter().find(|(sp, _)| *sp == Space::Model).map(|(_, v)| *v))).collect()
}
/// The active drawing's current model-space view as a rectangle with the viewport's aspect ratio
/// (the CLI viewport is 3:2 like the PNG export, so the image shows exactly this view).
fn current_window(s: &Session) -> Option<Bounds2> {
let st = s.state().ok()?;
let v = st.views.iter().find(|(sp, _)| *sp == Space::Model).map(|(_, v)| *v)?;
let (w, h) = s.viewport_px;
let half = Vec2::new(v.height * w / h.max(1.0), v.height) * 0.5;
Some(Bounds2::new(v.center - half, v.center + half))
}
/// The window an image export shows, or `None` to fit the extents. `before` is [`model_views`]
/// taken before the commands ran (`None` for `convert`, where nothing ran).
pub(crate) fn export_window(s: &Session, framing: Framing, before: Option<&[(u64, Option<View>)]>) -> Result<Option<Bounds2>, OutputError> {
match framing {
Framing::Window(w) => Ok(Some(w)),
Framing::Extents => Ok(None),
Framing::Current => current_window(s).map(Some).ok_or(OutputError::NoModelView),
Framing::Auto => {
let Some(before) = before else { return Ok(None) };
let Ok(st) = s.state() else { return Ok(None) };
let now = model_views(s);
let was = before.iter().find(|(uid, _)| *uid == st.uid);
let is = now.iter().find(|(uid, _)| *uid == st.uid);
// Only a view the commands changed counts; a drawing opened by the commands keeps
// the extents framing.
match (was, is) {
(Some(a), Some(b)) if a.1 != b.1 => Ok(current_window(s)),
_ => Ok(None),
}
}
}
}
/// Write `bytes` to `out` through the engine's atomic writer (an exclusively created sibling file
/// renamed over `out`), so a failed or interrupted write leaves the previous file untouched. An
/// existing `out` is resolved first: the rename would otherwise replace a symlink with a file and
/// leave the file it points to (`--in-place` through a link) unchanged.
pub(crate) fn write_atomic(out: &Path, bytes: &[u8]) -> Result<(), OutputError> {
let target = std::fs::canonicalize(out).unwrap_or_else(|_| out.to_path_buf());
cadcraft_engine::atomic_write::write_atomic(&target, bytes).map_err(|source| OutputError::Write { path: out.to_path_buf(), source })
}
pub(crate) fn export(s: &Session, out: &Path, io: &mut Streams) -> Result {
export_framed(s, out, None, io)
}
pub(crate) fn export_framed(s: &Session, out: &Path, window: Option<Bounds2>, io: &mut Streams) -> Result {
let d = s.doc()?;
let bytes = cadcraft_io::write_framed(d, out, window)?;
write_atomic(out, &bytes)?;
io.errln(format_args!("wrote {} ({} bytes)", out.display(), bytes.len()));
if cadcraft_engine::cmd::file::drops_unknown(out) {
let lost = cadcraft_engine::cmd::file::not_saved(d);
if let Some(m) = cadcraft_engine::cmd::file::not_saved_message(&lost) {
io.errln(format_args!("{m}"));
}
}
Ok(())
}
/// The warning for the model-space entities of `path` an image can't show, by type (those kept
/// as unknown objects, `Proxy` in `info`), or `None` when there are none.
pub(crate) fn undrawn_message(d: &cadcraft_engine::doc::Drawing, path: &str) -> Option<String> {
let mut types: std::collections::BTreeMap<&str, usize> = std::collections::BTreeMap::new();
for e in d.model.iter() {
if let cadcraft_engine::doc::EntityKind::Unknown(u) = &e.kind {
let n = types.entry(u.dxf_type.as_str()).or_insert(0);
*n = n.saturating_add(1);
}
}
let n = types.values().fold(0usize, |a, n| a.saturating_add(*n));
if n == 0 {
return None;
}
let list: Vec<String> = types.iter().map(|(t, n)| format!("{t}: {n}")).collect();
let entities = if n == 1 { "entity" } else { "entities" };
Some(format!("{path}: {n} {entities} not drawn ({})", list.join(", ")))
}
/// The warning for the records of `path` the reader could not place, or `None` when there are none.
pub(crate) fn skipped_message(d: &cadcraft_engine::doc::Drawing, path: &str) -> Option<String> {
let n = d.skipped_records.values().fold(0usize, |a, n| a.saturating_add(*n));
if n == 0 {
return None;
}
let list: Vec<String> = d.skipped_records.iter().map(|(section, n)| format!("{section}: {n}")).collect();
let records = if n == 1 { "record" } else { "records" };
Some(format!("{path}: {n} {records} could not be read and are left out ({})", list.join(", ")))
}
+196
View File
@@ -0,0 +1,196 @@
use super::args::PerfTarget;
use super::error::Result;
use super::open;
use super::output::Streams;
use cadcraft_engine::Session;
/// Why `perf` cannot run.
#[derive(Debug, thiserror::Error)]
pub(crate) enum PerfError {
#[error("perf: the drawing is empty")]
EmptyDrawing,
}
/// Small deterministic generator (xorshift64*) so perf runs are repeatable without a dependency.
struct Rng(u64);
impl Rng {
fn next(&mut self) -> f64 {
self.0 ^= self.0 >> 12;
self.0 ^= self.0 << 25;
self.0 ^= self.0 >> 27;
(self.0.wrapping_mul(0x2545_F491_4F6C_DD1D) >> 11) as f64 / (1u64 << 53) as f64
}
fn range(&mut self, lo: f64, hi: f64) -> f64 {
lo + (hi - lo) * self.next()
}
}
/// A synthetic drawing with `n` mixed entities (lines, circles, arcs, polylines, text) spread
/// over a square whose side grows with sqrt(n), so density stays constant.
fn synthetic(n: usize, side: f64) -> Result<cadcraft_engine::doc::Drawing, cadcraft_engine::doc::DocError> {
use cadcraft_engine::doc::{self as d, Common, EntityKind, Space};
use cadcraft_engine::geom::{PolyVertex, Vec2, Vec3};
let mut dr = d::Drawing::new_imperial();
let mut r = Rng(0x9E37_79B9_7F4A_7C15);
let v3 = |x: f64, y: f64| Vec3::new(x, y, 0.0);
for i in 0..n {
let (x, y) = (r.range(0.0, side), r.range(0.0, side));
let s = r.range(0.5, 8.0);
let kind = match i % 5 {
0 => EntityKind::Line(d::Line { a: v3(x, y), b: v3(x + r.range(-s, s), y + r.range(-s, s)) }),
1 => EntityKind::Circle(d::Circle { center: v3(x, y), radius: s * 0.5 }),
2 => EntityKind::Arc(d::Arc { center: v3(x, y), radius: s * 0.5, start: r.range(0.0, 3.0), end: r.range(3.2, 6.2) }),
3 => EntityKind::LwPolyline(d::LwPolyline {
vertices: (0..6)
.map(|k| PolyVertex {
p: Vec2::new(x + f64::from(k) * s * 0.3, y + r.range(-s, s) * 0.3),
bulge: if k == 2 { 0.4 } else { 0.0 },
start_width: 0.0,
end_width: 0.0,
})
.collect(),
closed: i % 2 == 0,
const_width: 0.0,
elevation: 0.0,
plinegen: false,
}),
_ => EntityKind::Text(d::Text {
insert: v3(x, y),
align_pt: None,
height: s * 0.2,
value: format!("T{i}"),
rotation: 0.0,
width_factor: 1.0,
oblique: 0.0,
style: "Standard".into(),
halign: d::HAlign::Left,
valign: d::VAlign::Baseline,
}),
};
dr.add(&Space::Model, Common::default(), kind)?;
}
Ok(dr)
}
/// `perf FILE`: the display list built as the canvas builds it (a 1600 x 1000 px view at the
/// drawing's centre: tolerance, dash level of detail and view window from the zoom band), at
/// zoom extents and zoomed in 4x at a time, next to the full-detail build plots use.
fn perf_file(path: &std::path::Path, io: &mut Streams) -> Result {
use cadcraft_engine::geom::{Bounds2, Vec2};
use cadcraft_engine::render::{Options, build};
use std::time::Instant;
let ms = |t: Instant| t.elapsed().as_secs_f64() * 1000.0;
let mut s = Session::empty();
let t = Instant::now();
open(&mut s, path)?;
let open_ms = ms(t);
let st = s.state()?;
let (d, space) = (&st.doc, &st.space);
let ext = d.extents(space);
let size = ext.width().max(ext.height());
if ext.is_empty() || !(size.is_finite() && size > 0.0) {
return Err(PerfError::EmptyDrawing.into());
}
io.outln(format_args!("open {open_ms:.0} ms, {} entities, extents {:.1} x {:.1}", d.entity_count(), ext.width(), ext.height()));
io.outln(format_args!("{:>8} {:>10} {:>10}", "zoom", "build ms", "prims"));
let mut finest = Options::default();
for k in 0..5 {
let zoom = 4f64.powi(k);
let h = size / zoom;
let pixel = 2f64.powi((h / 1000.0).max(1e-300).log2().floor() as i32);
let half = Vec2::new(h * 0.8, h * 0.5);
let visible = Bounds2::new(ext.center() - half, ext.center() + half);
let screen = Options { tolerance: pixel * 0.5, min_dash: pixel * 2.0, view: Some(visible.expand(h * 0.8)), ..Default::default() };
let t = Instant::now();
let n = build(d, space, &screen).prims.len();
io.outln(format_args!("{:>7}x {:>10.1} {n:>10}", zoom, ms(t)));
finest = screen;
}
// Plots: every pattern line, everywhere (last, so its large list doesn't weigh on the above).
let t = Instant::now();
let n = build(d, space, &Options { min_dash: 0.0, view: None, ..finest }).prims.len();
io.outln(format_args!("{:>8} {:>10.1} {n:>10}", "full", ms(t)));
Ok(())
}
pub(crate) fn perf(target: Option<&PerfTarget>, io: &mut Streams) -> Result {
use cadcraft_engine::doc::Space;
use cadcraft_engine::geom::{Bounds2, Vec2};
use cadcraft_engine::{select, snap};
use std::time::Instant;
let n = match target {
Some(PerfTarget::File(path)) => return perf_file(path, io),
Some(PerfTarget::Count(n)) => *n,
None => 200_000,
};
let side = (n as f64).sqrt() * 10.0;
let mut rows: Vec<(String, f64, String)> = Vec::new();
let ms = |t: Instant| t.elapsed().as_secs_f64() * 1000.0;
let t = Instant::now();
let d = synthetic(n, side)?;
rows.push(("build synthetic drawing".into(), ms(t), format!("{n} entities")));
// Display list at a 1600 px wide "zoom extents" view (tolerance = half a pixel).
let px = side / 1600.0;
let opts = cadcraft_engine::render::Options { tolerance: px * 0.5, min_dash: px * 2.0, ..Default::default() };
let t = Instant::now();
let list = cadcraft_engine::render::build(&d, &Space::Model, &opts);
rows.push(("display list build".into(), ms(t), format!("{} prims, {} segments", list.prims.len(), list.segment_count())));
// Hit testing on a zoomed-in view (aperture = 5 px at 0.02 units/px).
let ap = 0.1;
let mut r = Rng(42);
let pts: Vec<Vec2> = (0..1000).map(|_| Vec2::new(r.range(0.0, side), r.range(0.0, side))).collect();
let t = Instant::now();
let first = select::pick(&d, &Space::Model, pts.first().copied().unwrap_or(Vec2::ZERO), ap);
rows.push(("first pick (incl. index build)".into(), ms(t), format!("{first:?}")));
let t = Instant::now();
let hits = pts.iter().filter(|p| select::pick(&d, &Space::Model, **p, ap).is_some()).count();
let total = ms(t);
rows.push(("pick x1000".into(), total, format!("{hits} hits, {:.3} ms/pick", total / 1000.0)));
// One edit, then a pick: only the touched chunk is re-indexed.
let mut edited = d.clone();
if let Some(h) = edited.model.last().map(|e| e.handle) {
edited.model.modify(h, |e| e.common.layer = "0".into());
}
let t = Instant::now();
let _ = select::pick(&edited, &Space::Model, pts.first().copied().unwrap_or(Vec2::ZERO), ap);
rows.push(("pick after one edit (incremental re-index)".into(), ms(t), String::new()));
let mut sel = 0usize;
let t = Instant::now();
for k in 0..20 {
let c = Vec2::new(r.range(0.0, side), r.range(0.0, side));
let half = side * 0.05;
sel += select::select_window(&d, &Space::Model, Bounds2::new(c - Vec2::new(half, half), c + Vec2::new(half, half)), k % 2 == 1).len();
}
rows.push(("window/crossing select x20 (10% side)".into(), ms(t), format!("{sel} selected")));
let t = Instant::now();
let fence: Vec<Vec2> = (0..4).map(|_| Vec2::new(r.range(0.0, side), r.range(0.0, side))).collect();
let fsel = select::select_fence(&d, &Space::Model, &fence).len();
rows.push(("fence select (3 legs)".into(), ms(t), format!("{fsel} selected")));
let osmode = snap::mode::END | snap::mode::MID | snap::mode::CEN | snap::mode::QUA | snap::mode::INT;
let t = Instant::now();
let snaps = pts.iter().filter(|p| snap::osnap(&d, &Space::Model, **p, ap * 2.0, osmode, None, false).is_some()).count();
let total = ms(t);
rows.push(("osnap x1000".into(), total, format!("{snaps} hits, {:.3} ms/query", total / 1000.0)));
let t = Instant::now();
let bytes = cadcraft_io::write(&d, "perf.dxf")?;
rows.push(("DXF write".into(), ms(t), format!("{:.1} MB", bytes.len() as f64 / 1e6)));
let t = Instant::now();
let back = cadcraft_io::read(&bytes, "perf.dxf")?;
rows.push(("DXF read".into(), ms(t), format!("{} entities", back.entity_count())));
io.outln(format_args!("{:<40} {:>12} notes", "operation", "ms"));
io.outln(format_args!("{}", "-".repeat(80)));
for (name, t, note) in rows {
io.outln(format_args!("{name:<40} {t:>12.2} {note}"));
}
Ok(())
}
+223
View File
@@ -0,0 +1,223 @@
use super::args::{CmdStep, Drawing, RunArgs, Step};
use super::error::Result;
use super::open;
use super::output::{Streams, export, export_framed, export_window, model_views};
use cadcraft_engine::Session;
use cadcraft_engine::doc::Handle;
use serde_json::Value;
/// A `--cmd` parameter value of exactly `{last}` is filled in with the last object handle an
/// earlier `--cmd` in the same run returned: `mview` answers `{"viewports":["100"]}`, so
/// `viewport.set {"handle":"{last}","scale":1}` changes viewport 100. Any other string is passed
/// through unchanged, and `--script` text is never rewritten.
const LAST_HANDLE: &str = "{last}";
/// Why a `run` step fails.
#[derive(Debug, thiserror::Error)]
pub(crate) enum RunError {
#[error("{}: {source}", .path.display())]
ReadScript { path: std::path::PathBuf, source: std::io::Error },
#[error("--cmd {id}: {source}")]
CmdLast { id: String, source: NoLastHandle },
}
/// A `{last}` placeholder with no handle to fill in.
#[derive(Debug, PartialEq, thiserror::Error)]
#[error("`{{last}}` needs an earlier --cmd in this run to have returned a handle")]
pub(crate) struct NoLastHandle;
/// How deep [`result_handles`] walks a command result (results are the engine's own JSON).
const RESULT_DEPTH: usize = 16;
/// Result keys whose values are object references: the engine's result convention for handles.
/// A handle can be a string (`handle`, `viewport`, `insert`…) or a list of them (`handles`,
/// `viewports`, `members`…). Every other field may hold a user-defined name, a message or a
/// count, and is never read as a handle — a group named `100` is a name, not object `100`.
fn handle_field(key: &str) -> bool {
matches!(
key,
"handle"
| "handles"
| "viewport"
| "viewports"
| "boundary"
| "clip"
| "insert"
| "members"
| "source"
| "objects"
| "entities"
| "selection"
| "parts"
| "refs"
| "matches"
| "line"
| "arc"
| "blocks"
)
}
/// Collect the handles of `v`, a value under a handle field: a handle string, an array of them,
/// or objects that carry handle fields of their own (`entities`, `parts`).
fn collect_result_handles(s: &Session, v: &Value, depth: usize, out: &mut Vec<Handle>) {
if depth > RESULT_DEPTH {
return;
}
match v {
Value::String(t) => {
if let Some(h) = Handle::parse_hex(t)
&& s.doc().is_ok_and(|d| d.entity(h).is_some())
{
out.push(h);
}
}
Value::Array(a) => a.iter().for_each(|x| collect_result_handles(s, x, depth + 1, out)),
Value::Object(m) => {
for (k, x) in m {
if handle_field(k) {
collect_result_handles(s, x, depth + 1, out);
} else {
find_result_handles(s, x, depth + 1, out);
}
}
}
_ => {}
}
}
/// Find handle fields nested in containers that are not handles themselves (`groups` in
/// `groups.list`, whose members are handles): strings here are names, never references.
fn find_result_handles(s: &Session, v: &Value, depth: usize, out: &mut Vec<Handle>) {
if depth > RESULT_DEPTH {
return;
}
match v {
Value::Array(a) => a.iter().for_each(|x| find_result_handles(s, x, depth + 1, out)),
Value::Object(m) => {
for (k, x) in m {
if handle_field(k) {
collect_result_handles(s, x, depth + 1, out);
} else {
find_result_handles(s, x, depth + 1, out);
}
}
}
_ => {}
}
}
/// The object handles a command result mentions, in the order it lists them. A handle-only result
/// (a handle string or an array of them) counts as it is; otherwise only handle fields do.
fn result_handles(s: &Session, v: &Value, depth: usize, out: &mut Vec<Handle>) {
match v {
Value::String(_) => collect_result_handles(s, v, depth, out),
Value::Array(a) if a.iter().all(Value::is_string) => collect_result_handles(s, v, depth, out),
Value::Array(_) | Value::Object(_) => find_result_handles(s, v, depth, out),
_ => {}
}
}
/// The last handle `r` returned: what a later `{last}` stands for.
pub(crate) fn returned_handle(s: &Session, r: &Value) -> Option<Handle> {
let mut hs = Vec::new();
result_handles(s, r, 0, &mut hs);
hs.last().copied()
}
/// The active drawing's identity ([`cadcraft_engine::DocState::uid`]): a handle is only meaningful
/// in the drawing it came from, and `new`, `open`, `document.switch` and `close` can make another
/// drawing current.
fn active_drawing(s: &Session) -> Option<u64> {
s.docs.get(s.active).map(|st| st.uid)
}
/// Every `{last}` in `p`, at any depth, replaced by `h`. With no handle to fill in it is an
/// error, never a token reaching the command as a (bad) handle.
pub(crate) fn fill_last(p: &Value, h: Option<Handle>) -> Result<Value, NoLastHandle> {
match p {
Value::String(t) if t.as_str() == LAST_HANDLE => match h {
Some(h) => Ok(Value::String(h.hex())),
None => Err(NoLastHandle),
},
Value::Array(a) => a.iter().map(|x| fill_last(x, h)).collect::<Result<Vec<_>, _>>().map(Value::Array),
Value::Object(m) => {
m.iter().map(|(k, x)| Ok((k.clone(), fill_last(x, h)?))).collect::<Result<serde_json::Map<String, Value>, _>>().map(Value::Object)
}
other => Ok(other.clone()),
}
}
/// A step ready to run: script text, or a command.
enum Ready<'a> {
Script(String),
Cmd(&'a CmdStep),
}
pub(crate) fn run_cmds(a: &RunArgs, io: &mut Streams) -> Result {
let framing = a.framing.framing();
let (save, export_to) = (a.save.as_deref(), a.export.as_deref());
let mut s = Session::empty();
for d in &a.drawings {
match d {
Drawing::File(f) => open(&mut s, f)?,
Drawing::Sample => {
s.open_drawing(cadcraft_engine::sample::default_sample(), "Bracket", None);
}
Drawing::Metric => {
s.new_drawing(true);
}
}
}
let mut steps: Vec<Ready> = Vec::new();
for step in &a.steps {
steps.push(match step {
Step::Script(text) => Ready::Script(text.replace("\\n", "\n")),
Step::ScriptFile(p) => Ready::Script(std::fs::read_to_string(p).map_err(|source| RunError::ReadScript { path: p.clone(), source })?),
Step::Cmd(c) => Ready::Cmd(c),
});
}
if s.docs.is_empty() {
s.new_drawing(false);
}
let before = model_views(&s);
let mut last_handle: Option<Handle> = None;
for step in steps {
// A handle belongs to the drawing that returned it: if this step makes another drawing
// current (`new`, `open`, `document.switch`, `close`, or a script running one of them),
// the remembered handle is stale. A handle the step itself returns is taken afterwards,
// so it is a handle of the drawing it made current.
let drawing = active_drawing(&s);
match step {
Ready::Script(body) => {
s.script(&body)?;
if active_drawing(&s) != drawing {
last_handle = None;
}
}
Ready::Cmd(CmdStep { id, params }) => {
let params = fill_last(params, last_handle).map_err(|source| RunError::CmdLast { id: id.clone(), source })?;
let r = s.execute(id, &params)?;
if active_drawing(&s) != drawing {
last_handle = None;
}
if let Some(h) = returned_handle(&s, &r) {
last_handle = Some(h);
}
if !r.is_null() {
io.outln(format_args!("{r}"));
}
}
}
}
for l in &s.log {
io.errln(format_args!("{l}"));
}
if let Some(p) = save {
export(&s, p, io)?;
}
if let Some(p) = export_to {
let window = if cadcraft_io::is_image(p) { export_window(&s, framing, Some(&before))? } else { None };
export_framed(&s, p, window, io)?;
}
Ok(())
}
+14
View File
@@ -0,0 +1,14 @@
use super::args::{SampleArgs, SampleName};
use super::error::Result;
use super::output::{Streams, write_atomic};
pub(crate) fn sample(a: &SampleArgs, io: &mut Streams) -> Result {
let d = match a.name {
SampleName::Bracket => cadcraft_engine::sample::bracket(),
SampleName::Floorplan => cadcraft_engine::sample::floor_plan(),
};
let bytes = cadcraft_io::write(&d, &a.output)?;
write_atomic(&a.output, &bytes)?;
io.errln(format_args!("wrote {} ({} bytes)", a.output.display(), bytes.len()));
Ok(())
}
+7 -7
View File
@@ -1,23 +1,23 @@
//! `--help` is a request, not a failure (#1525): it goes to stdout with exit 0, like `--version`.
//! Bare `cadcraft-cli` keeps reporting on stderr with exit 1.
//! Bare `cadcraft-cli` is a usage error: the help on stderr, exit 2.
use std::process::Command;
#[test]
fn help_flags_print_usage_to_stdout_and_exit_zero() {
fn help_flags_print_help_to_stdout_and_exit_zero() {
for args in [&["--help"][..], &["-h"], &["help"]] {
let out = Command::new(env!("CARGO_BIN_EXE_cadcraft-cli")).args(args).output().expect("run cadcraft-cli");
assert!(out.status.success(), "{args:?}: {:?}", out.status);
let stdout = String::from_utf8_lossy(&out.stdout);
assert!(stdout.starts_with("usage:"), "{args:?}: {stdout:?}");
assert!(stdout.starts_with("cadcraft-cli: headless CADCraft\n"), "{args:?}: {stdout:?}");
assert!(String::from_utf8_lossy(&out.stderr).is_empty(), "{args:?}: stderr should be empty");
}
}
#[test]
fn bare_invocation_still_reports_on_stderr() {
fn bare_invocation_reports_on_stderr() {
let out = Command::new(env!("CARGO_BIN_EXE_cadcraft-cli")).output().expect("run cadcraft-cli");
assert_eq!(out.status.code(), Some(1));
assert!(out.stdout.is_empty(), "bare invocation keeps its usage on stderr");
assert!(String::from_utf8_lossy(&out.stderr).starts_with("usage:"));
assert_eq!(out.status.code(), Some(2));
assert!(out.stdout.is_empty(), "bare invocation keeps its help on stderr");
assert!(String::from_utf8_lossy(&out.stderr).starts_with("cadcraft-cli: headless CADCraft\n"));
}
+1
View File
@@ -4,3 +4,4 @@ mod help;
mod mcp_connect;
mod skipped_records;
mod undrawn_entities;
mod usage;
+6 -3
View File
@@ -33,12 +33,15 @@ fn replies(out: &Output) -> Vec<Value> {
#[test]
fn connect_without_address_fails_before_serving() {
let input = format!("{INIT}\n{CIRCLE}\n");
for args in [&["--connect"][..], &["--connect", ""], &["--connect", "--foo"]] {
// clap names an unknown flag rather than the value it left missing.
for (args, named) in
[(&["--connect"][..], "--connect <HOST:PORT>"), (&["--connect", ""], "--connect <HOST:PORT>"), (&["--connect", "--foo"], "'--foo'")]
{
let out = mcp(args, &input);
assert!(!out.status.success(), "{args:?} must exit non-zero");
assert_eq!(out.status.code(), Some(2), "{args:?} is a usage error");
assert!(out.stdout.is_empty(), "{args:?} must not answer MCP requests: {}", String::from_utf8_lossy(&out.stdout));
let err = String::from_utf8_lossy(&out.stderr);
assert!(err.contains("--connect needs HOST:PORT"), "{args:?}: {err}");
assert!(err.contains(named), "{args:?}: {err}");
}
}
+950
View File
@@ -0,0 +1,950 @@
//! The command line's behaviour: exit codes, streams and messages for help requests, unknown and
//! malformed options, value flags in both spellings, repeats and arity. Every case goes through
//! `invoke`, so the table rows are the record of what each input does. Usage errors are clap's
//! (exit 2, stderr); a subcommand's own failures are `error: …` with exit 1.
use std::path::{Path, PathBuf};
struct Invoke {
code: i32,
stdout: String,
stderr: String,
}
fn invoke(args: &[&str]) -> Invoke {
let (mut out, mut err) = (Vec::new(), Vec::new());
let code = cadcraft_cli::run(args, &mut out, &mut err);
Invoke { code, stdout: String::from_utf8_lossy(&out).into_owned(), stderr: String::from_utf8_lossy(&err).into_owned() }
}
/// What a stream holds.
#[derive(Clone, Copy)]
enum Expect {
Empty,
/// The first line equals this.
Line(&'static str),
/// The first line starts with this.
Starts(&'static str),
}
use Expect::{Empty, Line, Starts};
struct Case {
name: &'static str,
args: &'static [&'static str],
code: i32,
stdout: Expect,
stderr: Expect,
}
const fn case(name: &'static str, args: &'static [&'static str], code: i32, stdout: Expect, stderr: Expect) -> Case {
Case { name, args, code, stdout, stderr }
}
/// A scratch directory holding `b.dxf` (the bracket sample) and `s.scr` (a one-line script).
struct Scratch(PathBuf);
impl Scratch {
fn new(tag: &str) -> Scratch {
let dir = std::env::temp_dir().join(format!("cc-cli-usage-{tag}-{}", std::process::id()));
std::fs::create_dir_all(&dir).expect("create scratch dir");
let b = dir.join("b.dxf");
let r = invoke(&["sample", "bracket", b.to_str().expect("utf-8 path")]);
assert_eq!(r.code, 0, "{}", r.stderr);
std::fs::write(dir.join("s.scr"), "LINE 0,0 1,1\n").expect("write script");
Scratch(dir)
}
/// Replaces `{dir}` with the scratch directory and `{b}` with the sample drawing.
fn expand(&self, text: &str) -> String {
let dir = self.0.to_str().expect("utf-8 path");
text.replace("{b}", &Path::new(dir).join("b.dxf").to_string_lossy()).replace("{dir}", dir)
}
}
impl Drop for Scratch {
fn drop(&mut self) {
let _ = std::fs::remove_dir_all(&self.0);
}
}
fn check(what: &str, stream: &str, got: &str, expect: Expect, scratch: &Scratch) {
let first = got.lines().next().unwrap_or("");
match expect {
Empty => assert!(got.is_empty(), "{what}: {stream} should be empty, got {got:?}"),
Line(l) => assert_eq!(first, scratch.expand(l), "{what}: {stream}"),
Starts(p) => assert!(first.starts_with(&scratch.expand(p)), "{what}: {stream} should start with {p:?}, got {first:?}"),
}
}
fn run_cases(tag: &str, cases: &[Case]) {
let scratch = Scratch::new(tag);
for c in cases {
let args: Vec<String> = c.args.iter().map(|a| scratch.expand(a)).collect();
let args: Vec<&str> = args.iter().map(String::as_str).collect();
let what = format!("{}: {args:?}", c.name);
let r = invoke(&args);
assert_eq!(r.code, c.code, "{what}: exit code (stderr {:?})", r.stderr);
check(&what, "stdout", &r.stdout, c.stdout, &scratch);
check(&what, "stderr", &r.stderr, c.stderr, &scratch);
}
}
#[test]
fn top_level_requests() {
run_cases(
"top",
&[
case("--help", &["--help"], 0, Line("cadcraft-cli: headless CADCraft"), Empty),
case("-h", &["-h"], 0, Line("cadcraft-cli: headless CADCraft"), Empty),
case("help", &["help"], 0, Line("cadcraft-cli: headless CADCraft"), Empty),
case("--version", &["--version"], 0, Starts("cadcraft-cli "), Empty),
case("-V", &["-V"], 0, Starts("cadcraft-cli "), Empty),
case("version is not a subcommand", &["version"], 2, Empty, Line("error: unrecognized subcommand 'version'")),
case("bare", &[], 2, Empty, Line("cadcraft-cli: headless CADCraft")),
case("unknown subcommand", &["foo"], 2, Empty, Line("error: unrecognized subcommand 'foo'")),
case("unknown top-level flag", &["--bogus"], 2, Empty, Line("error: unexpected argument '--bogus' found")),
case("empty subcommand", &[""], 2, Empty, Line("error: unrecognized subcommand ''")),
],
);
}
/// Each subcommand's help, from `--help`, `-h` or `help <subcommand>`: its first line is the
/// subcommand's summary.
#[test]
fn subcommand_help_requests() {
run_cases(
"subhelp",
&[
case("info --help", &["info", "--help"], 0, Line("Print a drawing's summary as JSON"), Empty),
case("info -h", &["info", "-h"], 0, Line("Print a drawing's summary as JSON"), Empty),
case(
"convert --help",
&["convert", "--help"],
0,
Line("Convert a drawing; OUT's extension picks the format (dxf, dwg, dwt, svg, png, pdf)"),
Empty,
),
case(
"convert -h",
&["convert", "-h"],
0,
Line("Convert a drawing; OUT's extension picks the format (dxf, dwg, dwt, svg, png, pdf)"),
Empty,
),
case(
"run --help",
&["run", "--help"],
0,
Line("Open drawings (or start a new one), run scripts and commands in order, save or export the result"),
Empty,
),
case(
"run -h",
&["run", "-h"],
0,
Line("Open drawings (or start a new one), run scripts and commands in order, save or export the result"),
Empty,
),
case("commands --help", &["commands", "--help"], 0, Line("Print the command catalog as JSON"), Empty),
case(
"mcp --help",
&["mcp", "--help"],
0,
Line("Run the MCP server on stdio: a headless drawing session, or a bridge to the running app"),
Empty,
),
case(
"perf --help",
&["perf", "--help"],
0,
Line(
"Time the engine on a synthetic N-entity drawing (default 200000), or the canvas display-list build of a drawing, zoomed in step by step",
),
Empty,
),
case("sample --help", &["sample", "--help"], 0, Line("Write a built-in sample drawing"), Empty),
case(
"help run",
&["help", "run"],
0,
Line("Open drawings (or start a new one), run scripts and commands in order, save or export the result"),
Empty,
),
case("help info", &["help", "info"], 0, Line("Print a drawing's summary as JSON"), Empty),
case(
"help after a flag missing its value",
&["run", "--sample", "--script", "--help"],
0,
Line("Open drawings (or start a new one), run scripts and commands in order, save or export the result"),
Empty,
),
case(
"help after an unknown flag",
&["run", "--bogus", "--help"],
0,
Line("Open drawings (or start a new one), run scripts and commands in order, save or export the result"),
Empty,
),
case("help after an extra argument", &["info", "{b}", "extra", "-h"], 0, Line("Print a drawing's summary as JSON"), Empty),
case("--help after -- is a file name", &["run", "--", "--help"], 1, Empty, Starts("error: invalid parameters for `open`: --help:")),
case("run --version", &["run", "--version"], 2, Empty, Line("error: unexpected argument '--version' found")),
case("info --version", &["info", "--version"], 2, Empty, Line("error: unexpected argument '--version' found")),
],
);
}
#[test]
fn unknown_flags_on_every_subcommand() {
run_cases(
"unknown",
&[
case("info", &["info", "{b}", "--bogus"], 2, Empty, Line("error: unexpected argument '--bogus' found")),
case("info, flag first", &["info", "--bogus", "{b}"], 2, Empty, Line("error: unexpected argument '--bogus' found")),
case("info, short flag", &["info", "-x"], 2, Empty, Line("error: unexpected argument '-x' found")),
case("info, a file name starting with - after --", &["info", "--", "-x"], 1, Empty, Starts("error: invalid parameters for `open`: -x:")),
case("convert", &["convert", "{b}", "{dir}/o.svg", "--bogus"], 2, Empty, Line("error: unexpected argument '--bogus' found")),
case("run", &["run", "--sample", "--bogus"], 2, Empty, Line("error: unexpected argument '--bogus' found")),
case("run, flag first", &["run", "--bogus"], 2, Empty, Line("error: unexpected argument '--bogus' found")),
case("commands", &["commands", "--bogus"], 2, Empty, Line("error: unexpected argument '--bogus' found")),
case("commands -- ends the options", &["commands", "--"], 0, Line("["), Empty),
case("mcp", &["mcp", "--bogus"], 2, Empty, Line("error: unexpected argument '--bogus' found")),
case("mcp positional", &["mcp", "extra"], 2, Empty, Line("error: unexpected argument 'extra' found")),
case("perf", &["perf", "--bogus"], 2, Empty, Line("error: unexpected argument '--bogus' found")),
case("sample", &["sample", "--bogus"], 2, Empty, Line("error: unexpected argument '--bogus' found")),
case("sample after name", &["sample", "bracket", "--bogus"], 2, Empty, Line("error: unexpected argument '--bogus' found")),
],
);
}
/// `--x=v` is a spelling of `--x v`, and the one a value starting with `-` needs.
#[test]
fn value_flags_in_both_forms() {
run_cases(
"forms",
&[
case("--window v", &["convert", "{b}", "{dir}/w1.svg", "--window", "0,0,100,100"], 0, Empty, Starts("wrote {dir}/w1.svg (")),
case("--window=v", &["convert", "{b}", "{dir}/w2.svg", "--window=0,0,100,100"], 0, Empty, Starts("wrote {dir}/w2.svg (")),
case(
"run --window v",
&["run", "--sample", "--window", "0,0,100,100", "--export", "{dir}/w3.svg"],
0,
Empty,
Starts("wrote {dir}/w3.svg ("),
),
case(
"run --window=v",
&["run", "--sample", "--window=0,0,100,100", "--export", "{dir}/w4.svg"],
0,
Empty,
Starts("wrote {dir}/w4.svg ("),
),
case("--view v", &["convert", "{b}", "{dir}/v1.svg", "--view", "extents"], 0, Empty, Starts("wrote {dir}/v1.svg (")),
case("--view=v", &["convert", "{b}", "{dir}/v2.svg", "--view=extents"], 0, Empty, Starts("wrote {dir}/v2.svg (")),
case("run --view v", &["run", "--sample", "--view", "current", "--export", "{dir}/v3.svg"], 0, Empty, Starts("wrote {dir}/v3.svg (")),
case("run --view=v", &["run", "--sample", "--view=extents", "--export={dir}/v4.svg"], 0, Empty, Starts("wrote {dir}/v4.svg (")),
case("--script v", &["run", "--sample", "--script", "LINE 0,0 1,1"], 0, Empty, Line("Command: LINE")),
case("--script=v", &["run", "--sample", "--script=LINE 0,0 1,1"], 0, Empty, Line("Command: LINE")),
case("--script-file v", &["run", "--sample", "--script-file", "{dir}/s.scr"], 0, Empty, Starts("Command: LINE")),
case("--script-file=v", &["run", "--sample", "--script-file={dir}/s.scr"], 0, Empty, Starts("Command: LINE")),
case("--cmd v", &["run", "--sample", "--cmd", "nosuch"], 1, Empty, Line("error: unknown command `nosuch`")),
case("--cmd=v", &["run", "--sample", "--cmd=nosuch"], 1, Empty, Line("error: unknown command `nosuch`")),
case("--cmd=-v", &["run", "--sample", "--cmd=-x"], 1, Empty, Line("error: unknown command `-x`")),
case("--save v", &["run", "--sample", "--save", "{dir}/s1.dxf"], 0, Empty, Starts("wrote {dir}/s1.dxf (")),
case("--save=v", &["run", "--sample", "--save={dir}/s2.dxf"], 0, Empty, Starts("wrote {dir}/s2.dxf (")),
case("--export v", &["run", "--sample", "--export", "{dir}/e1.svg"], 0, Empty, Starts("wrote {dir}/e1.svg (")),
case("--export=v", &["run", "--sample", "--export={dir}/e2.svg"], 0, Empty, Starts("wrote {dir}/e2.svg (")),
case(
"--window=-v: negative coordinates need =",
&["convert", "{b}", "{dir}/w5.svg", "--window=-1000,-1000,1000,1000"],
0,
Empty,
Starts("wrote {dir}/w5.svg ("),
),
case(
"--window -v: a value starting with - is a flag",
&["convert", "{b}", "{dir}/w6.svg", "--window", "-1000,-1000,1000,1000"],
2,
Empty,
Line("error: unexpected argument '-1' found"),
),
case("--connect v", &["mcp", "--connect", "127.0.0.1:1"], 1, Empty, Starts("error: cannot connect to 127.0.0.1:1:")),
case("--connect=v", &["mcp", "--connect=127.0.0.1:1"], 1, Empty, Starts("error: cannot connect to 127.0.0.1:1:")),
],
);
}
/// A value flag at the end of the arguments, or followed by another flag, is missing its value:
/// a flag is never taken as a value.
#[test]
fn flags_missing_their_value() {
run_cases(
"missing",
&[
case(
"convert --window last",
&["convert", "{b}", "{dir}/o.svg", "--window"],
2,
Empty,
Line("error: a value is required for '--window <x0,y0,x1,y1>' but none was supplied"),
),
case(
"convert --view last",
&["convert", "{b}", "{dir}/o.svg", "--view"],
2,
Empty,
Line("error: a value is required for '--view <extents|current>' but none was supplied"),
),
case(
"convert --window then flag",
&["convert", "{b}", "{dir}/o.svg", "--window", "--view", "extents"],
2,
Empty,
Line("error: a value is required for '--window <x0,y0,x1,y1>' but none was supplied"),
),
case(
"convert --view then flag",
&["convert", "{b}", "{dir}/o.svg", "--view", "--window", "0,0,1,1"],
2,
Empty,
Line("error: a value is required for '--view <extents|current>' but none was supplied"),
),
case(
"run --window last",
&["run", "--sample", "--window"],
2,
Empty,
Line("error: a value is required for '--window <x0,y0,x1,y1>' but none was supplied"),
),
case(
"run --view last",
&["run", "--sample", "--view"],
2,
Empty,
Line("error: a value is required for '--view <extents|current>' but none was supplied"),
),
case(
"run --script last",
&["run", "--sample", "--script"],
2,
Empty,
Line("error: a value is required for '--script <TEXT>' but none was supplied"),
),
case(
"run --script then flag",
&["run", "--sample", "--script", "--sample"],
2,
Empty,
Line("error: a value is required for '--script <TEXT>' but none was supplied"),
),
case(
"run --script-file last",
&["run", "--script-file"],
2,
Empty,
Line("error: a value is required for '--script-file <F.scr>' but none was supplied"),
),
case(
"run --script-file then flag",
&["run", "--sample", "--script-file", "--sample"],
2,
Empty,
Line("error: a value is required for '--script-file <F.scr>' but none was supplied"),
),
case(
"run --cmd last",
&["run", "--sample", "--cmd"],
2,
Empty,
Line("error: a value is required for '--cmd <id {json}>' but none was supplied"),
),
case(
"run --cmd then flag",
&["run", "--sample", "--cmd", "--sample"],
2,
Empty,
Line("error: a value is required for '--cmd <id {json}>' but none was supplied"),
),
case(
"run --save last",
&["run", "--sample", "--save"],
2,
Empty,
Line("error: a value is required for '--save <OUT.dxf>' but none was supplied"),
),
case(
"run --export last",
&["run", "--sample", "--export"],
2,
Empty,
Line("error: a value is required for '--export <OUT.png>' but none was supplied"),
),
case(
"mcp --connect last",
&["mcp", "--connect"],
2,
Empty,
Line("error: a value is required for '--connect <HOST:PORT>' but none was supplied"),
),
case(
"mcp --connect then flag",
&["mcp", "--connect", "--lazy"],
2,
Empty,
Line("error: a value is required for '--connect <HOST:PORT>' but none was supplied"),
),
case(
"mcp --connect empty",
&["mcp", "--connect", " "],
2,
Empty,
Line("error: invalid value ' ' for '--connect <HOST:PORT>': expected HOST:PORT (the app's --control port, e.g. 127.0.0.1:7979)"),
),
case(
"mcp --connect without a port",
&["mcp", "--connect", "example.com"],
2,
Empty,
Line(
"error: invalid value 'example.com' for '--connect <HOST:PORT>': expected HOST:PORT (the app's --control port, e.g. 127.0.0.1:7979)",
),
),
case(
"mcp --connect port out of range",
&["mcp", "--connect", "host:99999"],
2,
Empty,
Line(
"error: invalid value 'host:99999' for '--connect <HOST:PORT>': expected HOST:PORT (the app's --control port, e.g. 127.0.0.1:7979)",
),
),
case(
"mcp --connect=-v",
&["mcp", "--connect=-v"],
2,
Empty,
Line("error: invalid value '-v' for '--connect <HOST:PORT>': expected HOST:PORT (the app's --control port, e.g. 127.0.0.1:7979)"),
),
],
);
}
#[test]
fn repeated_and_combined_flags() {
run_cases(
"repeat",
&[
case(
"--save twice",
&["run", "--sample", "--save", "{dir}/a.dxf", "--save", "{dir}/b2.dxf"],
2,
Empty,
Line("error: the argument '--save <OUT.dxf>' cannot be used multiple times"),
),
case(
"--export twice",
&["run", "--sample", "--export", "{dir}/x1.svg", "--export", "{dir}/x2.svg"],
2,
Empty,
Line("error: the argument '--export <OUT.png>' cannot be used multiple times"),
),
case(
"--window twice",
&["run", "--sample", "--window", "0,0,1,1", "--window", "0,0,2,2", "--export", "{dir}/ww.svg"],
2,
Empty,
Line("error: the argument '--window <x0,y0,x1,y1>' cannot be used multiple times"),
),
case(
"convert --window twice",
&["convert", "{b}", "{dir}/cw.svg", "--window", "0,0,1,1", "--window", "0,0,2,2"],
2,
Empty,
Line("error: the argument '--window <x0,y0,x1,y1>' cannot be used multiple times"),
),
case(
"--view twice, different",
&["run", "--sample", "--view", "extents", "--view", "current", "--export", "{dir}/vv.svg"],
2,
Empty,
Line("error: the argument '--view <extents|current>' cannot be used multiple times"),
),
case(
"--view twice, same",
&["run", "--sample", "--view", "extents", "--view", "extents", "--export", "{dir}/vs.svg"],
2,
Empty,
Line("error: the argument '--view <extents|current>' cannot be used multiple times"),
),
case("--sample twice", &["run", "--sample", "--sample"], 2, Empty, Line("error: the argument '--sample' cannot be used multiple times")),
case("--metric twice", &["run", "--metric", "--metric"], 2, Empty, Line("error: the argument '--metric' cannot be used multiple times")),
case(
"--lazy twice",
&["mcp", "--connect", "127.0.0.1:1", "--lazy", "--lazy"],
2,
Empty,
Line("error: the argument '--lazy' cannot be used multiple times"),
),
case(
"--launch twice",
&["mcp", "--connect", "127.0.0.1:1", "--launch", "--launch"],
2,
Empty,
Line("error: the argument '--launch' cannot be used multiple times"),
),
case(
"--script, --script-file and --cmd repeat",
&[
"run",
"--sample",
"--script",
"LINE 0,0 1,1",
"--script",
"LINE 0,0 2,2",
"--script-file",
"{dir}/s.scr",
"--script-file",
"{dir}/s.scr",
],
0,
Empty,
Starts("Command: LINE"),
),
case(
"--window and --view",
&["run", "--sample", "--window", "0,0,1,1", "--view", "extents", "--export", "{dir}/wv.svg"],
2,
Empty,
Line("error: the argument '--window <x0,y0,x1,y1>' cannot be used with '--view <extents|current>'"),
),
case(
"convert --window and --view",
&["convert", "{b}", "{dir}/cwv.svg", "--window", "0,0,1,1", "--view", "extents"],
2,
Empty,
Line("error: the argument '--window <x0,y0,x1,y1>' cannot be used with '--view <extents|current>'"),
),
case(
"--view is case-insensitive",
&["run", "--sample", "--view", "EXTENTS", "--export", "{dir}/vu.svg"],
0,
Empty,
Starts("wrote {dir}/vu.svg ("),
),
case(
"--connect twice",
&["mcp", "--connect", "127.0.0.1:1", "--connect", "127.0.0.1:2"],
2,
Empty,
Line("error: the argument '--connect <HOST:PORT>' cannot be used multiple times"),
),
case("--lazy without --connect", &["mcp", "--lazy"], 2, Empty, Line("error: the following required arguments were not provided:")),
case("--launch without --connect", &["mcp", "--launch"], 2, Empty, Line("error: the following required arguments were not provided:")),
case("--sample --metric: both accepted", &["run", "--sample", "--metric"], 0, Empty, Empty),
case("--sample and a file", &["run", "--sample", "{b}"], 0, Empty, Empty),
case("two files", &["run", "{b}", "{b}"], 0, Empty, Empty),
case(
"--window without export",
&["run", "--sample", "--window", "0,0,1,1"],
2,
Empty,
Line("error: the following required arguments were not provided:"),
),
case(
"--view without export",
&["run", "--sample", "--view", "current"],
2,
Empty,
Line("error: the following required arguments were not provided:"),
),
case(
"--window with a dxf output",
&["convert", "{b}", "{dir}/o.dxf", "--window", "0,0,1,1"],
2,
Empty,
Line("error: --window only applies to image output (png, svg, pdf), not `{dir}/o.dxf`"),
),
case(
"--view with a dxf output",
&["convert", "{b}", "{dir}/o.dxf", "--view", "extents"],
2,
Empty,
Line("error: --view only applies to image output (png, svg, pdf), not `{dir}/o.dxf`"),
),
case(
"run --window with a dxf export",
&["run", "--sample", "--window", "0,0,1,1", "--export", "{dir}/o.dxf"],
2,
Empty,
Line("error: --window only applies to image output (png, svg, pdf), not `{dir}/o.dxf`"),
),
case(
"run --view with a dxf export",
&["run", "--sample", "--view", "current", "--export", "{dir}/o.dxf"],
2,
Empty,
Line("error: --view only applies to image output (png, svg, pdf), not `{dir}/o.dxf`"),
),
],
);
}
#[test]
fn arity_and_positional_arguments() {
run_cases(
"arity",
&[
case("info without a file", &["info"], 2, Empty, Line("error: the following required arguments were not provided:")),
case("info with two files", &["info", "{b}", "extra"], 2, Empty, Line("error: unexpected argument 'extra' found")),
case("info missing file", &["info", "missing.dxf"], 1, Empty, Starts("error: invalid parameters for `open`: missing.dxf:")),
case("convert with no files", &["convert"], 2, Empty, Line("error: the following required arguments were not provided:")),
case("convert with one file", &["convert", "{b}"], 2, Empty, Line("error: the following required arguments were not provided:")),
case(
"convert with three files",
&["convert", "{b}", "{dir}/o.svg", "{dir}/x.svg"],
2,
Empty,
Line("error: unexpected argument '{dir}/x.svg' found"),
),
case("run missing file", &["run", "missing.dxf"], 1, Empty, Starts("error: invalid parameters for `open`: missing.dxf:")),
case("commands, no match", &["commands", "zzzznomatch"], 0, Line("[]"), Empty),
case(
"commands with an extra argument",
&["commands", "zzzznomatch", "extra"],
2,
Empty,
Line("error: unexpected argument 'extra' found"),
),
case("sample without arguments", &["sample"], 2, Empty, Line("error: the following required arguments were not provided:")),
case("sample without an output", &["sample", "bracket"], 2, Empty, Line("error: the following required arguments were not provided:")),
case(
"sample with a bad name",
&["sample", "nosuch", "{dir}/o.dxf"],
2,
Empty,
Line("error: invalid value 'nosuch' for '<bracket|floorplan>'"),
),
case(
"sample names are case-sensitive",
&["sample", "Bracket", "{dir}/o.dxf"],
2,
Empty,
Line("error: invalid value 'Bracket' for '<bracket|floorplan>'"),
),
case(
"sample with an empty output",
&["sample", "bracket", ""],
2,
Empty,
Line("error: a value is required for '<OUT>' but none was supplied"),
),
case("info with an empty file name", &["info", ""], 2, Empty, Line("error: a value is required for '<FILE>' but none was supplied")),
case("perf with an empty file name", &["perf", ""], 2, Empty, Line("error: a value is required for '[N|FILE]' but none was supplied")),
case(
"sample with an extra argument",
&["sample", "bracket", "{dir}/sx.dxf", "extra"],
2,
Empty,
Line("error: unexpected argument 'extra' found"),
),
case("sample floor alias", &["sample", "floor", "{dir}/sf.dxf"], 0, Empty, Starts("wrote {dir}/sf.dxf (")),
case("sample with a bad extension", &["sample", "bracket", "{dir}/o.xyz"], 1, Empty, Line("error: unsupported file type `xyz`")),
case("perf with a word", &["perf", "abc"], 1, Empty, Starts("error: invalid parameters for `open`: abc:")),
case("perf with a negative number", &["perf", "-5"], 2, Empty, Line("error: unexpected argument '-5' found")),
case("perf with a missing file", &["perf", "missing.dxf"], 1, Empty, Starts("error: invalid parameters for `open`: missing.dxf:")),
case("perf 1", &["perf", "1"], 0, Starts("operation"), Empty),
case("perf 0 is raised to 1", &["perf", "0"], 0, Starts("operation"), Empty),
case("perf with two counts", &["perf", "1", "2"], 2, Empty, Line("error: unexpected argument '2' found")),
],
);
}
#[test]
fn bad_values() {
run_cases(
"values",
&[
case(
"--view sideways",
&["convert", "{b}", "{dir}/o.svg", "--view", "sideways"],
2,
Empty,
Line("error: invalid value 'sideways' for '--view <extents|current>'"),
),
case(
"run --view sideways",
&["run", "--sample", "--view", "sideways"],
2,
Empty,
Line("error: invalid value 'sideways' for '--view <extents|current>'"),
),
case(
"--view sideways before the output check",
&["convert", "{b}", "{dir}/o.dxf", "--view", "sideways"],
2,
Empty,
Line("error: invalid value 'sideways' for '--view <extents|current>'"),
),
case(
"--window 3 numbers",
&["convert", "{b}", "{dir}/o.svg", "--window", "1,2,3"],
2,
Empty,
Line("error: invalid value '1,2,3' for '--window <x0,y0,x1,y1>': expected four numbers x0,y0,x1,y1"),
),
case(
"--window 5 numbers",
&["convert", "{b}", "{dir}/o.svg", "--window", "1,2,3,4,5"],
2,
Empty,
Line("error: invalid value '1,2,3,4,5' for '--window <x0,y0,x1,y1>': expected four numbers x0,y0,x1,y1"),
),
case(
"--window reversed",
&["convert", "{b}", "{dir}/o.svg", "--window", "3,3,1,1"],
2,
Empty,
Line("error: invalid value '3,3,1,1' for '--window <x0,y0,x1,y1>': need x0 < x1 and y0 < y1 (lower-left corner first)"),
),
case(
"--window not numbers",
&["convert", "{b}", "{dir}/o.svg", "--window", "a,b,c,d"],
2,
Empty,
Line("error: invalid value 'a,b,c,d' for '--window <x0,y0,x1,y1>': x0 must be a finite number, got `a`"),
),
case(
"--window NaN",
&["convert", "{b}", "{dir}/o.svg", "--window", "NaN,0,1,1"],
2,
Empty,
Line("error: invalid value 'NaN,0,1,1' for '--window <x0,y0,x1,y1>': x0 must be a finite number, got `NaN`"),
),
case(
"--window too large",
&["convert", "{b}", "{dir}/o.svg", "--window", "0,0,1e13,1"],
2,
Empty,
Line("error: invalid value '0,0,1e13,1' for '--window <x0,y0,x1,y1>': export window: coordinates must lie within ±1e12"),
),
case(
"run --window 3 numbers",
&["run", "--sample", "--window", "1,2,3", "--export", "{dir}/o.svg"],
2,
Empty,
Line("error: invalid value '1,2,3' for '--window <x0,y0,x1,y1>': expected four numbers x0,y0,x1,y1"),
),
case(
"run --window reversed",
&["run", "--sample", "--window", "3,3,1,1", "--export", "{dir}/o.svg"],
2,
Empty,
Line("error: invalid value '3,3,1,1' for '--window <x0,y0,x1,y1>': need x0 < x1 and y0 < y1 (lower-left corner first)"),
),
case(
"--cmd bad json",
&["run", "--sample", "--cmd", "line {bad json"],
2,
Empty,
Line("error: invalid value 'line {bad json' for '--cmd <id {json}>': key must be a string at line 1 column 2"),
),
case(
"--cmd bad json after a good step: nothing runs",
&["run", "--sample", "--cmd", "line {\"points\":[[0,0],[1,1]]}", "--cmd", "line {"],
2,
Empty,
Starts("error: invalid value 'line {' for '--cmd <id {json}>': "),
),
case(
"--cmd without an id",
&["run", "--sample", "--cmd", " {}"],
2,
Empty,
Line("error: invalid value ' {}' for '--cmd <id {json}>': expected a command id, then optionally its JSON parameters"),
),
case(
"--cmd empty",
&["run", "--sample", "--cmd="],
2,
Empty,
Line("error: invalid value '' for '--cmd <id {json}>': expected a command id, then optionally its JSON parameters"),
),
case("--cmd unknown id", &["run", "--sample", "--cmd", "nosuch"], 1, Empty, Line("error: unknown command `nosuch`")),
case(
"--cmd {last} with no earlier handle",
&["run", "--sample", "--cmd", "erase {\"handles\":[\"{last}\"]}"],
1,
Empty,
Line("error: --cmd erase: `{last}` needs an earlier --cmd in this run to have returned a handle"),
),
case("--script-file missing", &["run", "--sample", "--script-file", "missing.scr"], 1, Empty, Starts("error: missing.scr:")),
],
);
}
/// `mcp` serves on the process's real stdin and stdout, so the headless server runs through the
/// binary, with a closed stdin.
#[test]
fn mcp_headless_with_a_closed_stdin() {
let out = std::process::Command::new(env!("CARGO_BIN_EXE_cadcraft-cli"))
.arg("mcp")
.stdin(std::process::Stdio::null())
.output()
.expect("run cadcraft-cli");
assert_eq!(out.status.code(), Some(0));
assert!(out.stdout.is_empty() && out.stderr.is_empty());
}
/// A drawing to open whose name isn't valid Unicode reaches the handler as a path; the engine opens
/// files by text name, so it is refused there (exit 1), naming the file. Text that isn't Unicode is
/// a usage error.
#[cfg(unix)]
#[test]
fn non_unicode_arguments() {
use std::ffi::OsString;
use std::os::unix::ffi::OsStringExt;
let invoke_os = |args: Vec<OsString>| {
let (mut out, mut err) = (Vec::new(), Vec::new());
let code = cadcraft_cli::run(args, &mut out, &mut err);
assert!(out.is_empty());
(code, String::from_utf8_lossy(&err).into_owned())
};
let latin1 = || OsString::from_vec(b"caf\xe9.dxf".to_vec());
let (code, err) = invoke_os(vec![OsString::from("info"), latin1()]);
assert_eq!(code, 1);
assert_eq!(err.lines().next(), Some("error: caf\u{FFFD}.dxf: the file name is not valid Unicode"));
let (code, err) = invoke_os(vec![OsString::from("run"), OsString::from("--sample"), OsString::from("--cmd"), latin1()]);
assert_eq!(code, 2);
assert!(err.starts_with("error: invalid UTF-8 was detected"), "{err}");
}
/// An output name that isn't valid Unicode is written as given: only its extension picks the format.
#[cfg(unix)]
#[test]
fn non_unicode_output_names() {
use std::ffi::OsString;
use std::os::unix::ffi::OsStringExt;
let s = Scratch::new("nonunicode-out");
let latin1 = |ext: &str| {
let mut n = b"caf\xe9.".to_vec();
n.extend_from_slice(ext.as_bytes());
s.0.join(OsString::from_vec(n))
};
let run = |args: Vec<OsString>| {
let (mut out, mut err) = (Vec::new(), Vec::new());
let code = cadcraft_cli::run(args, &mut out, &mut err);
(code, String::from_utf8_lossy(&err).into_owned())
};
let b = s.0.join("b.dxf");
let cases: [(Vec<OsString>, std::path::PathBuf); 3] = [
(vec!["sample".into(), "bracket".into(), latin1("dxf").into()], latin1("dxf")),
(vec!["convert".into(), b.clone().into(), latin1("svg").into()], latin1("svg")),
(vec!["run".into(), "--sample".into(), "--save".into(), latin1("dwg").into()], latin1("dwg")),
];
for (args, path) in cases {
let (code, err) = run(args.clone());
assert_eq!(code, 0, "{args:?}: {err}");
assert!(path.exists(), "{path:?}");
assert!(std::fs::metadata(&path).expect("stat output").len() > 0, "{path:?}");
}
// An input with such a name is still refused.
let (code, err) = run(vec!["info".into(), latin1("dxf").into()]);
assert_eq!(code, 1);
assert!(err.contains("not valid Unicode"), "{err}");
}
/// An output that is an input file is refused before any work (exit 2, the input untouched) unless
/// `--in-place` allows it; the same file under another spelling counts, another existing file doesn't.
#[test]
fn output_that_replaces_an_input() {
let s = Scratch::new("inplace");
let dir = s.0.to_str().expect("utf-8 path").to_string();
let b = format!("{dir}/b.dxf");
let original = std::fs::read(&b).expect("read input");
std::fs::create_dir_all(format!("{dir}/sub")).expect("create sub");
let dotted = format!("{dir}/sub/../b.dxf");
#[allow(unused_mut)]
let mut spellings = vec![b.clone(), dotted];
#[cfg(unix)]
{
let link = format!("{dir}/link.dxf");
std::os::unix::fs::symlink(&b, &link).expect("symlink");
spellings.push(link);
}
for out in &spellings {
for args in [vec!["convert", &b, out], vec!["run", &b, "--save", out], vec!["run", &b, "--export", out]] {
let r = invoke(&args);
assert_eq!(r.code, 2, "{args:?}: {}", r.stderr);
assert!(r.stdout.is_empty(), "{args:?}");
assert!(r.stderr.starts_with(&format!("error: {out} is an input file")), "{args:?}: {}", r.stderr);
assert!(r.stderr.contains("--in-place"), "{args:?}: {}", r.stderr);
assert_eq!(std::fs::read(&b).expect("read input"), original, "{args:?}: input changed");
}
}
// Another existing file is replaced as before.
let other = format!("{dir}/other.dxf");
std::fs::write(&other, "x").expect("write other");
let r = invoke(&["convert", &b, &other]);
assert_eq!(r.code, 0, "{}", r.stderr);
assert_ne!(std::fs::read(&other).expect("read other"), b"x");
// --in-place allows it, for each spelling and flag: the input itself is rewritten, and a
// symlink stays a link to it.
let line = "line {\"points\":[[0,0],[1,1]]}";
let lines = |p: &str| std::fs::read_to_string(p).expect("read input").lines().filter(|l| l.trim_end() == "LINE").count();
let before = lines(&b);
for out in &spellings {
std::fs::write(&b, &original).expect("restore input");
let r = invoke(&["convert", &b, out, "--in-place"]);
assert_eq!(r.code, 0, "convert {out}: {}", r.stderr);
assert_eq!(lines(&b), before, "convert {out} keeps the drawing");
for flag in ["--save", "--export"] {
std::fs::write(&b, &original).expect("restore input");
let r = invoke(&["run", &b, "--cmd", line, "--in-place", flag, out]);
assert_eq!(r.code, 0, "{flag} {out}: {}", r.stderr);
assert_eq!(lines(&b), before + 1, "{flag} {out}: the input gains the line");
}
}
#[cfg(unix)]
{
let link = format!("{dir}/link.dxf");
assert!(std::fs::symlink_metadata(&link).expect("stat link").file_type().is_symlink(), "{link} is still a symlink");
}
// An output that doesn't exist yet is never an input.
let new = format!("{dir}/new.dxf");
let r = invoke(&["run", &b, "--save", &new]);
assert_eq!(r.code, 0, "{}", r.stderr);
assert!(std::path::Path::new(&new).is_file(), "{new} written");
}
/// JSON results are pretty-printed; `--compact` puts each on one line (RFC-0012 rule 1.3). `run`
/// prints one line per `--cmd` result either way.
#[test]
fn json_output_is_pretty_unless_compact() {
let s = Scratch::new("compact");
let b = format!("{}/b.dxf", s.0.to_str().expect("utf-8 path"));
for args in [&["info", b.as_str()][..], &["commands", "ellipse"]] {
let help = invoke(&[args[0], "--help"]);
assert!(
help.stdout.contains("--compact") && help.stdout.contains("One line of JSON instead of pretty-printed"),
"{} --help: {}",
args[0],
help.stdout
);
let pretty = invoke(args);
assert_eq!(pretty.code, 0, "{args:?}: {}", pretty.stderr);
assert!(pretty.stdout.lines().count() > 1, "{args:?} is pretty-printed: {}", pretty.stdout);
let compact = invoke(&[args, &["--compact"]].concat());
assert_eq!(compact.code, 0, "{args:?} --compact: {}", compact.stderr);
assert_eq!(compact.stdout.lines().count(), 1, "{args:?} --compact is one line: {}", compact.stdout);
let a: serde_json::Value = serde_json::from_str(&pretty.stdout).expect("pretty JSON");
let c: serde_json::Value = serde_json::from_str(&compact.stdout).expect("compact JSON");
assert_eq!(a, c, "{args:?}: same JSON either way");
}
let r = invoke(&["run", "--sample", "--cmd", "drawing.inspect", "--cmd", "drawing.inspect"]);
assert_eq!(r.code, 0, "{}", r.stderr);
assert_eq!(r.stdout.lines().count(), 2, "one line per --cmd result: {}", r.stdout);
assert_eq!(invoke(&["run", "--sample", "--compact"]).code, 2, "run takes no --compact");
}
@@ -0,0 +1,30 @@
//! The clap definition is consistent, and `examples/man-and-completions.rs` writes every shell's
//! completions and every man page under the names `packaging/linux/package.sh` installs.
// The example itself, so the test runs its code; its `main` is unused here.
#[allow(dead_code)]
#[path = "../examples/man-and-completions.rs"]
mod example;
#[test]
fn command_is_consistent() {
cadcraft_cli::command().debug_assert();
}
#[test]
fn the_example_writes_the_files_the_packages_install() {
let dir = std::path::Path::new(env!("CARGO_TARGET_TMPDIR")).join(format!("man-and-completions-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
example::generate(&dir).unwrap();
let mut written: Vec<String> = std::fs::read_dir(&dir).unwrap().map(|e| e.unwrap().file_name().into_string().unwrap()).collect();
written.sort();
let completions = ["cadcraft-cli.bash", "_cadcraft-cli", "cadcraft-cli.fish", "cadcraft-cli.elv", "_cadcraft-cli.ps1"];
let subcommands = ["info", "convert", "run", "commands", "mcp", "perf", "sample"];
let mut expected: Vec<String> = completions.map(String::from).into();
expected.push("cadcraft-cli.1".into());
expected.extend(subcommands.iter().map(|s| format!("cadcraft-cli-{s}.1")));
expected.sort();
assert_eq!(written, expected);
std::fs::remove_dir_all(&dir).unwrap();
}
+2
View File
@@ -21,6 +21,8 @@ eframe = { workspace = true, features = ["clipboard", "wgpu", "accesskit", "wayl
egui = { workspace = true }
serde_json = { workspace = true }
log = { workspace = true }
clap = { workspace = true }
thiserror = { workspace = true }
chrono = { workspace = true }
[build-dependencies]
+172
View File
@@ -0,0 +1,172 @@
//! The `CADCRAFT_*` variables of the desktop app, read once at startup into [`Env`] and passed on
//! from there; no library crate reads them. `--help` lists them from [`VARS`]. `--control`'s
//! fallback, `CADCRAFT_CONTROL_PORT`, is clap's (see `launch_args`).
use std::ffi::OsString;
use std::fmt::Write as _;
use std::path::PathBuf;
use cadcraft_ui_egui::switch::Switch;
const CONFIG_DIR: &str = "CADCRAFT_CONFIG_DIR";
const LOCALE: &str = "CADCRAFT_LOCALE";
const VSYNC: &str = "CADCRAFT_VSYNC";
const WAYLAND: &str = "CADCRAFT_WAYLAND";
const NO_NATIVE_MENU: &str = "CADCRAFT_NO_NATIVE_MENU";
const SYSTEM_CURSOR: &str = "CADCRAFT_SYSTEM_CURSOR";
const FONTALT: &str = "CADCRAFT_FONTALT";
const FONTFALLBACK: &str = "CADCRAFT_FONTFALLBACK";
/// Every variable [`Env`] reads, with its `--help` line.
pub(crate) const VARS: &[(&str, &str)] = &[
(CONFIG_DIR, "the settings folder (logs, autosave, workspace, plotters); empty means no settings folder"),
(LOCALE, "the interface language, instead of the system's"),
(VSYNC, "1 presents with vsync, 0 without it (default: without on Linux and BSD)"),
(WAYLAND, "1 keeps the native Wayland backend instead of XWayland; 0 or unset is off"),
(NO_NATIVE_MENU, "macOS: 1 keeps the menus inside the window; 0 or unset is off"),
(SYSTEM_CURSOR, "1 uses the system cursor instead of the drawn crosshair; 0 or unset is off"),
(FONTALT, "the font that replaces a missing one"),
(FONTFALLBACK, "the fonts tried, in order, for characters a font lacks"),
];
/// The process environment, read once at startup. A blank variable counts as unset, except
/// `CADCRAFT_CONFIG_DIR`.
#[derive(Debug, PartialEq)]
pub(crate) struct Env {
/// The settings folder (logs, autosave, workspace, plotters): `CADCRAFT_CONFIG_DIR`; else, when
/// that is unset, the platform's (`cadcraft_engine::settings_dir::platform`). `None`: no
/// folder, because the variable is empty or blank (the way to run without one) or the
/// platform has none.
pub(crate) config_dir: Option<PathBuf>,
/// The interface language, instead of the system's.
pub(crate) locale: Option<String>,
/// Present with vsync (default: off on Linux and BSD, on elsewhere).
pub(crate) vsync: Switch,
/// Keep the native Wayland backend instead of XWayland.
#[cfg_attr(not(all(unix, not(target_os = "macos"))), allow(dead_code))]
pub(crate) wayland: Switch,
/// macOS: keep the menus inside the window.
#[cfg_attr(not(target_os = "macos"), allow(dead_code))]
pub(crate) no_native_menu: Switch,
/// Use the system cursor instead of the drawn crosshair.
pub(crate) system_cursor: Switch,
/// FONTALT at startup.
pub(crate) font_alt: Option<String>,
/// FONTFALLBACK at startup.
pub(crate) font_fallback: Option<String>,
}
impl Env {
pub(crate) fn read() -> Env {
Env::from_vars(|k| std::env::var_os(k))
}
/// [`Env::read`] with `var` looking a variable up.
pub(crate) fn from_vars(var: impl Fn(&str) -> Option<OsString>) -> Env {
let text = |k: &str| var(k).and_then(|v| v.into_string().ok()).filter(|v| !v.trim().is_empty());
let switch = |k: &str| Switch::parse(k, var(k).map(|v| v.to_string_lossy().into_owned()).as_deref());
Env {
config_dir: match var(CONFIG_DIR) {
Some(dir) if dir.to_str().is_some_and(|d| d.trim().is_empty()) => None,
Some(dir) => Some(PathBuf::from(dir)),
None => cadcraft_engine::settings_dir::platform(&var),
},
locale: text(LOCALE),
vsync: switch(VSYNC),
wayland: switch(WAYLAND),
no_native_menu: switch(NO_NATIVE_MENU),
system_cursor: switch(SYSTEM_CURSOR),
font_alt: text(FONTALT),
font_fallback: text(FONTFALLBACK),
}
}
}
/// The `--help` section that lists [`VARS`].
pub(crate) fn help() -> String {
let width = VARS.iter().map(|(name, _)| name.len()).max().unwrap_or(0) + 3;
VARS.iter().fold(String::from("Environment:"), |mut help, (name, line)| {
let _ = write!(help, "\n {name:<width$}{line}");
help
})
}
#[cfg(test)]
mod tests {
use super::*;
use std::cell::RefCell;
fn env<'a>(vars: &'a [(&'a str, &'a str)]) -> impl Fn(&str) -> Option<OsString> + 'a {
move |k| vars.iter().find(|(n, _)| *n == k).map(|(_, v)| OsString::from(v))
}
#[test]
fn every_variable_read_is_in_the_help_and_every_listed_one_is_read() {
let asked = RefCell::new(Vec::new());
Env::from_vars(|k| {
asked.borrow_mut().push(k.to_owned());
None
});
let ours: Vec<String> = asked.into_inner().into_iter().filter(|k| k.starts_with("CADCRAFT_")).collect();
let help = help();
let unset = Env::from_vars(|_| None);
for k in &ours {
assert!(VARS.iter().any(|(name, _)| name == k), "{k} is read but not in VARS");
}
for (name, line) in VARS {
assert!(ours.iter().any(|k| k == name), "{name} is in VARS but not read");
assert_ne!(Env::from_vars(env(&[(name, "1")])), unset, "{name} sets no field");
assert!(help.lines().any(|l| l.trim_start().starts_with(name) && l.ends_with(line)), "{help}");
}
}
#[test]
fn values_are_read_and_blank_ones_are_unset() {
let vars = [
(CONFIG_DIR, "/private/cc"),
("HOME", "/home/u"),
("XDG_CONFIG_HOME", "/x"),
("APPDATA", "C:\\a"),
(LOCALE, "cs-CZ"),
(VSYNC, " On "),
(WAYLAND, "0"),
(NO_NATIVE_MENU, "yes"),
(SYSTEM_CURSOR, "maybe"),
(FONTALT, "Noto Sans"),
(FONTFALLBACK, "Vazirmatn, msjh.ttc"),
];
let read = Env::from_vars(env(&vars));
assert_eq!(
read,
Env {
config_dir: Some(PathBuf::from("/private/cc")),
locale: Some("cs-CZ".into()),
vsync: Switch::On,
wayland: Switch::Off,
no_native_menu: Switch::On,
system_cursor: Switch::Default,
font_alt: Some("Noto Sans".into()),
font_fallback: Some("Vazirmatn, msjh.ttc".into()),
}
);
let blank = vars.map(|(k, _)| (k, if k == FONTALT { " " } else { "" }));
let read = Env::from_vars(env(&blank));
assert_eq!(read.config_dir, None, "an empty variable means no directory, not the working directory");
assert_eq!((read.locale, read.font_alt, read.font_fallback), (None, None, None));
assert_eq!([read.vsync, read.wayland, read.no_native_menu, read.system_cursor], [Switch::Default; 4]);
}
#[test]
fn config_dir_unset_is_the_platform_folder_set_is_that_folder_blank_is_none() {
let platform = [("HOME", "/home/u"), ("XDG_CONFIG_HOME", "/x"), ("APPDATA", "C:\\a")];
let expected = cadcraft_engine::settings_dir::platform(env(&platform));
assert!(expected.is_some());
assert_eq!(Env::from_vars(env(&platform)).config_dir, expected);
let set = [platform.as_slice(), &[(CONFIG_DIR, "/private/cc")]].concat();
assert_eq!(Env::from_vars(env(&set)).config_dir, Some(PathBuf::from("/private/cc")));
for blank in ["", " "] {
let vars = [platform.as_slice(), &[(CONFIG_DIR, blank)]].concat();
assert_eq!(Env::from_vars(env(&vars)).config_dir, None, "{blank:?} means no settings folder, not the platform's");
}
}
}
+158
View File
@@ -0,0 +1,158 @@
//! The desktop app's command line, as clap types: `cadcraft --help` comes from these doc comments
//! and its Environment section from [`crate::env::VARS`], so the help and the parsers can't disagree. Anything they don't declare is a usage error naming
//! it (exit status 2), so a typo such as `--sampel` doesn't open the window and then fail to open
//! the flag as a file; so is a flag without its value, a repeated flag and a bad port, from the
//! flag or from `CADCRAFT_CONTROL_PORT`. A value never starts with `-`, and a file whose name
//! starts with `-` goes after `--`.
use std::ffi::OsString;
use std::path::PathBuf;
use cadcraft_mcp::args::{blank_env_is_unset, name_env_vars};
use clap::{Command, CommandFactory, FromArgMatches, Parser};
/// Opens CADCraft with the given files
#[derive(Parser)]
#[command(name = "cadcraft", version = cadcraft_engine::build_version(), after_help = crate::env::help())]
pub(crate) struct LaunchArgs {
/// Files to open. Put `--` before a name that starts with `-`
pub(crate) files: Vec<PathBuf>,
/// Start the localhost JSON-lines control server on this port
// allow_negative_numbers makes `--control -1` a bad value rather than a missing one.
#[arg(long, value_name = "PORT", env = "CADCRAFT_CONTROL_PORT", value_parser = control_port, allow_negative_numbers = true)]
pub(crate) control: Option<u16>,
/// Open with the sample drawing
#[arg(long)]
pub(crate) sample: bool,
}
/// The command line. An empty or blank variable counts as unset.
pub(crate) fn command() -> Command {
LaunchArgs::command().mut_args(|a| blank_env_is_unset(a, |k| std::env::var_os(k)))
}
/// Parse the launch arguments (without the binary name) with `cmd`, from [`command`]. Old macOS
/// passes a process serial number (`-psn_…`) when launched from Finder: it is dropped first, unless
/// it comes after `--`. A bad value from a variable is a usage error naming the variable.
pub(crate) fn parse(mut cmd: Command, args: impl IntoIterator<Item = OsString>) -> Result<LaunchArgs, clap::Error> {
let mut options = true;
let args: Vec<OsString> = args
.into_iter()
.filter(|a| {
options &= a != "--";
!(options && a.to_str().is_some_and(|s| s.starts_with("-psn_")))
})
.collect();
let argv = std::iter::once(OsString::from("cadcraft")).chain(args.iter().cloned());
let matches = cmd.try_get_matches_from_mut(argv).map_err(|e| name_env_vars(e, &cmd, &args))?;
LaunchArgs::from_arg_matches(&matches)
}
/// A control port, for clap's `value_parser`: `--control` and `CADCRAFT_CONTROL_PORT`, which may
/// carry spaces.
fn control_port(s: &str) -> Result<u16, NotAPort> {
s.trim().parse().map_err(|_| NotAPort)
}
/// A [`control_port`] value that isn't a port.
#[derive(Debug, PartialEq, Eq, thiserror::Error)]
#[error("expected a port, 0-65535")]
struct NotAPort;
#[cfg(test)]
mod tests {
use super::*;
use clap::error::ErrorKind;
/// Parse without the variables, so one exported where the tests run can't change them.
fn parse_args(args: &[&str]) -> Result<LaunchArgs, clap::Error> {
parse(command().mut_args(|a| a.env(None::<&str>)), args.iter().map(OsString::from))
}
fn usage_error(args: &[&str]) -> String {
let Err(e) = parse_args(args) else { panic!("{args:?} parsed") };
assert_eq!(e.exit_code(), 2, "{args:?}: {e}");
e.to_string()
}
#[test]
fn values_are_parsed() {
let parsed = parse_args(&["--control", " 50494 ", "--sample", "a.dxf", "b.dwg"]).unwrap();
assert_eq!((parsed.control, parsed.sample), (Some(50494), true));
assert_eq!(parsed.files, [PathBuf::from("a.dxf"), PathBuf::from("b.dwg")]);
let parsed = parse_args(&[]).unwrap();
assert_eq!((parsed.control, parsed.sample, parsed.files.len()), (None, false, 0));
}
#[test]
fn control_port_rejects_unparseable_values_naming_them() {
for bad in ["78787", "-1", "abc", "99999999999999999999"] {
assert!(usage_error(&["--control", bad]).contains(&format!("invalid value '{bad}' for '--control <PORT>'")), "{bad}");
}
assert!(usage_error(&["--control="]).contains("invalid value '' for '--control <PORT>'"));
}
#[test]
fn usage_errors_exit_2() {
assert!(usage_error(&["--sampel"]).contains("unexpected argument '--sampel'"));
assert!(usage_error(&["--control"]).contains("a value is required for '--control <PORT>'"));
// A following flag is never taken as the value.
assert!(usage_error(&["--control", "--sample"]).contains("a value is required for '--control <PORT>'"));
assert!(usage_error(&["--sample", "--sample"]).contains("cannot be used multiple times"));
assert!(usage_error(&["--control", "1", "--control", "2"]).contains("cannot be used multiple times"));
}
#[test]
fn version_stops_parsing() {
let e = parse_args(&["-V", "--control"]).err().unwrap();
assert_eq!((e.kind(), e.exit_code()), (ErrorKind::DisplayVersion, 0));
assert_eq!(e.to_string(), format!("{}\n", crate::version_string()));
let e = parse_args(&["--version", "--bogus"]).err().unwrap();
assert_eq!(e.kind(), ErrorKind::DisplayVersion);
}
#[test]
fn help_stops_parsing_and_double_dash_ends_options() {
let e = parse_args(&["-h", "--sampel", "--control"]).err().unwrap();
assert_eq!((e.kind(), e.exit_code()), (ErrorKind::DisplayHelp, 0));
let help = parse_args(&["--help"]).err().unwrap().to_string();
assert!(help.contains("--control <PORT>") && help.contains("CADCRAFT_CONFIG_DIR"), "{help}");
assert!(usage_error(&["--sampel", "--", "--help"]).contains("unexpected argument '--sampel'"));
let parsed = parse_args(&["a.dxf", "--", "--help", "-x"]).unwrap();
assert_eq!(parsed.files, ["a.dxf", "--help", "-x"].map(PathBuf::from));
}
#[test]
fn a_finder_process_serial_number_is_dropped() {
let parsed = parse_args(&["-psn_0_12345", "a.dxf"]).unwrap();
assert_eq!(parsed.files, [PathBuf::from("a.dxf")]);
let parsed = parse_args(&["--", "-psn_x.dxf"]).unwrap();
assert_eq!(parsed.files, [PathBuf::from("-psn_x.dxf")]);
}
/// A name that isn't valid Unicode is kept as given.
#[cfg(unix)]
#[test]
fn non_unicode_file_names_are_kept() {
use std::os::unix::ffi::OsStringExt as _;
let latin1 = OsString::from_vec(b"caf\xe9.dxf".to_vec());
let parsed = parse(command().mut_args(|a| a.env(None::<&str>)), [latin1.clone(), OsString::from("b.dxf")]).unwrap();
assert_eq!(parsed.files, [PathBuf::from(&latin1), PathBuf::from("b.dxf")]);
}
/// `--control` falls back to `PATH` here instead of `CADCRAFT_CONTROL_PORT`: `PATH` is set
/// wherever the tests run and is never a port, and tests can't set a variable (`set_var` is
/// unsafe).
#[test]
fn the_flag_wins_over_its_variable_and_a_bad_value_names_the_variable() {
let Some(path) = std::env::var_os("PATH").filter(|p| !p.is_empty()) else { return };
let path_fallback = || command().mut_args(|a| a.env(None::<&str>)).mut_arg("control", |a| a.env("PATH"));
let e = parse(path_fallback(), []).err().unwrap();
assert_eq!(e.exit_code(), 2);
let text = e.to_string();
assert!(text.contains(&format!("invalid value '{}' for 'PATH'", path.to_string_lossy())), "{text}");
assert!(!text.contains("--control <PORT>'"), "{text}");
assert_eq!(parse(path_fallback(), ["--control", "7"].map(OsString::from)).unwrap().control, Some(7));
}
}
+1 -1
View File
@@ -3,7 +3,7 @@
//! Without a logger every `log::warn!`/`log::error!`/`log::info!` in the workspace (a broken app
//! icon, the GPU canvas set-up, the control server) vanished. A launch from a desktop menu has no
//! terminal, so the file is what a bug report can attach: `<settings dir>/logs/cadcraft.log`
//! (`CADCRAFT_CONFIG_DIR`, or the platform settings directory; see `config_dir` in `main.rs`).
//! (`CADCRAFT_CONFIG_DIR`, or the platform settings directory; empty means none; see `env.rs`).
//! Each start moves the previous log to `cadcraft.1.log` (and that one to `.2`), so the log of a
//! run that crashed survives the next launch.
//!
+34 -137
View File
@@ -1,6 +1,6 @@
//! CADCraft desktop app.
//!
//! Usage: `cadcraft [--control <port>] [--sample] [files…]`
//! Usage: `cadcraft [--control <port>] [--sample] [files…]` (`cadcraft --help` lists the rest; see [`launch_args`])
//!
//! `--control <port>` (or `CADCRAFT_CONTROL_PORT`) starts a localhost JSON-lines control server:
//! `{"id":1,"method":"cmdline.input","params":{"text":"circle 0,0 5"}}` → `{"id":1,"ok":true,…}`.
@@ -10,14 +10,16 @@
//! present mode (`CADCRAFT_VSYNC=0` selects that elsewhere); see `cadcraft_ui_egui::gpu::surface_config`.
//!
//! `log` records go to standard error and `<settings dir>/logs/cadcraft.log` (`RUST_LOG` sets the
//! levels); see [`logging`] and [`config_dir`].
//! levels); see [`logging`]. The `CADCRAFT_*` variables are read once, at startup; see [`env`].
#![cfg_attr(all(target_os = "windows", not(debug_assertions)), windows_subsystem = "windows")]
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
mod control_server;
mod desktop_theme;
mod env;
#[cfg(any(target_os = "windows", test))]
mod graphics;
mod launch_args;
mod logging;
#[cfg(target_os = "macos")]
mod native_menu;
@@ -26,6 +28,7 @@ mod system_animations;
mod workspace;
use cadcraft_engine::Session;
use cadcraft_ui_egui::switch::Switch;
use cadcraft_ui_egui::{CadApp, Services, i18n};
struct App {
@@ -39,6 +42,9 @@ struct App {
workspace_error: Option<String>,
#[cfg(target_os = "macos")]
native_menu: Option<native_menu::NativeMenu>,
/// `CADCRAFT_NO_NATIVE_MENU`: the menus stay inside the window.
#[cfg(target_os = "macos")]
menus_in_window: bool,
/// The `movable` flag last set on the main window.
#[cfg(target_os = "macos")]
movable: Option<bool>,
@@ -88,7 +94,7 @@ impl eframe::App for App {
if ctx.current_pass_index() == 0 {
#[cfg(target_os = "macos")]
{
if self.native_menu.is_none() && std::env::var_os("CADCRAFT_NO_NATIVE_MENU").is_none() {
if self.native_menu.is_none() && !self.menus_in_window {
self.native_menu = Some(native_menu::NativeMenu::install(&mut self.cad, ctx));
}
if let Some(m) = &mut self.native_menu {
@@ -188,30 +194,6 @@ fn filters_for_save(name: &str) -> [(&'static str, &'static str); 6] {
filters
}
/// The per-user settings directory (it holds `logs/` and `autosave/`): `CADCRAFT_CONFIG_DIR` if set, else
/// `$XDG_CONFIG_HOME/cadcraft` or `~/.config/cadcraft` on Linux and the BSDs,
/// `~/Library/Application Support/CADCraft` on macOS, `%APPDATA%\CADCraft` on Windows.
fn config_dir() -> Option<std::path::PathBuf> {
config_dir_from(|k| std::env::var_os(k))
}
/// [`config_dir`] with the environment passed in (`var` looks a variable up). An empty variable
/// counts as unset, so a blank value never means the working directory.
fn config_dir_from(var: impl Fn(&str) -> Option<std::ffi::OsString>) -> Option<std::path::PathBuf> {
let set = |k: &str| var(k).filter(|v| !v.is_empty()).map(std::path::PathBuf::from);
if let Some(dir) = set("CADCRAFT_CONFIG_DIR") {
return Some(dir);
}
if cfg!(target_os = "macos") {
set("HOME").map(|h| h.join("Library/Application Support/CADCraft"))
} else if cfg!(windows) {
set("APPDATA").map(|a| a.join("CADCraft"))
} else {
// The XDG spec ignores a relative XDG_CONFIG_HOME.
set("XDG_CONFIG_HOME").filter(|p| p.is_absolute()).or_else(|| set("HOME").map(|h| h.join(".config"))).map(|c| c.join("cadcraft"))
}
}
const APP_ID: &str = "ai.storyteller.cadcraft";
/// Stencil bits of the window's render pass (see `NativeOptions::stencil_buffer`).
@@ -227,32 +209,7 @@ fn app_icon() -> Option<egui::IconData> {
}
fn version_string() -> String {
let sha = option_env!("CADCRAFT_BUILD_SHA").unwrap_or("dev");
format!("cadcraft {} ({sha})", env!("CARGO_PKG_VERSION"))
}
/// The control port from `--control <port>` or `CADCRAFT_CONTROL_PORT` (`source`); a value that is
/// not a port is logged and ignored instead of silently starting no control channel.
fn control_port_from(source: &str, value: Option<String>) -> Option<u16> {
let value = value?;
let port = value.trim().parse().ok();
if port.is_none() {
log::warn!("{source}: {value:?} is not a port number; the control channel is off");
}
port
}
/// `--control` followed by `value`: a bare `--control` (last argument) keeps the port already
/// read from `CADCRAFT_CONTROL_PORT` (`current`) instead of turning the control channel off.
fn control_flag(current: Option<u16>, value: Option<String>) -> Option<u16> {
if value.is_some() {
return control_port_from("--control", value);
}
match current {
Some(port) => log::warn!("--control: no port given; using CADCRAFT_CONTROL_PORT ({port})"),
None => log::warn!("--control: no port given; the control channel is off"),
}
current
format!("cadcraft {}", cadcraft_engine::build_version())
}
/// Parse CLI options (`--control`, `--sample`, files, `--version`), install logging and I/O hooks, build the services and app, and run eframe.
@@ -268,37 +225,33 @@ fn main() -> eframe::Result {
}
return Ok(());
}
// lossy, so a value that is not Unicode is reported like any other bad port instead of ignored
let mut control_port =
control_port_from("CADCRAFT_CONTROL_PORT", std::env::var_os("CADCRAFT_CONTROL_PORT").map(|p| p.to_string_lossy().into_owned()));
let mut files = Vec::new();
let mut sample = false;
let mut args = std::env::args().skip(1);
while let Some(a) = args.next() {
match a.as_str() {
"--control" => control_port = control_flag(control_port, args.next()),
"--sample" => sample = true,
"--version" | "-V" => {
println!("{}", version_string());
return Ok(());
}
_ => files.push(a),
}
}
// `--help` and `--version` print to standard output and exit 0. A usage error (an unknown or
// repeated flag, a missing or bad value, a bad CADCRAFT_CONTROL_PORT) names the argument on
// standard error and exits 2 before the window opens.
let launch = launch_args::parse(launch_args::command(), std::env::args_os().skip(1)).unwrap_or_else(|e| e.exit());
let vars = env::Env::read();
let (control_port, sample, files) = (launch.control, launch.sample, launch.files);
// The log file lives under the settings directory; opened after the arguments, so `--version`
// leaves no file behind. Records logged until now are written to it first.
if let Some(logger) = logger {
match config_dir().map(|d| logger.attach_dir(&d.join(logging::LOG_DIR))) {
match vars.config_dir.as_ref().map(|d| logger.attach_dir(&d.join(logging::LOG_DIR))) {
Some(Ok(path)) => log::info!("{} ({} {}), log file {}", version_string(), std::env::consts::OS, std::env::consts::ARCH, path.display()),
Some(Err(e)) => log::warn!("no log file: {e}"),
None => {
logger.stderr_only();
log::warn!("no log file: no settings directory (set CADCRAFT_CONFIG_DIR)");
log::warn!("no log file: no settings directory (an empty CADCRAFT_CONFIG_DIR turns it off)");
}
}
}
install_io();
let surface = cadcraft_ui_egui::gpu::surface_config(std::env::var("CADCRAFT_VSYNC").ok().as_deref(), cfg!(all(unix, not(target_os = "macos"))));
cadcraft_engine::settings_dir::set(vars.config_dir.clone());
if let Some(name) = &vars.font_alt {
cadcraft_engine::fonts::ttf::set_font_alt(name);
}
if let Some(list) = &vars.font_fallback {
cadcraft_engine::fonts::ttf::set_fallback_fonts(list);
}
let surface = cadcraft_ui_egui::gpu::surface_config(vars.vsync, cfg!(all(unix, not(target_os = "macos"))));
let mut options = eframe::NativeOptions {
// The crosshair is drawn by the app: present without a queue on Linux/BSD, where X11
// swapchains hold two frames back under vsync (`CADCRAFT_VSYNC=1` restores vsync).
@@ -341,7 +294,7 @@ fn main() -> eframe::Result {
// manager showed a "no" cursor. Run through XWayland when it's there; CADCRAFT_WAYLAND=1
// keeps the native Wayland backend.
#[cfg(all(unix, not(target_os = "macos")))]
if std::env::var_os("DISPLAY").is_some() && std::env::var_os("CADCRAFT_WAYLAND").is_none() {
if std::env::var_os("DISPLAY").is_some() && vars.wayland != Switch::On {
options.event_loop_builder = Some(Box::new(|b| {
use winit::platform::x11::EventLoopBuilderExtX11;
b.with_x11();
@@ -352,15 +305,16 @@ fn main() -> eframe::Result {
options,
Box::new(move |cc| {
let mut app = CadApp::new(Session::empty(), services());
let (workspace, restored, workspace_error) = workspace::Workspace::load();
let (workspace, restored, workspace_error) = workspace::Workspace::load(vars.config_dir.as_deref());
if let Some(ui) = restored {
app.ui = ui;
}
app.set_system_cursor_default(vars.system_cursor == Switch::On);
if let Some(error) = &workspace_error {
eprintln!("CADCraft workspace: {error}");
app.set_status(error);
}
app.system_languages = std::env::var("CADCRAFT_LOCALE").map(|s| vec![s]).unwrap_or_else(|_| sys_locale::get_locales().collect());
app.system_languages = vars.locale.map(|s| vec![s]).unwrap_or_else(|| sys_locale::get_locales().collect());
// The user profile (Options): drafting settings, selection sizes, drawing-area colours.
if let Some(profile) = cc.storage.and_then(|s| s.get_string(cadcraft_ui_egui::options::PROFILE_KEY)) {
app.load_profile(&profile);
@@ -372,7 +326,7 @@ fn main() -> eframe::Result {
cadcraft_ui_egui::autosave::load_prefs(&prefs);
}
// Autosave files (SAVEFILEPATH) default to `<settings dir>/autosave`.
if let Some(dir) = config_dir() {
if let Some(dir) = &vars.config_dir {
app.enable_autosave(&dir.join("autosave"));
app.enable_update_check();
// Startup LISP (acad.lsp, acaddoc.lsp) is read from `<settings>/support`; the
@@ -419,6 +373,8 @@ fn main() -> eframe::Result {
#[cfg(target_os = "macos")]
native_menu: None,
#[cfg(target_os = "macos")]
menus_in_window: vars.no_native_menu == Switch::On,
#[cfg(target_os = "macos")]
movable: None,
}))
}),
@@ -427,13 +383,7 @@ fn main() -> eframe::Result {
#[cfg(test)]
mod tests {
use super::{config_dir_from, control_flag, control_port_from, filters_for_save, follow_desktop};
use std::ffi::OsString;
use std::path::PathBuf;
fn env<'a>(vars: &'a [(&'a str, &'a str)]) -> impl Fn(&str) -> Option<OsString> + 'a {
move |k| vars.iter().find(|(n, _)| *n == k).map(|(_, v)| OsString::from(v))
}
use super::{filters_for_save, follow_desktop};
#[test]
fn save_dialog_offers_dwg_with_the_drawing_format_first() {
@@ -451,59 +401,6 @@ mod tests {
}
}
#[test]
fn control_port_values_that_are_not_ports_are_ignored() {
assert_eq!(control_port_from("--control", Some("7979".into())), Some(7979));
assert_eq!(control_port_from("--control", Some(" 7979 ".into())), Some(7979));
assert_eq!(control_port_from("--control", None), None);
for bad in ["", "abc", "-1", "65536", "99999999999999999999", "\u{0}"] {
assert_eq!(control_port_from("--control", Some(bad.into())), None, "{bad:?}");
}
}
#[test]
fn control_without_a_port_keeps_the_environment_port() {
// `CADCRAFT_CONTROL_PORT=47321 cadcraft --control` (#844)
assert_eq!(control_flag(Some(47321), None), Some(47321));
assert_eq!(control_flag(None, None), None);
// A port given on the command line still wins over the variable.
assert_eq!(control_flag(Some(47321), Some("7979".into())), Some(7979));
assert_eq!(control_flag(Some(47321), Some("abc".into())), None);
}
#[test]
fn the_override_variable_wins_and_empty_values_are_unset() {
let vars = [("CADCRAFT_CONFIG_DIR", "/tmp/cc"), ("HOME", "/home/u"), ("XDG_CONFIG_HOME", "/x"), ("APPDATA", "C:\\a")];
assert_eq!(config_dir_from(env(&vars)), Some(PathBuf::from("/tmp/cc")));
let empty = [("CADCRAFT_CONFIG_DIR", ""), ("HOME", ""), ("XDG_CONFIG_HOME", ""), ("APPDATA", "")];
assert_eq!(config_dir_from(env(&empty)), None, "no usable variable means no directory, not the working directory");
assert_eq!(config_dir_from(env(&[])), None);
}
#[cfg(all(unix, not(target_os = "macos")))]
#[test]
fn linux_and_bsd_follow_xdg_config_home() {
assert_eq!(config_dir_from(env(&[("XDG_CONFIG_HOME", "/x"), ("HOME", "/home/u")])), Some(PathBuf::from("/x/cadcraft")));
assert_eq!(config_dir_from(env(&[("HOME", "/home/u")])), Some(PathBuf::from("/home/u/.config/cadcraft")));
// The XDG spec says a relative XDG_CONFIG_HOME is ignored.
assert_eq!(config_dir_from(env(&[("XDG_CONFIG_HOME", "rel"), ("HOME", "/home/u")])), Some(PathBuf::from("/home/u/.config/cadcraft")));
}
#[cfg(target_os = "macos")]
#[test]
fn macos_uses_application_support() {
assert_eq!(config_dir_from(env(&[("HOME", "/Users/u")])), Some(PathBuf::from("/Users/u/Library/Application Support/CADCraft")));
}
#[cfg(windows)]
#[test]
fn windows_uses_appdata() {
assert_eq!(
config_dir_from(env(&[("APPDATA", "C:\\Users\\u\\AppData\\Roaming")])),
Some(PathBuf::from("C:\\Users\\u\\AppData\\Roaming").join("CADCraft"))
);
}
/// View ▸ Theme ▸ System on Linux: winit reports no theme, so the desktop's answer stands in;
/// without one (or where winit answers and the desktop doesn't) the input is left alone.
#[test]
+15 -28
View File
@@ -1,6 +1,5 @@
//! Native workspace preferences. Drawing data and transient dialogs never enter this file.
use std::ffi::OsString;
use std::fs::{self, File, OpenOptions};
use std::io::{Read, Write};
use std::path::{Path, PathBuf};
@@ -24,18 +23,6 @@ pub struct Workspace {
last_write: Option<Instant>,
}
fn config_dir_from(platform: &str, get: impl Fn(&str) -> Option<OsString>) -> Option<PathBuf> {
if let Some(root) = get("CADCRAFT_CONFIG_DIR") {
return (!root.is_empty()).then(|| PathBuf::from(root));
}
let nonempty = |key| get(key).filter(|value| !value.is_empty()).map(PathBuf::from);
match platform {
"macos" => nonempty("HOME").map(|home| home.join("Library/Application Support/CADCraft")),
"windows" => nonempty("APPDATA").map(|root| root.join("CADCraft")),
_ => nonempty("XDG_CONFIG_HOME").map(|root| root.join("cadcraft")).or_else(|| nonempty("HOME").map(|home| home.join(".config/cadcraft"))),
}
}
fn snapshot(ui: &UiState) -> Result<Value, String> {
cadcraft_ui_egui::docking::validate(&ui.docking)?;
if !matches!(ui.toolset_tab.as_str(), "Drafting" | "Modeling") {
@@ -139,8 +126,9 @@ fn write(path: &Path, workspace: &Value) -> Result<(), String> {
}
impl Workspace {
pub fn load() -> (Self, Option<UiState>, Option<String>) {
Self::at(config_dir_from(std::env::consts::OS, |key| std::env::var_os(key)).map(|root| root.join("workspace.json")))
/// The workspace file in the settings directory `config_dir`; without one nothing is kept.
pub fn load(config_dir: Option<&Path>) -> (Self, Option<UiState>, Option<String>) {
Self::at(config_dir.map(|root| root.join("workspace.json")))
}
fn at(path: Option<PathBuf>) -> (Self, Option<UiState>, Option<String>) {
@@ -195,6 +183,7 @@ impl Workspace {
#[cfg(test)]
mod tests {
use super::*;
use std::ffi::OsString;
fn temp_dir() -> PathBuf {
let sequence = TEMP_SEQUENCE.fetch_add(1, Ordering::Relaxed);
@@ -205,20 +194,18 @@ mod tests {
#[test]
fn profile_override_isolated_or_explicitly_disabled() {
let get = |key: &str| match key {
"CADCRAFT_CONFIG_DIR" => Some(OsString::from("/private/test-state")),
"HOME" | "APPDATA" | "XDG_CONFIG_HOME" => Some(OsString::from("/unrelated-user-profile")),
_ => None,
let vars = |config: Option<&'static str>| {
move |key: &str| match key {
"CADCRAFT_CONFIG_DIR" => config.map(OsString::from),
"HOME" | "APPDATA" | "XDG_CONFIG_HOME" => Some(OsString::from("/unrelated-user-profile")),
_ => None,
}
};
for platform in ["macos", "windows", "linux", "freebsd"] {
assert_eq!(config_dir_from(platform, get), Some(PathBuf::from("/private/test-state")));
assert_eq!(config_dir_from(platform, |key| if key == "CADCRAFT_CONFIG_DIR" { Some(OsString::new()) } else { get(key) }), None);
}
assert_eq!(
config_dir_from("linux", |key| (key == "XDG_CONFIG_HOME").then(|| OsString::from("/config"))),
Some(PathBuf::from("/config/cadcraft"))
);
assert_eq!(config_dir_from("macos", |_| None), None);
let dir = |config| crate::env::Env::from_vars(vars(config)).config_dir;
assert_eq!(dir(Some("/private/test-state")), Some(PathBuf::from("/private/test-state")));
assert_eq!(dir(Some("")), None);
let (_, restored, error) = Workspace::load(dir(Some("")).as_deref());
assert!(restored.is_none() && error.is_none(), "no settings folder, no workspace file");
}
#[test]
+100
View File
@@ -0,0 +1,100 @@
use std::path::Path;
/// A file format, chosen by the file name's extension (ASCII case-insensitive).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Format {
Dxf,
Dwg,
/// A drawing template: DWG content.
Dwt,
Svg,
/// Gzip-compressed SVG.
Svgz,
Png,
Pdf,
}
impl Format {
/// The formats a drawing can be read from by name. DXF and DWG are also recognised by content.
pub const READ: &'static [Format] = &[Format::Dxf, Format::Dwg, Format::Svg, Format::Svgz];
/// The formats a drawing can be written to.
pub const WRITE: &'static [Format] = &[Format::Dxf, Format::Dwg, Format::Dwt, Format::Svg, Format::Png, Format::Pdf];
/// The format `path`'s extension names. A name without an extension is DXF; an unknown
/// extension is `None`.
pub fn from_path(p: impl AsRef<Path>) -> Option<Format> {
let ext = p.as_ref().extension().map(|e| e.to_string_lossy().to_ascii_lowercase()).unwrap_or_default();
Some(match ext.as_str() {
"dxf" | "" => Format::Dxf,
"dwg" => Format::Dwg,
"dwt" => Format::Dwt,
"svg" => Format::Svg,
"svgz" => Format::Svgz,
"png" => Format::Png,
"pdf" => Format::Pdf,
_ => return None,
})
}
/// The extension, lower case and without the dot.
pub fn extension(self) -> &'static str {
match self {
Format::Dxf => "dxf",
Format::Dwg => "dwg",
Format::Dwt => "dwt",
Format::Svg => "svg",
Format::Svgz => "svgz",
Format::Png => "png",
Format::Pdf => "pdf",
}
}
/// Written as an image (model space fitted to a frame), so framing applies. SVGZ is read only.
pub fn is_image(self) -> bool {
matches!(self, Format::Svg | Format::Png | Format::Pdf)
}
/// A drawing file (DXF, DWG, template) rather than an image.
pub fn is_drawing(self) -> bool {
matches!(self, Format::Dxf | Format::Dwg | Format::Dwt)
}
/// Written as DWG, which drops the object types the DWG writer doesn't know.
pub fn drops_unknown(self) -> bool {
matches!(self, Format::Dwg | Format::Dwt)
}
/// `formats` as "dxf, dwg, svg": the list help text shows.
pub fn list(formats: &[Format]) -> String {
formats.iter().map(|f| f.extension()).collect::<Vec<_>>().join(", ")
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn from_path_by_extension() {
for f in [Format::Dxf, Format::Dwg, Format::Dwt, Format::Svg, Format::Svgz, Format::Png, Format::Pdf] {
assert_eq!(Format::from_path(format!("a/b.{}", f.extension())), Some(f));
assert_eq!(Format::from_path(format!("B.{}", f.extension().to_ascii_uppercase())), Some(f));
}
assert_eq!(Format::from_path("Drawing1"), Some(Format::Dxf), "no extension is DXF");
assert_eq!(Format::from_path("dir.dwg/Drawing1"), Some(Format::Dxf));
assert_eq!(Format::from_path("a."), Some(Format::Dxf));
assert_eq!(Format::from_path("a.txt"), None);
assert_eq!(Format::from_path("a.dxf.bak"), None);
assert_eq!(Format::from_path(std::path::Path::new("x.PnG")), Some(Format::Png));
}
#[test]
fn classes() {
assert!(Format::READ.contains(&Format::Svgz) && !Format::WRITE.contains(&Format::Svgz));
assert!(Format::WRITE.contains(&Format::Dwt) && !Format::READ.contains(&Format::Dwt));
assert!(Format::WRITE.iter().filter(|f| f.is_image()).count() == 3 && !Format::Svgz.is_image());
assert!(Format::Dwt.drops_unknown() && Format::Dwg.drops_unknown() && !Format::Dxf.drops_unknown());
assert!(Format::Dwt.is_drawing() && !Format::Pdf.is_drawing());
assert_eq!(Format::list(Format::READ), "dxf, dwg, svg, svgz");
}
}
+2
View File
@@ -10,6 +10,7 @@ mod array;
mod constraint;
mod entity;
mod extents;
mod format;
mod gdt;
mod header;
pub mod library;
@@ -27,6 +28,7 @@ pub use cadcraft_geom as geom;
pub use constraint::*;
pub use entity::*;
pub use extents::{MAX_BLOCK_DEPTH, entity_bounds};
pub use format::Format;
pub use gdt::*;
pub use header::{HVal, Header};
pub use plotstyle::*;
+16 -15
View File
@@ -7,7 +7,7 @@ mod template;
use std::sync::OnceLock;
use cadcraft_doc::Drawing;
use cadcraft_doc::{Drawing, Format};
pub use cadcraft_dxf::Version;
use serde_json::{Value, json};
@@ -136,8 +136,7 @@ fn save_options(cmd: &str, p: &Value) -> Result<SaveAs> {
/// Whether `path` names a DXF file (or has no extension, which saves as DXF).
fn is_dxf(path: &str) -> bool {
let ext = std::path::Path::new(path).extension().map(|e| e.to_string_lossy().to_ascii_lowercase()).unwrap_or_default();
matches!(ext.as_str(), "dxf" | "")
Format::from_path(path) == Some(Format::Dxf)
}
/// The drawing written to `path` with `opts`: through [`IoHooks::write`] when no option is set,
@@ -273,17 +272,21 @@ pub struct ReadFile {
}
/// Read and decode `path` (the slow half of `OPEN {path}`). Needs no session; runs anywhere.
pub fn read_file(path: &str) -> std::result::Result<ReadFile, String> {
pub fn read_file(path: &std::path::Path) -> std::result::Result<ReadFile, String> {
#[cfg(not(target_arch = "wasm32"))]
{
let r = std::panic::catch_unwind(|| {
let bytes =
crate::capped_read::read_capped(std::path::Path::new(path), MAX_DRAWING_BYTES).map_err(|e| bad("open", format!("{path}: {e}")))?;
read_bytes(&bytes, path, Some(path.to_string()))
let shown = path.display();
// The session keeps paths as text; a name that isn't Unicode could never be saved back to.
let Some(text_path) = path.to_str() else {
return Err(bad("open", format!("{shown}: the file name is not valid Unicode, so CADCraft can't save back to it")));
};
let bytes = crate::capped_read::read_capped(path, MAX_DRAWING_BYTES).map_err(|e| bad("open", format!("{shown}: {e}")))?;
read_bytes(&bytes, text_path, Some(text_path.to_string()))
});
match r {
Ok(r) => r.map_err(|e| e.to_string()),
Err(_) => Err(bad("open", format!("{path}: the file could not be read")).to_string()),
Err(_) => Err(bad("open", format!("{}: the file could not be read", path.display())).to_string()),
}
}
#[cfg(target_arch = "wasm32")]
@@ -515,7 +518,7 @@ fn run_bytes(s: &mut Session, p: &Value) -> Result<Value> {
let lost = not_saved_as(s.doc()?, version);
let bytes = write_bytes(s, "document.bytes", &format!("drawing.{fmt}"), &opts)?;
let mut r = json!({ "data": base64_encode(&bytes), "bytes": bytes.len() });
if drops_unknown(&format!("drawing.{fmt}")) {
if drops_unknown(format!("drawing.{fmt}")) {
report_not_saved(s, &mut r, &lost);
}
Ok(r)
@@ -563,15 +566,13 @@ pub fn not_saved_message(lost: &std::collections::BTreeMap<String, usize>) -> Op
/// Whether saving to `path` leaves out the entities [`not_saved`] counts: DWG does (the DWG
/// bridge drops types it doesn't know); DXF writes them back as read.
pub fn drops_unknown(path: &str) -> bool {
// Templates (.dwt) are written as DWG too.
std::path::Path::new(path).extension().is_some_and(|e| e.eq_ignore_ascii_case("dwg") || e.eq_ignore_ascii_case("dwt"))
pub fn drops_unknown(path: impl AsRef<std::path::Path>) -> bool {
Format::from_path(path).is_some_and(Format::drops_unknown)
}
/// Whether `path` is saved as a drawing (DXF, DWG) rather than exported as an image.
fn is_drawing_file(path: &str) -> bool {
let ext = std::path::Path::new(path).extension().map(|e| e.to_string_lossy().to_ascii_lowercase()).unwrap_or_default();
matches!(ext.as_str(), "dxf" | "dwg" | "dwt" | "")
fn is_drawing_file(path: impl AsRef<std::path::Path>) -> bool {
Format::from_path(path).is_some_and(Format::is_drawing)
}
/// Say on the command line what the file couldn't keep, and list it in the result's `notSaved`.
+4 -14
View File
@@ -61,23 +61,13 @@ impl PlotterStore {
}
}
/// The `plotters` folder of the CADCraft settings directory (`CADCRAFT_CONFIG_DIR`, else
/// the platform's settings directory).
/// The `plotters` folder of the CADCraft settings directory ([`crate::settings_dir::current`]).
#[cfg(not(target_arch = "wasm32"))]
pub fn settings_folder() -> PlotterStore {
fn dir() -> std::result::Result<std::path::PathBuf, String> {
use std::path::PathBuf;
let get = |k: &str| std::env::var_os(k).filter(|v| !v.is_empty()).map(PathBuf::from);
let root = match std::env::var_os("CADCRAFT_CONFIG_DIR") {
Some(r) if !r.is_empty() => Some(PathBuf::from(r)),
Some(_) => None,
None => match std::env::consts::OS {
"macos" => get("HOME").map(|h| h.join("Library/Application Support/CADCraft")),
"windows" => get("APPDATA").map(|r| r.join("CADCraft")),
_ => get("XDG_CONFIG_HOME").map(|r| r.join("cadcraft")).or_else(|| get("HOME").map(|h| h.join(".config/cadcraft"))),
},
};
root.map(|r| r.join("plotters")).ok_or_else(|| "there is no settings folder for plotter configurations".to_string())
crate::settings_dir::current()
.map(|r| r.join("plotters"))
.ok_or_else(|| "there is no settings folder for plotter configurations".to_string())
}
/// A plain file name of ours (no separators, no parent references).
fn file(n: &str) -> std::result::Result<std::path::PathBuf, String> {
+10
View File
@@ -29,6 +29,7 @@ pub mod prompt;
mod recent;
pub mod sample;
pub mod select;
pub mod settings_dir;
pub mod snap;
pub mod spatial;
pub mod sysvars;
@@ -43,6 +44,7 @@ use serde::{Deserialize, Serialize};
use serde_json::Value;
pub use cadcraft_doc as doc;
pub use cadcraft_fonts as fonts;
pub use cadcraft_geom as geom;
pub use cadcraft_render as render;
pub use cmd::hatch::{HatchPicks, PatternChoice, PickMode, pattern_choices};
@@ -64,6 +66,14 @@ pub use running::{PendingWindow, Running};
pub use settings::Settings;
pub use view::{ModelTile, ModelTiles, View};
/// `<version> (<commit>)`, what `--version` prints after the program name in the app and the CLI.
/// The commit comes from `CADCRAFT_BUILD_SHA` at build time, `dev` without it.
pub fn build_version() -> &'static str {
static VERSION: std::sync::LazyLock<String> =
std::sync::LazyLock::new(|| format!("{} ({})", env!("CARGO_PKG_VERSION"), option_env!("CADCRAFT_BUILD_SHA").unwrap_or("dev")));
&VERSION
}
/// The editor session: open drawings, settings, the running command and the command log.
pub struct Session {
pub docs: Vec<DocState>,
+3 -3
View File
@@ -73,17 +73,17 @@ pub(super) fn findfile(a: &[Value]) -> R {
/// Read a regular text file up to 64 MiB, replacing invalid UTF-8 and returning `None` on read failure.
#[cfg(not(target_arch = "wasm32"))]
pub fn read_text_file(path: &str) -> Option<String> {
pub fn read_text_file(path: impl AsRef<std::path::Path>) -> Option<String> {
// Read through a byte-limited, regular-file-only reader so a path naming an endless device
// cannot exhaust memory before the 64 MiB cap is enforced (CWE-400).
const MAX: usize = 64 * 1024 * 1024;
let bytes = crate::capped_read::read_capped(std::path::Path::new(path), MAX).ok()?;
let bytes = crate::capped_read::read_capped(path.as_ref(), MAX).ok()?;
Some(String::from_utf8_lossy(&bytes).into_owned())
}
/// Return `None` on the web, where native filesystem paths are unavailable.
#[cfg(target_arch = "wasm32")]
pub fn read_text_file(_path: &str) -> Option<String> {
pub fn read_text_file(_path: impl AsRef<std::path::Path>) -> Option<String> {
None
}
+1 -1
View File
@@ -1097,5 +1097,5 @@ pub fn load_source(s: &Session, name: &str) -> Option<String> {
// As given (a path, or relative to the working folder), then in the support folder.
let support =
s.lisp_support_dir().map(|d| candidates.iter().map(|c| d.join(c).to_string_lossy().into_owned()).collect::<Vec<_>>()).unwrap_or_default();
candidates.iter().chain(&support).find_map(|c| super::builtins::read_text_file(c))
candidates.iter().chain(&support).find_map(super::builtins::read_text_file)
}
+1 -1
View File
@@ -42,7 +42,7 @@ impl Session {
if once && self.lisp.acad_loaded && !per_drawing {
continue;
}
let Some(text) = super::builtins::read_text_file(&dir.join(name).to_string_lossy()) else { continue };
let Some(text) = super::builtins::read_text_file(dir.join(name)) else { continue };
if once {
self.lisp.acad_loaded = true;
}
+82
View File
@@ -0,0 +1,82 @@
//! The per-user CADCraft settings directory (logs, autosave, plotter configurations). The host
//! chooses it ([`set`], possibly to none); without a choice it is the platform's ([`platform`]).
use std::ffi::OsString;
use std::path::PathBuf;
use std::sync::Mutex;
/// `None`: no choice yet; `Some(None)`: the host chose to have no settings directory.
static CHOSEN: Mutex<Option<Option<PathBuf>>> = Mutex::new(None);
/// The platform's settings directory, with `var` looking up the OS variables: `$XDG_CONFIG_HOME/cadcraft`
/// or `~/.config/cadcraft` on Linux and the BSDs, `~/Library/Application Support/CADCraft` on
/// macOS, `%APPDATA%\CADCraft` on Windows. An empty variable counts as unset, so a blank value
/// never means the working directory.
pub fn platform(var: impl Fn(&str) -> Option<OsString>) -> Option<PathBuf> {
let set = |k: &str| var(k).filter(|v| !v.is_empty()).map(PathBuf::from);
if cfg!(target_os = "macos") {
set("HOME").map(|h| h.join("Library/Application Support/CADCraft"))
} else if cfg!(windows) {
set("APPDATA").map(|a| a.join("CADCraft"))
} else {
// The XDG spec ignores a relative XDG_CONFIG_HOME.
set("XDG_CONFIG_HOME").filter(|p| p.is_absolute()).or_else(|| set("HOME").map(|h| h.join(".config"))).map(|c| c.join("cadcraft"))
}
}
/// Use `dir` as the settings directory; `None` means there is none (plotter configurations are
/// neither read nor written).
pub fn set(dir: Option<PathBuf>) {
if let Ok(mut chosen) = CHOSEN.lock() {
*chosen = Some(dir);
}
}
/// The settings directory: the host's choice, else the platform's.
pub fn current() -> Option<PathBuf> {
match CHOSEN.lock().ok().and_then(|c| c.clone()) {
Some(choice) => choice,
None => platform(|k| std::env::var_os(k)),
}
}
#[cfg(test)]
mod tests {
use super::platform;
use std::ffi::OsString;
use std::path::PathBuf;
fn env<'a>(vars: &'a [(&'a str, &'a str)]) -> impl Fn(&str) -> Option<OsString> + 'a {
move |k| vars.iter().find(|(n, _)| *n == k).map(|(_, v)| OsString::from(v))
}
#[test]
fn empty_values_are_unset() {
assert_eq!(platform(env(&[("HOME", ""), ("XDG_CONFIG_HOME", ""), ("APPDATA", "")])), None, "not the working directory");
assert_eq!(platform(env(&[])), None);
}
#[cfg(all(unix, not(target_os = "macos")))]
#[test]
fn linux_and_bsd_follow_xdg_config_home() {
assert_eq!(platform(env(&[("XDG_CONFIG_HOME", "/x"), ("HOME", "/home/u")])), Some(PathBuf::from("/x/cadcraft")));
assert_eq!(platform(env(&[("HOME", "/home/u")])), Some(PathBuf::from("/home/u/.config/cadcraft")));
// The XDG spec says a relative XDG_CONFIG_HOME is ignored.
assert_eq!(platform(env(&[("XDG_CONFIG_HOME", "rel"), ("HOME", "/home/u")])), Some(PathBuf::from("/home/u/.config/cadcraft")));
}
#[cfg(target_os = "macos")]
#[test]
fn macos_uses_application_support() {
assert_eq!(platform(env(&[("HOME", "/Users/u")])), Some(PathBuf::from("/Users/u/Library/Application Support/CADCraft")));
}
#[cfg(windows)]
#[test]
fn windows_uses_appdata() {
assert_eq!(
platform(env(&[("APPDATA", "C:\\Users\\u\\AppData\\Roaming")])),
Some(PathBuf::from("C:\\Users\\u\\AppData\\Roaming").join("CADCraft"))
);
}
}
+25
View File
@@ -0,0 +1,25 @@
//! A drawing path that isn't valid Unicode is refused: the session keeps paths as text, so it
//! could never be saved back to.
#![cfg(unix)]
use std::ffi::OsString;
use std::os::unix::ffi::OsStringExt;
use cadcraft_doc::Drawing;
use cadcraft_engine::cmd::file::{IoHooks, read_file, set_io};
#[test]
fn read_file_refuses_a_name_that_is_not_unicode() {
set_io(IoHooks { read: |_, _| Ok(Drawing::new_metric()), write: |_, _| Ok(Vec::new()), plot: None });
let dir = std::env::temp_dir().join(format!("cadcraft-nonunicode-{}", std::process::id()));
std::fs::create_dir_all(&dir).unwrap();
let good = dir.join("good.dxf");
let bad = dir.join(OsString::from_vec(b"bad-\xff.dxf".to_vec()));
std::fs::write(&good, b"0\nEOF\n").unwrap();
std::fs::write(&bad, b"0\nEOF\n").unwrap();
let e = read_file(&bad).err().expect("a non-Unicode name is refused");
assert!(e.contains("not valid Unicode") && e.contains("bad-"), "{e}");
assert!(read_file(&good).is_ok());
let _ = std::fs::remove_dir_all(&dir);
}
+1 -1
View File
@@ -29,7 +29,7 @@ fn folder(tag: &str) -> PathBuf {
}
fn save(d: &Drawing, path: &Path) {
std::fs::write(path, cadcraft_io::write(d, &path.to_string_lossy()).unwrap()).unwrap();
std::fs::write(path, cadcraft_io::write(d, path).unwrap()).unwrap();
}
fn line(d: &mut Drawing, layer: &str, a: (f64, f64), b: (f64, f64)) {
+3 -12
View File
@@ -11,8 +11,7 @@
//! - [`fallback_fonts`] (`FONTFALLBACK`): fonts tried first for characters the text's font
//! lacks (CJK in an SHX big font, for example), before the automatic system font search.
//!
//! On native builds both start from the `CADCRAFT_FONTALT` / `CADCRAFT_FONTFALLBACK`
//! environment variables.
//! Both start empty; the host sets its starting values ([`set_font_alt`], [`set_fallback_fonts`]).
use std::collections::HashMap;
use std::path::PathBuf;
@@ -524,16 +523,8 @@ struct Prefs {
}
fn prefs() -> MutexGuard<'static, Prefs> {
static P: OnceLock<Mutex<Prefs>> = OnceLock::new();
P.get_or_init(|| {
#[cfg(not(target_arch = "wasm32"))]
let env = |k: &str| std::env::var(k).unwrap_or_default();
#[cfg(target_arch = "wasm32")]
let env = |_: &str| String::new();
Mutex::new(Prefs { alt: clean_name(&env("CADCRAFT_FONTALT")), fallback: split_list(&env("CADCRAFT_FONTFALLBACK")) })
})
.lock()
.unwrap_or_else(PoisonError::into_inner)
static P: Mutex<Prefs> = Mutex::new(Prefs { alt: String::new(), fallback: Vec::new() });
P.lock().unwrap_or_else(PoisonError::into_inner)
}
/// A font name setting: trimmed, capped, "." = none.
+33 -25
View File
@@ -22,7 +22,9 @@ mod dxf_mline;
use cadcraft_doc::{Drawing, Space};
use cadcraft_geom::Bounds2;
use std::path::{Path, PathBuf};
pub use cadcraft_doc::Format;
pub use cadcraft_dxf::Version;
pub use dxf_read::entity_from_groups;
pub use dxf_write::entity_groups;
@@ -53,40 +55,42 @@ pub enum IoError {
pub type Result<T> = std::result::Result<T, IoError>;
fn ext(name: &str) -> String {
std::path::Path::new(name).extension().map(|e| e.to_string_lossy().to_ascii_lowercase()).unwrap_or_default()
fn ext(name: impl AsRef<Path>) -> String {
name.as_ref().extension().map(|e| e.to_string_lossy().to_ascii_lowercase()).unwrap_or_default()
}
/// Read a drawing; the format comes from the content (DXF ASCII/binary, DWG) or the name
/// (SVG and gzip-compressed SVGZ).
pub fn read(bytes: &[u8], name: &str) -> Result<Drawing> {
pub fn read(bytes: &[u8], name: impl AsRef<Path>) -> Result<Drawing> {
let name = name.as_ref();
if cadcraft_dwg::is_dwg(bytes) {
let (dxf, notes) = cadcraft_dwg::dwg_to_dxf_noted(bytes, cadcraft_dwg::Limits::DEFAULT).map_err(IoError::Format)?;
let mut d = dxf_read::read(&dxf).map_err(|e| IoError::Format(format!("{e} (in the DXF converted from this DWG)")))?;
d.read_notes = notes;
return Ok(d);
}
match ext(name).as_str() {
"svg" | "svgz" => svg_read::read(bytes),
"dxf" | "" => dxf_read::read(bytes),
e if bytes.len() > 4 => dxf_read::read(bytes).map_err(|_| IoError::Unsupported(e.to_string())),
e => Err(IoError::Unsupported(e.to_string())),
match (Format::from_path(name), ext(name).as_str()) {
(Some(Format::Svg | Format::Svgz), _) => svg_read::read(bytes),
(Some(Format::Dxf), _) => dxf_read::read(bytes),
(_, e) if bytes.len() > 4 => dxf_read::read(bytes).map_err(|_| IoError::Unsupported(e.to_string())),
(_, e) => Err(IoError::Unsupported(e.to_string())),
}
}
/// Write a drawing in the format chosen by the name's extension. Images (PNG, SVG, PDF) show
/// model space fitted to its extents. DXF and DWG are written in the drawing's version
/// ([`save_version`]), DXF as ASCII.
pub fn write(d: &Drawing, name: &str) -> Result<Vec<u8>> {
pub fn write(d: &Drawing, name: impl AsRef<Path>) -> Result<Vec<u8>> {
write_framed(d, name, None)
}
/// Like [`write`], with the DXF/DWG version and binary DXF chosen by `opts`. Binary applies to
/// DXF only; asking for it with another format is an error.
pub fn write_with(d: &Drawing, name: &str, opts: &SaveOptions) -> Result<Vec<u8>> {
pub fn write_with(d: &Drawing, name: impl AsRef<Path>, opts: &SaveOptions) -> Result<Vec<u8>> {
let name = name.as_ref();
let version = opts.version.unwrap_or_else(|| save_version(d));
match ext(name).as_str() {
"dxf" | "" => {
match Format::from_path(name) {
Some(Format::Dxf) => {
let tags = dxf_write::tags(d, version);
Ok(if opts.binary {
cadcraft_dxf::write_binary(&tags, version.utf8())
@@ -97,11 +101,11 @@ pub fn write_with(d: &Drawing, name: &str, opts: &SaveOptions) -> Result<Vec<u8>
// The DWG bridge reads our R2000 DXF and writes the DWG at the version asked for. Without
// one, at least 2004: R2000 DWG has no true colours, transparency, table styles or
// gradients, so a drawing from an R2000 DXF doesn't lose them by default.
"dwg" if !opts.binary => {
Some(Format::Dwg) if !opts.binary => {
let version = opts.version.unwrap_or_else(|| version.max(Version::R2004));
cadcraft_dwg::dxf_to_dwg_as(dxf_write::dwg_bridge(d, version).as_bytes(), version.code()).map_err(IoError::Format)
}
e if opts.binary => Err(IoError::Format(format!("binary output is for DXF files, not `{e}`"))),
_ if opts.binary => Err(IoError::Format(format!("binary output is for DXF files, not `{}`", ext(name)))),
_ => write_framed(d, name, None),
}
}
@@ -110,28 +114,32 @@ pub fn write_with(d: &Drawing, name: &str, opts: &SaveOptions) -> Result<Vec<u8>
/// drawing units, centred and scaled to fit the image without distortion) instead of the
/// extents. Formats that are not images (DXF, DWG) ignore the window. The window is checked with
/// [`check_window`].
pub fn write_framed(d: &Drawing, name: &str, window: Option<Bounds2>) -> Result<Vec<u8>> {
pub fn write_framed(d: &Drawing, name: impl AsRef<Path>, window: Option<Bounds2>) -> Result<Vec<u8>> {
let name = name.as_ref();
// A drawing template (.dwt) is DWG content.
if ext(name) == "dwt" {
return write_framed(d, &format!("{name}.dwg"), None);
let format = Format::from_path(name);
if format == Some(Format::Dwt) {
let mut dwg = name.as_os_str().to_owned();
dwg.push(".dwg");
return write_framed(d, PathBuf::from(dwg), None);
}
if let Some(w) = &window
&& is_image(name)
{
check_window(w)?;
}
match ext(name).as_str() {
"dxf" | "" | "dwg" => write_with(d, name, &SaveOptions::default()),
"svg" => Ok(svg::export_window(d, &Space::Model, window).into_bytes()),
"png" => png_framed(d, &Space::Model, 2400, 1600, window),
"pdf" => pdf::pdf(d, &Space::Model, &PdfOptions { compress: true, window, ..PdfOptions::default() }),
e => Err(IoError::Unsupported(e.to_string())),
match format {
Some(Format::Dxf | Format::Dwg) => write_with(d, name, &SaveOptions::default()),
Some(Format::Svg) => Ok(svg::export_window(d, &Space::Model, window).into_bytes()),
Some(Format::Png) => png_framed(d, &Space::Model, 2400, 1600, window),
Some(Format::Pdf) => pdf::pdf(d, &Space::Model, &PdfOptions { compress: true, window, ..PdfOptions::default() }),
_ => Err(IoError::Unsupported(ext(name))),
}
}
/// Whether `name` is written as an image (PNG, SVG, PDF), i.e. whether framing applies to it.
pub fn is_image(name: &str) -> bool {
matches!(ext(name).as_str(), "png" | "svg" | "pdf")
pub fn is_image(name: impl AsRef<Path>) -> bool {
Format::from_path(name).is_some_and(Format::is_image)
}
/// Largest coordinate magnitude accepted in an export window.
+14
View File
@@ -2813,3 +2813,17 @@ fn proxies_keep_their_class_when_classes_are_rewritten() {
dxf_records(&pairs, "ACAD_PROXY_OBJECT").iter().map(|r| classes[own_91(r).parse::<usize>().unwrap() - 500].clone()).collect();
assert_eq!(names, ["VISUALSTYLE", "WIDGETX"]);
}
/// A name that isn't valid Unicode still picks its format by extension.
#[cfg(unix)]
#[test]
fn non_unicode_names_pick_the_format_by_extension() {
use std::os::unix::ffi::OsStringExt as _;
let name = |ext: &str| std::path::PathBuf::from(std::ffi::OsString::from_vec([b"caf\xe9.".as_slice(), ext.as_bytes()].concat()));
assert!(is_image(name("png")) && !is_image(name("dxf")));
let d = sample();
let bytes = write(&d, name("dxf")).unwrap();
assert!(read(&bytes, name("dxf")).is_ok());
assert!(write(&d, name("png")).unwrap().starts_with(b"\x89PNG"));
assert!(write(&d, name("dwt")).is_ok(), "a template is written as DWG");
}
+1
View File
@@ -12,6 +12,7 @@ workspace = true
cadcraft-engine = { workspace = true }
cadcraft-render = { workspace = true }
cadcraft-io = { workspace = true }
clap = { workspace = true }
serde_json = { workspace = true }
log = { workspace = true }
# Secure randomness for the per-session control token (MIT OR Apache-2.0).
+51
View File
@@ -0,0 +1,51 @@
//! Helpers for clap parsers shared by the apps: environment variables as flag fallbacks.
//!
//! Apply [`blank_env_is_unset`] to the arguments, so an empty variable counts as unset, and pass a
//! parse error through [`name_env_vars`], so a bad value names the variable it came from.
use std::ffi::{OsStr, OsString};
use clap::{Arg, Command};
/// For `Command::mut_args`: an empty or blank variable counts as unset, so `CADCRAFT_CONTROL_PORT=`
/// turns a fallback off without `unset`. clap would pass the empty value to the parser. `var`
/// looks the variable up.
pub fn blank_env_is_unset(arg: Arg, var: impl Fn(&OsStr) -> Option<OsString>) -> Arg {
let blank = arg.get_env().and_then(var).is_some_and(|v| v.to_str().is_some_and(|v| v.trim().is_empty()));
if blank { arg.env(None::<&str>) } else { arg }
}
/// clap names the flag when a value from its variable is bad or conflicts with another, as if the
/// flag had been given: name the variable instead when the flag isn't among `args` (without the
/// binary name; a first one naming a subcommand selects whose arguments to look in).
pub fn name_env_vars(mut error: clap::Error, cmd: &Command, args: &[OsString]) -> clap::Error {
use clap::error::{ContextKind, ContextValue};
// `--flag value` or `--flag=value`.
let given =
|long: &str| args.iter().filter_map(|a| a.to_str()?.strip_prefix("--")?.strip_prefix(long)).any(|r| r.is_empty() || r.starts_with('='));
let sub = args.first().and_then(|name| cmd.find_subcommand(name)).unwrap_or(cmd);
for kind in [ContextKind::InvalidArg, ContextKind::PriorArg] {
let Some(ContextValue::String(shown)) = error.get(kind) else { continue };
let Some(arg) = sub.get_arguments().find(|a| a.to_string() == *shown) else { continue };
let (Some(long), Some(var)) = (arg.get_long(), arg.get_env()) else { continue };
if !given(long) {
error.insert(kind, ContextValue::String(var.to_string_lossy().into_owned()));
}
}
error
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn blank_variables_count_as_unset() {
let arg = || Arg::new("control").long("control").env("CADCRAFT_CONTROL_PORT");
for value in ["", " "] {
assert_eq!(blank_env_is_unset(arg(), |_| Some(value.into())).get_env(), None, "{value:?}");
}
assert!(blank_env_is_unset(arg(), |_| Some(" 50494 ".into())).get_env().is_some());
assert!(blank_env_is_unset(arg(), |_| None).get_env().is_some());
}
}
+1
View File
@@ -8,6 +8,7 @@
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
#![forbid(unsafe_code)]
pub mod args;
mod backend;
pub mod control_token;
mod server;
+1 -1
View File
@@ -575,7 +575,7 @@ pub fn start_page(app: &mut CadApp, ui: &mut egui::Ui) {
y += 46.0;
}
if let Some(path) = recent {
app.open_path(&path);
app.open_path(std::path::Path::new(&path));
} else if app.ui.recent_files.is_empty() {
p.text(
pos2(main.center().x, main.center().y),
+3 -3
View File
@@ -350,9 +350,9 @@ pub fn show(app: &mut crate::CadApp, ui: &mut egui::Ui) {
#[cfg(not(target_arch = "wasm32"))]
for files in std::mem::take(&mut output.window_files) {
for file in files.dropped {
let path = file.path().to_string_lossy().to_string();
if !path.is_empty() {
app.open_path(&path);
let path = file.path();
if !path.as_os_str().is_empty() {
app.open_path(path);
}
}
}
+9 -17
View File
@@ -23,6 +23,8 @@ use cadcraft_render::{DisplayList, Kind};
use egui_wgpu::wgpu;
use egui_wgpu::wgpu::util::DeviceExt;
use crate::switch::Switch;
/// Line/triangle vertex: position (2 × f32, relative to the origin) + sRGB colour (4 × u8,
/// premultiplied by its alpha: transparent objects blend with what is under them).
const VERTEX_SIZE: usize = 12;
@@ -44,12 +46,8 @@ const POINT_SIZE: f32 = 1.5;
/// then Mailbox, then falls back to FIFO, so it is valid on every surface; under a compositor the
/// compositor still syncs to the display. `vsync` is the `CADCRAFT_VSYNC` override: `1`/`on`
/// forces FIFO (tear-free without a compositor), `0`/`off` forces the low-latency mode.
pub fn surface_config(vsync: Option<&str>, low_latency: bool) -> egui_wgpu::SurfaceConfig {
let no_vsync = match vsync.map(|v| v.trim().to_ascii_lowercase()).as_deref() {
Some("1" | "on" | "true" | "yes") => false,
Some("0" | "off" | "false" | "no") => true,
_ => low_latency,
};
pub fn surface_config(vsync: Switch, low_latency: bool) -> egui_wgpu::SurfaceConfig {
let no_vsync = !vsync.or(!low_latency);
egui_wgpu::SurfaceConfig {
present_mode: if no_vsync { wgpu::PresentMode::AutoNoVsync } else { wgpu::PresentMode::AutoVsync },
desired_maximum_frame_latency: Some(1),
@@ -801,17 +799,11 @@ mod tests {
#[test]
fn surface_config_prefers_low_latency_where_asked_and_honours_override() {
use wgpu::PresentMode::{AutoNoVsync, AutoVsync};
assert_eq!(surface_config(None, true).present_mode, AutoNoVsync);
assert_eq!(surface_config(None, false).present_mode, AutoVsync);
for on in ["1", "on", " TRUE ", "yes"] {
assert_eq!(surface_config(Some(on), true).present_mode, AutoVsync, "{on}");
}
for off in ["0", "Off", "false", "no"] {
assert_eq!(surface_config(Some(off), false).present_mode, AutoNoVsync, "{off}");
}
assert_eq!(surface_config(Some("maybe"), true).present_mode, AutoNoVsync);
assert_eq!(surface_config(Some(""), false).present_mode, AutoVsync);
assert_eq!(surface_config(None, true).desired_maximum_frame_latency, Some(1));
assert_eq!(surface_config(Switch::Default, true).present_mode, AutoNoVsync);
assert_eq!(surface_config(Switch::Default, false).present_mode, AutoVsync);
assert_eq!(surface_config(Switch::On, true).present_mode, AutoVsync);
assert_eq!(surface_config(Switch::Off, false).present_mode, AutoNoVsync);
assert_eq!(surface_config(Switch::Default, true).desired_maximum_frame_latency, Some(1));
}
#[cfg(not(target_arch = "wasm32"))]
+28 -11
View File
@@ -27,6 +27,7 @@ pub mod hatchdlg;
mod mtext_editor;
mod panel_state;
pub mod spacemouse;
pub mod switch;
// The External References palette.
pub mod xrefs;
@@ -55,6 +56,7 @@ pub mod vpscale;
pub mod exchange;
use std::path::Path;
use std::sync::mpsc::Receiver;
use cadcraft_engine::Session;
@@ -88,7 +90,7 @@ pub struct UiState {
/// Keep the system cursor visible over the drawing area (a small crosshair at the centre of the
/// drawn one) instead of hiding it. Screen magnifiers (Windows Magnifier "follow the mouse
/// pointer"), screen readers, recorders and remote desktops track the system cursor and lose it
/// when it is hidden. Off by default; `CADCRAFT_SYSTEM_CURSOR=1` turns it on at startup.
/// when it is hidden. Off unless the host defaults to it ([`CadApp::set_system_cursor_default`]).
pub system_cursor: bool,
/// "Drafting" or "Modeling".
pub toolset_tab: String,
@@ -173,7 +175,7 @@ impl Default for UiState {
show_viewcube: true,
show_ucs_icon: true,
show_layer_list: false,
system_cursor: std::env::var("CADCRAFT_SYSTEM_CURSOR").is_ok_and(|v| !matches!(v.trim(), "" | "0" | "false" | "off")),
system_cursor: false,
toolset_tab: "Drafting".into(),
collapsed_groups: Vec::new(),
hidden_tools: Vec::new(),
@@ -211,6 +213,8 @@ pub struct CadApp {
/// Whether the operating system shows animations, as the host reads it; `None` when the OS
/// states nothing or the host cannot ask ([`animation`]).
pub system_animations: Option<bool>,
/// What `ui.system_cursor` goes back to when the interface is reset ([`Self::set_system_cursor_default`]).
pub system_cursor_default: bool,
pub session: Session,
pub ui: UiState,
/// The interface's own preferences from the Options dialog ([`options`]).
@@ -296,6 +300,7 @@ impl CadApp {
CadApp {
system_languages: Vec::new(),
system_animations: None,
system_cursor_default: false,
session,
ui: UiState::default(),
options: options::UiOptions::default(),
@@ -469,6 +474,15 @@ impl CadApp {
}
}
/// Make the system cursor the interface default (`on`) and turn it on; saved preferences and
/// resets never turn it off then.
pub fn set_system_cursor_default(&mut self, on: bool) {
self.system_cursor_default = on;
if on {
self.ui.system_cursor = true;
}
}
pub fn set_status(&mut self, s: impl Into<String>) {
self.status = Some((s.into(), now_ms()));
}
@@ -481,12 +495,12 @@ impl CadApp {
/// Open the drawing at `path`. Natively the file is read on a worker thread while an
/// "Opening ..." card shows ([`opening`]); [`Self::finish_opening`] adds it when ready. On the
/// web it opens at once.
pub fn open_path(&mut self, path: &str) {
pub fn open_path(&mut self, path: &Path) {
// A LISP file (dropped on the window): loaded as APPLOAD loads it.
if is_lisp_file(path) {
match cadcraft_engine::lisp::builtins::read_text_file(path) {
Some(text) => self.load_lisp(path, &text),
None => self.open_failed(format!("APPLOAD: can't read {path}")),
Some(text) => self.load_lisp(&path.to_string_lossy(), &text),
None => self.open_failed(format!("APPLOAD: can't read {}", path.display())),
}
return;
}
@@ -496,7 +510,10 @@ impl CadApp {
}
#[cfg(target_arch = "wasm32")]
{
let r = self.run("open", json!({ "path": path }));
let r = match path.to_str() {
Some(text) => self.run("open", json!({ "path": text })),
None => Err(format!("open: {}: the path is not valid Unicode", path.display())),
};
self.opened(r);
}
}
@@ -800,9 +817,9 @@ impl CadApp {
{
let dropped = ctx.input_mut(|input| std::mem::take(&mut input.raw.dropped_files));
for file in dropped {
let path = file.path().to_string_lossy().to_string();
if !path.is_empty() {
self.open_path(&path);
let path = file.path();
if !path.as_os_str().is_empty() {
self.open_path(path);
}
}
}
@@ -889,8 +906,8 @@ pub fn now_ms() -> f64 {
}
/// A LISP source file, by its name.
fn is_lisp_file(name: &str) -> bool {
std::path::Path::new(name).extension().is_some_and(|e| e.eq_ignore_ascii_case("lsp"))
fn is_lisp_file(name: impl AsRef<Path>) -> bool {
name.as_ref().extension().is_some_and(|e| e.eq_ignore_ascii_case("lsp"))
}
#[cfg(test)]
+13 -3
View File
@@ -128,7 +128,7 @@ fn run_recent_file_command(app: &mut CadApp, id: &str) -> Option<Result<Value, S
}
if let Some(i) = id.strip_prefix(RECENT_ITEM).and_then(|n| n.parse::<usize>().ok()) {
let Some(path) = app.ui.recent_files.get(i).cloned() else { return Some(Err(format!("no recent file {i}"))) };
app.open_path(&path);
app.open_path(std::path::Path::new(&path));
return Some(Ok(Value::Null));
}
None
@@ -319,7 +319,7 @@ fn run_ui_command_inner(app: &mut CadApp, id: &str, params: &Value) -> Option<Re
"ui.open" | "open" if no_path => {
let picked = app.services.pick_open.as_ref().and_then(|f| f());
if let Some(p) = picked {
app.open_path(&p);
app.open_path(std::path::Path::new(&p));
}
Ok(Value::Null)
}
@@ -404,7 +404,17 @@ fn run_ui_command_inner(app: &mut CadApp, id: &str, params: &Value) -> Option<Re
"ui.resetpalettes" => {
let (menu, theme, interface_language, save_format) = (app.ui.in_window_menu, app.ui.theme, app.ui.interface_language, app.ui.save_format);
let (animations, save_version) = (app.ui.animations, std::mem::take(&mut app.ui.save_version));
app.ui = crate::UiState { in_window_menu: menu, theme, animations, interface_language, save_format, save_version, ..Default::default() };
let system_cursor = app.system_cursor_default;
app.ui = crate::UiState {
in_window_menu: menu,
theme,
animations,
interface_language,
save_format,
save_version,
system_cursor,
..Default::default()
};
Ok(Value::Null)
}
"ui.start" => {
+14 -12
View File
@@ -3,6 +3,7 @@
//! a spinner and the elapsed time and keeps painting. The finished drawing is added to the session
//! on the UI thread. The web build has no threads and opens synchronously.
use std::path::{Path, PathBuf};
use std::sync::mpsc::{Receiver, TryRecvError, channel};
use std::time::{Duration, Instant};
@@ -13,7 +14,7 @@ use crate::theme::Tokens;
type Outcome = Result<ReadFile, String>;
struct Job {
path: String,
path: PathBuf,
started: Instant,
rx: Receiver<Outcome>,
}
@@ -26,20 +27,20 @@ pub struct Opening {
impl Opening {
/// Start reading `path` on a worker thread.
pub fn start(&mut self, path: &str) {
pub fn start(&mut self, path: &Path) {
let (tx, rx) = channel();
let p = path.to_string();
let p = path.to_path_buf();
let spawned = std::thread::Builder::new().name("cadcraft-open".into()).spawn(move || {
let _ = tx.send(read_file(&p));
});
if spawned.is_err() {
// No thread to read on: report it like any other failed open.
let (tx, rx2) = channel();
let _ = tx.send(Err(format!("open: {path}: could not start a reader thread")));
self.jobs.push(Job { path: path.to_string(), started: Instant::now(), rx: rx2 });
let _ = tx.send(Err(format!("open: {}: could not start a reader thread", path.display())));
self.jobs.push(Job { path: path.to_path_buf(), started: Instant::now(), rx: rx2 });
return;
}
self.jobs.push(Job { path: path.to_string(), started: Instant::now(), rx });
self.jobs.push(Job { path: path.to_path_buf(), started: Instant::now(), rx });
}
/// Whether any file is still being read.
@@ -48,7 +49,7 @@ impl Opening {
}
/// The finished reads, as (path, result). A reader that died without answering is an error.
pub fn poll(&mut self) -> Vec<(String, Outcome)> {
pub fn poll(&mut self) -> Vec<(PathBuf, Outcome)> {
let mut done = Vec::new();
self.jobs.retain(|j| match j.rx.try_recv() {
Ok(r) => {
@@ -57,7 +58,7 @@ impl Opening {
}
Err(TryRecvError::Empty) => true,
Err(TryRecvError::Disconnected) => {
done.push((j.path.clone(), Err(format!("open: {}: the file could not be read", j.path))));
done.push((j.path.clone(), Err(format!("open: {}: the file could not be read", j.path.display()))));
false
}
});
@@ -67,7 +68,7 @@ impl Opening {
/// The text of the card: the file and how long it has taken, or how many files are queued.
fn label(&self) -> Option<String> {
let first = self.jobs.first()?;
let name = std::path::Path::new(&first.path).file_name().map_or_else(|| first.path.clone(), |n| n.to_string_lossy().to_string());
let name = first.path.file_name().unwrap_or(first.path.as_os_str()).to_string_lossy();
let secs = first.started.elapsed().as_secs_f32();
let more = self.jobs.len() - 1;
Some(if more == 0 { format!("Opening {name}... {secs:.0} s") } else { format!("Opening {name} and {more} more... {secs:.0} s") })
@@ -100,6 +101,7 @@ impl Opening {
#[cfg(test)]
mod tests {
use std::path::Path;
use std::time::{Duration, Instant};
use cadcraft_engine::Session;
@@ -114,7 +116,7 @@ mod tests {
let before = app.session.docs.len();
let missing = std::env::temp_dir().join(format!("cadcraft-missing-{}.dxf", std::process::id()));
let p = missing.to_string_lossy().to_string();
app.open_path(&p);
app.open_path(&missing);
assert!(app.opening.busy() || app.status.is_some(), "the read starts in the background");
let t = Instant::now();
while app.opening.busy() && t.elapsed() < Duration::from_secs(10) {
@@ -133,8 +135,8 @@ mod tests {
fn card_text_names_the_file_and_counts_queued_ones() {
let mut o = super::Opening::default();
assert!(o.label().is_none());
o.start("/nonexistent/dir/a.dxf");
o.start("/nonexistent/dir/b.dxf");
o.start(Path::new("/nonexistent/dir/a.dxf"));
o.start(Path::new("/nonexistent/dir/b.dxf"));
let l = o.label().unwrap_or_default();
assert!(l.starts_with("Opening a.dxf and 1 more"), "{l}");
}
+2 -2
View File
@@ -310,7 +310,7 @@ fn reset_ui(app: &mut CadApp) {
app.ui.animations = d.animations;
app.ui.save_format = d.save_format;
app.ui.save_version = d.save_version;
app.ui.system_cursor = d.system_cursor;
app.ui.system_cursor = app.system_cursor_default;
app.ui.history_lines = d.history_lines;
app.options = UiOptions::default();
}
@@ -353,7 +353,7 @@ impl CadApp {
let _ = parse_ui(key, value, &mut c);
}
}
// CADCRAFT_SYSTEM_CURSOR=1 turns the system cursor on whatever was saved.
// A saved `false` leaves the host's default (`set_system_cursor_default`) in place.
if c.system_cursor == Some(true) {
self.ui.system_cursor = true;
}
+54
View File
@@ -0,0 +1,54 @@
//! Boolean environment switches (`CADCRAFT_VSYNC`, `CADCRAFT_WAYLAND`, ...): one parser, so every
//! variable accepts the same spellings.
/// `1/on/true/yes` or `0/off/false/no`, case- and space-insensitive. Blank or unset is `Default`;
/// anything else is `Default` and logged.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Switch {
On,
Off,
Default,
}
impl Switch {
/// Parse the value of the variable `name`; `name` only appears in the warning.
pub fn parse(name: &str, value: Option<&str>) -> Switch {
let Some(value) = value else { return Switch::Default };
match value.trim().to_ascii_lowercase().as_str() {
"1" | "on" | "true" | "yes" => Switch::On,
"0" | "off" | "false" | "no" => Switch::Off,
"" => Switch::Default,
_ => {
log::warn!("{name}={value:?} is not 1/on/true/yes or 0/off/false/no; using the default");
Switch::Default
}
}
}
/// Whether the switch is on, with `default` for `Default`.
pub fn or(self, default: bool) -> bool {
match self {
Switch::On => true,
Switch::Off => false,
Switch::Default => default,
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parses_every_spelling() {
for v in ["1", "on", "true", "yes", "ON", "True", " Yes ", "\t1\n"] {
assert_eq!(Switch::parse("X", Some(v)), Switch::On, "{v:?}");
}
for v in ["0", "off", "false", "no", "OFF", "False", " No ", " 0 "] {
assert_eq!(Switch::parse("X", Some(v)), Switch::Off, "{v:?}");
}
for v in [None, Some(""), Some(" "), Some("maybe"), Some("2"), Some("onn")] {
assert_eq!(Switch::parse("X", v), Switch::Default, "{v:?}");
}
}
}
+2 -2
View File
@@ -133,7 +133,7 @@ fn opening_a_drawing_with_authoring_elements_offers_the_block_editor() {
let symbol = dir.join("Symbol.dxf");
std::fs::write(&symbol, "authoring").unwrap();
let mut app = CadApp::new(Session::new(), Services::default());
app.open_path(&symbol.to_string_lossy());
app.open_path(&symbol);
// The file is read in the background (#797): wait for it to be added.
let t = std::time::Instant::now();
while app.opening.busy() && t.elapsed() < std::time::Duration::from_secs(10) {
@@ -163,7 +163,7 @@ fn opening_a_drawing_with_authoring_elements_offers_the_block_editor() {
let plain = dir.join("Plain.dxf");
std::fs::write(&plain, "plain").unwrap();
let mut app = CadApp::new(Session::new(), Services::default());
app.open_path(&plain.to_string_lossy());
app.open_path(&plain);
// The file is read in the background (#797): wait for it to be added.
let t = std::time::Instant::now();
while app.opening.busy() && t.elapsed() < std::time::Duration::from_secs(10) {
+20
View File
@@ -35,3 +35,23 @@ fn system_cursor_stays_visible_over_the_canvas_when_requested() {
assert!(app.ui.system_cursor);
assert_eq!(canvas_cursor(&mut app), egui::CursorIcon::Crosshair, "systemCursor keeps an OS cursor for magnifiers");
}
/// The host's default (the desktop app's `CADCRAFT_SYSTEM_CURSOR`) turns it on; a saved `false`
/// and the resets keep it.
#[test]
fn the_host_default_survives_saved_profiles_and_resets() {
let mut app = CadApp::new(Session::new(), Services::default());
app.run("options", serde_json::json!({ "reset": true })).unwrap();
assert!(!app.ui.system_cursor, "off without a host default");
app.set_system_cursor_default(true);
assert!(app.ui.system_cursor);
app.load_profile(r#"{"systemCursor": false}"#);
assert!(app.ui.system_cursor);
app.ui.system_cursor = false;
app.run("options", serde_json::json!({ "reset": true })).unwrap();
assert!(app.ui.system_cursor);
app.ui.system_cursor = false;
app.run("ui.resetpalettes", serde_json::json!({})).unwrap();
assert!(app.ui.system_cursor);
}
+4 -4
View File
@@ -53,15 +53,15 @@ fn opened_drawings_are_listed_newest_first_and_survive_a_restart() {
let mut app = CadApp::new(Session::empty(), Services::default());
assert!(app.ui.recent_files.is_empty());
app.open_path(&plan);
app.open_path(std::path::Path::new(&plan));
settle(&mut app);
app.open_path(&section);
app.open_path(std::path::Path::new(&section));
settle(&mut app);
app.open_path(&plan);
app.open_path(std::path::Path::new(&plan));
settle(&mut app);
assert_eq!(app.ui.recent_files, [plan.clone(), section.clone()], "newest first, each file once");
// A file that could not be opened is not listed.
app.open_path("/nonexistent/missing.dxf");
app.open_path(std::path::Path::new("/nonexistent/missing.dxf"));
settle(&mut app);
assert_eq!(app.ui.recent_files, [plan.clone(), section.clone()]);
+58
View File
@@ -0,0 +1,58 @@
# cadcraft-cli
`cadcraft-cli` is headless CADCraft: it reads, converts and exports drawings, runs scripts and
commands, prints the command catalog and serves MCP. It follows
[RFC-0012: Command-line conventions](https://github.com/storytold/craft-contrib/pull/18).
`cadcraft-cli --help` and `cadcraft-cli help <subcommand>` (or `<subcommand> --help`) are the
reference for every subcommand, flag and value; this page doesn't repeat them. Examples are in the
[README](../README.md#drive-it-from-agents-mcp-and-the-cli), MCP setup in [mcp.md](mcp.md),
scripts and the JSON command forms in [customization.md](customization.md).
## Conventions
| | |
|---|---|
| Exit codes | `0` success, `1` the command failed, `2` usage error. |
| Streams | Results on stdout. `info` and `commands` print pretty JSON, or one line with `--compact`; `run` prints one JSON line per `--cmd` result (JSON lines); a command with no result (JSON `null`) prints no line. Errors (`error: …`), warnings and `wrote …` lines on stderr. `mcp` speaks MCP on stdout and writes nothing else there. |
| Usage errors | An unknown or repeated flag, a missing or malformed value (`--window`, `--view`, `--cmd` JSON, a sample name), flags that conflict (`--window` with `--view`) or that need another (`run --window` without `--export`) stop before any work, with exit 2. `--script`, `--script-file`, `--cmd` and `run`'s files repeat and run in command-line order. |
| Outputs that replace an input | `convert IN OUT` and `run FILE… --save OUT` / `--export OUT` refuse an OUT that is the same file as an input (any spelling or symlink of it): usage error, exit 2, nothing opened or written. `--in-place` allows it. A save a script or `--cmd` runs is the engine's. |
| Values starting with `-` | Written with `=`: `--window=-10,-10,10,10`, `--export=-plan.png`. |
| Paths | Read as given, including names that aren't valid Unicode. The engine opens files by text name, so such a name is reported as an error (exit 1) where a drawing is opened; an output takes any name whose extension is ASCII. |
| Completions and man pages | The Linux packages install them. To generate them yourself: `cargo run -p cadcraft-cli --example man-and-completions -- <out-dir>`. |
## Environment variables
Variables are fallbacks for flags; `--help` shows each next to its flag. An empty value counts as
unset and the flag wins over the variable, except for `CADCRAFT_CONFIG_DIR` (see below).
| Variable | Flag | Subcommands |
|---|---|---|
| `CADCRAFT_CONFIG_DIR` | `--config-dir` (the settings folder; plotter configurations are in its `plotters` folder; empty means no settings folder) | `convert`, `run`, `mcp`, `sample` |
| `CADCRAFT_FONTALT` | `--fontalt` (FONTALT) | `convert`, `run`, `mcp`, `sample` |
| `CADCRAFT_FONTFALLBACK` | `--fontfallback` (FONTFALLBACK) | `convert`, `run`, `mcp`, `sample` |
The desktop app's are listed by `cadcraft --help`; its one flag fallback is
`CADCRAFT_CONTROL_PORT` for `--control`, where a bad value is a usage error that names the
variable.
## Not followed yet
- **`CADCRAFT_CONFIG_DIR` is the one flag fallback where an empty variable doesn't count as
unset** (RFC-0012 rule 1.7): empty (or `--config-dir ""`) means no settings folder, as it did
before the port.
- **No variable for `mcp --connect`.** Photocraft's `mcp --bridge` falls back to its
`*_CONTROL_PORT` variable. Here an exported `CADCRAFT_CONTROL_PORT` would silently switch `mcp`
from a headless session to the running app, so `--connect` stays a flag only.
- **The desktop app on Windows** is built without a console, so a usage error in its launch flags
isn't visible there; the app exits with code 2.
- **The `string-error` ast-grep rule** covers the CLI code only. The engine's file hooks
(`cadcraft_engine::cmd::file::IoHooks`) still return `Result<_, String>`, so `install_io` maps
errors to strings at that boundary.
- **No AGENTS.md line for the ast-grep scan.** RFC-0012 asks an app's AGENTS.md to have coding
agents run the scan before pushing (`ast-grep scan -c lint/ast-grep/sgconfig.yml`); CI runs it
on every PR that touches the CLI code.
- **`perf` prints a text table**, with no `--json` (whether text listings get one is an open
question in RFC-0012).
- **Saves a command or script runs** (`--cmd 'saveas {…}'`, a script's `SAVEAS`) are the engine's
and are not checked against the opened drawings; only `--save` and `--export` are.
+1 -1
View File
@@ -124,7 +124,7 @@ height and related chrome choices. It does not store drawings, command buffers,
current Start tab. The default directory is `~/Library/Application Support/CADCraft` on macOS,
`%APPDATA%/CADCraft` on Windows, and `$XDG_CONFIG_HOME/cadcraft` or `~/.config/cadcraft` elsewhere.
Set `CADCRAFT_CONFIG_DIR` to a private directory for an isolated profile; an explicitly empty
value disables workspace reads and writes. An invalid, oversized or newer-version file is
value disables all settings reads and writes (workspace, logs, autosave, plotters). An invalid, oversized or newer-version file is
reported and left untouched, with persistence disabled for that launch. Repair or move that
file before restarting to resume saving workspace choices.
+2 -1
View File
@@ -32,7 +32,8 @@ settings directory:
| macOS | `~/Library/Application Support/CADCraft/plotters` |
| Windows | `%APPDATA%\CADCraft\plotters` |
`CADCRAFT_CONFIG_DIR` replaces the settings directory. On the web, devices last for the
`CADCRAFT_CONFIG_DIR` replaces the settings directory; empty means none (`cadcraft-cli`:
`--config-dir`, which falls back to the same variable). On the web, devices last for the
session unless the host provides storage (`cmd::plotters::set_plotter_store`). Binary `.pc3`
files are not read; we haven't found a public specification of that format.
+19
View File
@@ -0,0 +1,19 @@
id: args-os
valid:
- let code = photocraft_cli::run(std::env::args_os().skip(1), &mut out, &mut err);
- "let args: Vec<OsString> = env::args_os().collect();"
- |
use std::env::args_os;
fn main() { let a: Vec<_> = args_os().collect(); }
- |
fn args() -> Vec<String> { Vec::new() }
fn main() { let a = args(); }
invalid:
- "let args: Vec<String> = std::env::args().collect();"
- for a in env::args().skip(1) {}
- |
use std::env::args;
fn main() { let a: Vec<String> = args().collect(); }
- |
use std::env::{args, var};
fn main() { for a in args() {} }
@@ -0,0 +1,13 @@
id: clap-error-message
valid:
- cmd.error(ErrorKind::ArgumentConflict, UsageError::BridgeRoots)
- cmd.error(ErrorKind::ArgumentConflict, Conflict { a, b })
- sub.error(kind, self)
- log.error("not a clap error")
invalid:
- cmd.error(ErrorKind::ArgumentConflict, "configure automation roots on the desktop app")
- sub.error(ErrorKind::MissingRequiredArgument, format!("{flag} requires {transport}"))
- sub.error(ErrorKind::ArgumentConflict, BRIDGE_ROOTS)
- cmd.error(ErrorKind::InvalidValue, e.to_string())
- cmd.error(ErrorKind::InvalidValue, String::from("bad value"))
- clap::Error::raw(ErrorKind::InvalidValue, "bad value")
@@ -0,0 +1,47 @@
id: clap-error-message-variable
valid:
- |
fn conflict(cmd: &mut Command, a: String, b: String) -> clap::Error {
cmd.error(ErrorKind::ArgumentConflict, Conflict { a, b })
}
- |
fn wrap(cmd: &mut Command, e: UsageError) -> clap::Error {
cmd.error(ErrorKind::ValueValidation, e)
}
- |
fn unrelated(cmd: &mut Command, e: UsageError) -> clap::Error {
let shown = format!("{e}");
eprintln!("{shown}");
cmd.error(ErrorKind::ValueValidation, e)
}
- |
fn cloned(cmd: &mut Command, e: &UsageError) -> clap::Error {
let owned = e.to_owned();
cmd.error(ErrorKind::ValueValidation, owned)
}
invalid:
- |
fn conflict(cmd: &mut Command, a: &str, b: &str) -> clap::Error {
let message = format!("the argument '{a}' cannot be used with '{b}'");
cmd.error(ErrorKind::ArgumentConflict, message)
}
- |
fn bad(cmd: &mut Command, e: UsageError) -> clap::Error {
let message = e.to_string();
cmd.error(ErrorKind::ValueValidation, message)
}
- |
fn typed(cmd: &mut Command, flag: &str) -> clap::Error {
let message: String = flag.into();
clap::Error::raw(ErrorKind::InvalidValue, message)
}
- |
fn literal(cmd: &mut Command) -> clap::Error {
let message = "bad value".to_owned();
cmd.error(ErrorKind::InvalidValue, message)
}
- |
fn from(cmd: &mut Command) -> clap::Error {
let message = String::from("bad value");
cmd.error(ErrorKind::InvalidValue, message)
}
@@ -0,0 +1,14 @@
id: string-error
valid:
- "fn parse(s: &str) -> Result<Port, PortError> { todo!() }"
- "fn name() -> Option<String> { None }"
- "fn ok() -> Result<String, PortError> { Ok(String::new()) }"
- Err(PortError::Range)
- Err(e)
invalid:
- "fn parse(s: &str) -> Result<Port, String> { todo!() }"
- "type R = Result<(), String>;"
- Err(format!("bad port {s}"))
- Err(e.to_string())
- Err(String::from("bad port"))
- Err("bad port")
+21
View File
@@ -0,0 +1,21 @@
id: args-os
language: rust
severity: error
message: std::env::args() panics on an argument that isn't valid Unicode
note: |
Read std::env::args_os() and let clap parse the OsStrings, so a Latin-1 file name reaches the
command (or is a usage error) instead of aborting before anything is printed (photocraft#1108).
rule:
any:
- pattern: std::env::args()
- pattern: env::args()
# A bare args() only where the file imports std::env::args, not any function named args.
- all:
- pattern: args()
- inside:
kind: source_file
stopBy: end
has:
kind: use_declaration
stopBy: end
regex: std::env::(args\b|\{[^}]*\bargs\b)
@@ -0,0 +1,35 @@
id: clap-error-message-variable
language: rust
severity: error
message: clap error built from a string held in a variable
note: |
The message was built with format!, .to_string(), String::from or a literal's .to_owned() a
few lines up. Give it a variant on a
#[derive(thiserror::Error)] enum instead, with the parts as fields, and pass the variant.
rule:
# In this order: the call binds $MSG, then the function must hold a `let` of that same name.
all:
- any:
- pattern: $CMD.error($KIND, $MSG)
- pattern: Error::raw($KIND, $MSG)
- pattern: clap::Error::raw($KIND, $MSG)
- inside:
kind: function_item
stopBy: end
has:
stopBy: end
any:
- pattern: let $MSG = format!($$$);
- pattern: "let $MSG: String = $VAL;"
- pattern: let $MSG = $SRC.to_string();
- pattern: let $MSG = String::from($$$);
# .to_owned() only on a string literal: on anything else it may clone a typed error.
- all:
- kind: let_declaration
- regex: '=\s*"(?s:.*)"\s*\.to_owned\(\)\s*;?$'
- has:
field: pattern
pattern: $MSG
constraints:
MSG:
kind: identifier
@@ -0,0 +1,26 @@
id: clap-error-message
language: rust
severity: error
message: clap error built from a string
note: |
Give the message a variant on a #[derive(thiserror::Error)] enum and pass the variant, e.g.
`cmd.error(ErrorKind::ArgumentConflict, UsageError::BridgeRoots)`. A string literal, format!,
.to_string() or a SCREAMING_CASE const keeps the message apart from the error's type.
rule:
any:
- pattern: $CMD.error($KIND, $MSG)
- pattern: Error::raw($KIND, $MSG)
- pattern: clap::Error::raw($KIND, $MSG)
constraints:
MSG:
any:
- kind: string_literal
- all:
- kind: macro_invocation
- regex: ^format!
- all:
- kind: identifier
- regex: ^[A-Z][A-Z0-9_]*$
- all:
- kind: call_expression
- regex: \.(to_string|to_owned)\(\)$|^String::from\(
+21
View File
@@ -0,0 +1,21 @@
id: string-error
language: rust
severity: error
message: String as an error type
note: |
Return a #[derive(thiserror::Error)] enum, so a caller can match on what failed and the
messages live with their variants.
rule:
any:
- pattern:
context: type T = Result<$OK, String>;
selector: generic_type
- pattern: Err(format!($$$))
- pattern: Err($S.to_string())
- pattern: Err(String::from($$$))
- all:
- pattern: Err($S)
- has:
kind: arguments
has:
kind: string_literal
+6
View File
@@ -0,0 +1,6 @@
# Structural rules for the command-line code (RFC-0012), run by .github/workflows/ast-grep.yml.
# Each rule in rules/ has its cases in rule-tests/, which CI checks before the scan.
ruleDirs:
- rules
testConfigs:
- testDir: rule-tests
+25
View File
@@ -44,11 +44,16 @@ BASENAME="cadcraft-$VERSION-linux-$ARCH"
echo "==> CADCraft $VERSION for Linux $ARCH ($FORMATS)"
# The man-and-completions example writes cadcraft-cli's man pages and shell completions below. It
# is built in its own cargo run: built with the binaries, its dev-dependencies' features would be
# unified into them.
if [[ "$SKIP_BUILD" = 0 ]]; then
if [[ -n "${CROSS_TARGET:-}" ]]; then
(cd "$ROOT" && cargo build --release --locked -p cadcraft -p cadcraft-cli --target "$CROSS_TARGET")
(cd "$ROOT" && cargo build --release --locked -p cadcraft-cli --example man-and-completions --target "$CROSS_TARGET")
else
(cd "$ROOT" && cargo build --release --locked -p cadcraft -p cadcraft-cli)
(cd "$ROOT" && cargo build --release --locked -p cadcraft-cli --example man-and-completions)
fi
fi
BIN="$CARGO_TARGET_DIR/${CROSS_TARGET:+$CROSS_TARGET/}release"
@@ -69,6 +74,26 @@ mkdir -p "$STAGE/usr/share/icons"
cp -R "$ROOT/assets/app-icon/hicolor" "$STAGE/usr/share/icons/"
mkdir -p "$STAGE/usr/share/doc/cadcraft"
copy_docs "$STAGE/usr/share/doc/cadcraft"
# cadcraft-cli's man pages and shell completions, from its clap definition, written by the
# example built above. A cross build runs it through $EMULATOR, like the --version check at the
# end, and leaves them out without one, as a --skip-build run whose prebuilt binaries came without
# the example does. zsh reads site-functions on Fedora and openSUSE.
CLI_DOCS="$BIN/examples/man-and-completions"
if [[ -n "${CROSS_TARGET:-}" ]] && [[ -z "${EMULATOR:-}" ]]; then
warn "no EMULATOR to run the $CROSS_TARGET build, so cadcraft-cli's man pages and completions are left out"
elif [[ ! -x "$CLI_DOCS" ]]; then
warn "$CLI_DOCS is not built, so cadcraft-cli's man pages and completions are left out"
else
if [[ -n "${CROSS_TARGET:-}" ]]; then
"$EMULATOR" "$CLI_DOCS" "$WORK/cli-docs"
else
"$CLI_DOCS" "$WORK/cli-docs"
fi
install -Dm644 -t "$STAGE/usr/share/man/man1" "$WORK"/cli-docs/*.1
install -Dm644 "$WORK/cli-docs/cadcraft-cli.bash" "$STAGE/usr/share/bash-completion/completions/cadcraft-cli"
install -Dm644 "$WORK/cli-docs/_cadcraft-cli" "$STAGE/usr/share/zsh/site-functions/_cadcraft-cli"
install -Dm644 "$WORK/cli-docs/cadcraft-cli.fish" "$STAGE/usr/share/fish/vendor_completions.d/cadcraft-cli.fish"
fi
if command -v desktop-file-validate >/dev/null; then
desktop-file-validate "$STAGE/usr/share/applications/$APP_ID.desktop"