Cleanup documentation and examples

README.md

@@ -79,6 +79,39 @@ Use the `cargo run --bin` command to list possible examples, and run them.
 
 We do this because it allows us to have different dependencies between examples.
 
+### Specific example docs
+
+#### `chirpunk`
+
+A clone of the cyberpunk 2077 main menu and settings menu.
+
+Demonstrates full end-to-end usage of `.chirp`, including common patterns for
+managining complexity.
+
+This example requires additional steps to work properly.
+
+Check the [example's README](./examples/chirpunk/) for more details.
+
+#### `simple_menu`
+
+A single menu made using `cuicui_dsl`.
+
+#### `dsl_and_chirp`
+
+Demonstrates the equivalence between the `dsl!` macro and the `.chirp` file
+format. Also used as a test to make sure it is trully equivalent.
+
+#### `sprite_debug`
+
+Demonstrates usage of `cuicui_layout_bevy_sprite`. Due to a quirk in the way
+cargo resolves workspace features, the debug overlay is specifically broken for
+this. You need to use the following command line to run it with the layout debug
+overlay:
+
+```sh
+cargo run --bin sprite_debug -p sprite_debug --features cuicui_layout/debug
+```
+
 ## Stability
 
 This crate is in expansion, use at your own risk, it is extremely likely that
@@ -94,6 +127,8 @@ First, chose which crate you want to use:
   [`cuicui_layout_bevy_sprite`] is for you.
 - Using a custom renderer or want your UI to be part of the 3D environment?
   Build on top of [`cuicui_layout`] itself then.
+- Are you making a complex menu requiring a lot of iterations? Consider using
+  [`cuicui_chirp`] and the `.chirp` file format!
 
 Secondly, add your chosen integration crate to your `Cargo.toml`:
 
@@ -172,11 +207,59 @@ Also check the [`cuicui_dsl`] crate documentation for details on the
 `DslBundle` trait (the trait providing the `node` and `insert` methods)
 and the `IntoEntityCommands` trait (for the `to_cmds` method).
 
+### What's that `.chirp` file format?
+
+See the [`cuicui_chirp` crate README](./chirp).
+
+#### How do I use `.chirp` files?
+
+Reproducing the previous example with `.chirp` files:
+
+First, write the chirp file:
+
+```ron
+// file: <scene.chirp>
+// Use screen_root to follow the screen's boundaries
+row(screen_root) {
+    row(margin 9, border(5, cyan), bg navy) {
+        spawn(text "Hello world!");
+    }
+}
+```
+
+Second, add the plugin and load the chirp file:
+
+```rust,no_run
+use bevy::prelude::*;
+use cuicui_layout::{dsl, LayoutRootCamera, dsl_functions::*};
+use cuicui_layout_bevy_ui::UiDsl;
+use cuicui_chirp::Chirp;
+
+fn main() {
+    // Do not forget to add cuicui_layout_bevy_{ui,sprite}::Plugin
+    // and cuicui_chirp::loader::Plugin with the wanted DSL as type parameter
+    App::new().add_plugins((
+        DefaultPlugins,
+        cuicui_layout_bevy_ui::Plugin,
+        cuicui_chirp::loader::Plugin::new::<UiDsl>(),
+    ))
+        .add_systems(Startup, setup)
+        .run();
+}
+fn setup(mut commands: Commands, assets: Res<AssetServer>) {
+    commands.spawn((Camera2dBundle::default(), LayoutRootCamera));
+    // Spawn the chirp scene as is. Yeah that's it.
+    commands.spawn(assets.load::<Chirp, _>("scene.chirp"));
+}
+```
+
 [`cuicui_layout_bevy_sprite`]: https://lib.rs/crates/cuicui_layout_bevy_sprite
 [`cuicui_layout_bevy_ui`]: https://lib.rs/crates/cuicui_layout_bevy_ui
 [`cuicui_layout`]: https://lib.rs/crates/cuicui_layout
 [`cuicui_dsl`]: https://lib.rs/crates/cuicui_dsl
+[`cuicui_chirp`]: https://lib.rs/crates/cuicui_chirp
 [`LayoutDsl`]: https://docs.rs/cuicui_layout/latest/cuicui_layout/dsl/struct.LayoutDsl.html
+[`ReflectDsl`]: https://docs.rs/cuicui_chirp/latest/cuicui_chirp/reflect/struct.ReflectDsl.html
 [`dsl!`]: https://docs.rs/cuicui_dsl/latest/cuicui_dsl/macro.dsl.html
 
 ## `cuicui_layout` crates
@@ -231,6 +314,7 @@ This repository contains several crates:
   why things do not turn out as expected.
 - `cuicui_layout`'s algo runs in `O(n)` where `n` is how many nodes you have.
 - An extensive debugging overlay.
+- Working hot reloading.
 
 ## Why not Flexbox
 

chirp/README.md

@@ -3,19 +3,84 @@
 | **❗ A syntax overall is expected in 0.10.0!!! Beware ❗** |
 |------------------------------------------------------------|
 
-This is a [`cuicui_dsl`] companion crate.
+The `.chirp` file format is a **general bevy scene text file format**. It was
+designed to look as close as possible to the [`dsl!`] macro from `cuicui_dsl`.
 
-It provides a trait to enable defining `cuicui_dsl` UI trees outside of rust,
-in an independent file format.
+It just so happen that all `cuicui` crates are compatible with `.chirp` files.
 
 It is a custom file format. The parser is written using `winnow` and directly
 interprets the bits.
 
 It provides a bevy `Plugin` to load `.chirp` files with the `AssetServer` as
 scenes.
 
+### Usage
+
+First, write the chirp file:
+
+```ron
+// file: <scene.chirp>
+// Use screen_root to follow the screen's boundaries
+row(screen_root) {
+    row(margin 9, border(5, cyan), bg navy) {
+        spawn(text "Hello world!");
+    }
+}
+```
+Second, add the plugin and load the chirp file:
+```rust,no_run
+use bevy::prelude::*;
+use cuicui_dsl::BaseDsl;
+use cuicui_chirp::Chirp;
+
+fn main() {
+    // Do not forget to add cuicui_layout_bevy_{ui,sprite}::Plugin
+    // and cuicui_chirp::loader::Plugin with the wanted DSL as type parameter
+    App::new().add_plugins((
+        DefaultPlugins,
+        cuicui_chirp::loader::Plugin::new::<BaseDsl>(),
+    ))
+        .add_systems(Startup, setup)
+        .run();
+}
+fn setup(mut commands: Commands, assets: Res<AssetServer>) {
+    // commands.spawn((Camera2dBundle::default(), LayoutRootCamera));
+    // Spawn the chirp scene as is. Yeah that's it.
+    commands.spawn(assets.load::<Chirp, _>("scene.chirp"));
+}
+```
+
+See the `cuicui_layout` repository root README for more details.
+
+### Differences with the `dsl!` macro
+
+- It can be hot reloaded, and scenes are cleaned up and reloaded properly, unlike rust code.
+- It supports an additional feature: [`ReflectDsl`]. It implements `ParseDsl`
+  based on a `Reflect + Bundle` type. No such thing is possible with the `dsl!`
+  macro.
+- `.chirp` files support arbitrary syntax. For example, we use [`css-color`]
+  to parse colors.
+- As a separate file format, chirp files are not written within rust code
+- It can't directly inline rust code as in the `dsl!` macro
+- It requires implementing an additional trait on your `DslBundle`. The trait
+  in question is `ParseDsl`. You may use `parse_dsl_impl` to make this easy.
+- It requires loading assets synchronously, using `FileAssetIo`.
+
+Both crates are not mutually exclusive.
+You can prototype with a `.chirp` file, then copy the chirp content
+into a `dsl!` macro. This is how the `chirpunk` example was built.
+
 ## Features
 
 * **`macros`** (default): Define the `parse_dsl_impl` macro. If you are not using
   the proc macro and defining `ParseDsl` implementations manually, you can
   disable this feature for faster compile times.
+* **`load_font`** and **`load_image`** (default): Enable loading `Font` and `Image`
+  assets from `.chirp` files. Disable those features if you are not using `Font`s
+  or `Image`s
+* **`fancy_errors`** (default): Show position in source code when failing to parse
+  `.chirp` files.
+
+[`css-color`]: https://lib.rs/crates/css-color
+[`ReflectDsl`]: https://docs.rs/cuicui_chirp/latest/cuicui_chirp/reflect/struct.ReflectDsl.html
+[`dsl!`]: https://docs.rs/cuicui_dsl/latest/cuicui_dsl/macro.dsl.html

examples/chirpunk/README.md

@@ -22,7 +22,7 @@ The idea is to clone the bevy-lunex cyberpunk example and re-use its `asset`
 directory.
 
 If `make` is not an option for you, the following shell commands _should work_,
-although it has only been proved to work on my machine™.
+although it has only been proven to work on my machine™.
 
 ```sh
 # First Make sure that your working directory (PWD) is the cuicui_layout workspace root.
@@ -63,7 +63,7 @@ And use `--features advanced_logging` to log more stuff.
 
 - Uses `bevy_ui` (through `cuicui_layout_bevy_ui`):
   - Bloom doesn't work on UI
-  - Requires a patches version of bevy for hot reloading to work (see the
+  - **Requires a patches version of bevy for hot reloading** to work (see the
     repository's workspace `Cargo.toml`)
 - Missing cuicui features:
   - A "all overlapping" `Distribution` mode, to replace some of the `MenuSwatch`

examples/parse_dsl_macro/Cargo.toml → examples/dsl_and_chirp/Cargo.toml

@@ -1,13 +1,13 @@
 [package]
-name = "parse_dsl_macro"
-description = "Shows usage of the ParseDslImpl macro from cuicui_format"
+name = "dsl_and_chirp"
+description = "Demonstrate equivalence between cuicui_chirp and cuicui_dsl"
 version = "0.1.0"
 edition.workspace = true
 license.workspace = true
 publish = false
 
 [[bin]]
-name = "parse_dsl_macro"
+name = "dsl_and_chirp"
 path = "main.rs"
 
 [dependencies]

examples/bevypunk/Cargo.toml → examples/simple_menu/Cargo.toml

@@ -1,13 +1,13 @@
 [package]
-name = "bevypunk"
-description = "Show extents of containers for bevy_ui cuicui_layout adaptor"
+name = "simple_menu"
+description = "How to build a simple single-screen menu using cuicui_dsl"
 version = "0.1.0"
 edition.workspace = true
 license.workspace = true
 publish = false
 
 [[bin]]
-name = "bevypunk"
+name = "simple_menu"
 path = "main.rs"
 
 [dependencies]

examples/sprite_debug/main.rs

@@ -13,9 +13,8 @@ use bevy::{
     sprite::MaterialMesh2dBundle,
 };
 use cuicui_dsl::dsl;
-use cuicui_layout::{
-    dsl::IntoUiBundle, dsl_functions::*, ComputeLayoutSet, LayoutRect, Node, Root, Size,
-};
+use cuicui_layout::dsl_functions::*;
+use cuicui_layout::{dsl::IntoUiBundle, ComputeLayoutSet, LayoutRect, Node, Root, Size};
 use cuicui_layout_bevy_sprite as render;
 use cuicui_layout_bevy_sprite::SpriteDsl as Dsl;