compose_yml/
lib.rs

1//! Support for reading and writing `docker-compose.yml` files.
2//!
3//! The `docker-compose.yml` format is suprisingly complex, with support
4//! for multiple ways of representing the same data.  This library attemps
5//! to provide a single, consistent and type-safe representation of
6//! everything found in a [`docker-compose.yml` version 2 file][dcv2].
7//!
8//! Here's an example of one property, `build`, being represented in two
9//! different ways, and how we normalize it:
10//!
11//! ```
12//! use std::str::FromStr;
13//! use compose_yml::v2 as dc;
14//!
15//! let yaml = r#"---
16//!
17//! version: "2"
18//! services:
19//!   app1:
20//!     build:
21//!       context: "./app1"
22//!       dockerfile: "Dockerfile-alt"
23//!
24//!   app2:
25//!     build: "./app2"
26//!
27//! "#;
28//!
29//! let file = dc::File::from_str(yaml).unwrap();
30//!
31//! let app1 = file.services.get("app1").unwrap();
32//! let build1 = app1.build.as_ref().unwrap();
33//! assert_eq!(build1.context, dc::value(dc::Context::new("./app1")));
34//! assert_eq!(build1.dockerfile.as_ref().unwrap(),
35//!            &dc::value("Dockerfile-alt".to_owned()));
36//!
37//! // We automatically convert all different `build:` syntaxes
38//! // to be consistent.
39//! let app2 = file.services.get("app2").unwrap();
40//! let build2 = app2.build.as_ref().unwrap();
41//! assert_eq!(build2.context, dc::value(dc::Context::new("./app2")));
42//! ```
43//!
44//! An interesting place to start browsing this documentation is
45//! `docker_compose::v2::Service`.  You can drill down into other fields
46//! from there.
47//!
48//! [dcv2]: https://docs.docker.com/compose/compose-file/
49
50// Enable as many useful Rust and Clippy warnings as we can stand.  We'd
51// also enable `trivial_casts`, but we're waiting for
52// https://github.com/rust-lang/rust/issues/23416.
53#![warn(
54    missing_copy_implementations,
55    missing_debug_implementations,
56    missing_docs,
57    trivial_numeric_casts,
58    unsafe_code,
59    unused_extern_crates,
60    unused_import_braces,
61    clippy::all
62)]
63
64pub mod errors;
65pub mod v2;