1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
//! A crate for representing and creating Rust type definitions as values,
//! i. e. a subset of the Rust abstract syntax.
//! Camo is a library for converting Rust type definitions into corresponding definitions in other languages.
//!
//! - **Abstract syntax tree** - Camo provides a collection of data structures that describe a subset of the Rust syntax. The syntax tree is rooted in [`core::Container`], which types provide via the [`core::Camo`] trait.
//!
//! - **Derive macro** - The [`derive::Camo`] derive macro automates the work of creating the syntax tree for your type. The macro takes `serde` attributes into account, ensuring that generated types accurately describe the values that `serde` would produce.
//!
//! - **TypeScript backend** - The [`typescript`] module provides a ready-to-use TypeScript backend. Convert a [`core::Container`] into a [`typescript::Definition`], and write it to a file.
//!
//! ---
//!
//! ## Getting started
//!
//! Add Camo as a dependency:
//!
//! ```sh
//! # `derive` is included by default
//! cargo add camo
//! # optionally add the typescript backend
//! cargo add camo --features typescript
//! ```
//!
//! Add the `Camo` derive macro to your type, and use
//! the generated `Camo::camo()` implementation:
//!
//! ```rust
//! use camo::Camo;
//!
//! #[derive(Camo)]
//! enum BindingType {
//! Paperback,
//! Hardcover,
//! }
//!
//! #[derive(Camo)]
//! struct Book {
//! title: String,
//! author: String,
//! page_count: usize,
//! chapters: Vec<String>,
//! binding: BindingType,
//! }
//!
//!
//! let book = Book::camo();
//! println!("{:?}", book);
//!
//! let binding = BindingType::camo();
//! println!("{:?}", binding);
//! ```
//!
//! With the `typescript` feature enabled, create a TypeScript definition:
//!
//! ```rust
//! use camo::{
//! Camo,
//! /* ... */
//! typescript::Definition,
//! };
//! #
//! # #[derive(Camo)]
//! # enum BindingType {
//! # Paperback,
//! # Hardcover,
//! # }
//! #
//! # #[derive(Camo)]
//! # struct Book {
//! # title: String,
//! # author: String,
//! # page_count: usize,
//! # chapters: Vec<String>,
//! # binding: BindingType,
//! # }
//! #
//! # let book = Book::camo();
//! # let binding = BindingType::camo();
//! /* ... */
//!
//! let book: Definition = book.into();
//! assert_eq!(
//! book.to_string(),
//! unindent::unindent("
//! interface Book {
//! title: string;
//! author: string;
//! page_count: number;
//! chapters: string[];
//! binding: BindingType;
//! }
//! ")
//! );
//!
//! let binding: Definition = binding.into();
//! assert_eq!(
//! binding.to_string(),
//! unindent::unindent(r#"
//! type BindingType =
//! | "Paperback"
//! | "Hardcover";
//! "#)
//! );
//! ```
//!
//! See more examples [here][github-link-examples].
//!
//! ## Features
//!
//! | Feature | Default | Description |
//! | ------------ | ------- | ----------- |
//! | `derive` | Yes | Enables the [`derive::Camo`] derive macro. |
//! | `typescript` | No | Enables the TypeScript backend, rooted in [`typescript::Definition`]. |
//!
//!
//! [cratesio-link-camo]: https://crates.io/crates/camo
//! [cratesio-link-camo-core]: https://crates.io/crates/camo-core
//! [cratesio-link-camo-derive]: https://crates.io/crates/camo-derive
//! [cratesio-link-camo-typescript]: https://crates.io/crates/camo-typescript
//! [cratesio-badge-camo]: https://img.shields.io/crates/v/camo?label=docs&style=for-the-badge&logo=rust
//!
//! [github-link-examples]: https://github.com/philipahlberg/camo/tree/main/examples
//!
//! [`core::Container`]: https://docs.rs/camo/0/core/struct.Container.html
//! [`core::Camo`]: https://docs.rs/camo/0/core/trait.Camo.html
//! [`derive::Camo`]: https://docs.rs/camo/0/derive/macro.Camo.html
//! [`typescript`]: https://docs.rs/camo/0/typescript/index.html
//! [`typescript::Definition`]: https://docs.rs/camo/0/typescript/enum.Definition.html
/// The data structures used to construct abstract syntax trees for types.
pub use camo_core as core;
pub use Camo;
/// The `Camo` derive macro, enabled by the `derive` feature.
pub use Camo;
/// The TypeScript backend, enabled by the `typescript` feature.
pub use camo_typescript as typescript;