First version0.1.1

1 files changed, 223 insertions, 0 deletions

diff --git a/src/lib.rs b/src/lib.rs
new file mode 100644
index 0000000..2875c41
--- /dev/null
+++ b/src/lib.rs
@@ -0,0 +1,223 @@
+//! Progress Management Library
+//!
+//! This library provides flexible progress management functionality, supporting multi-level progress display and custom renderers.
+//!
+//! # Quick Start
+//!
+//! The following is a simple usage example demonstrating how to create a progress center, bind a renderer, and update progress for multiple concurrent tasks:
+//!
+//! ```rust
+//! use just_progress::progress;
+//! use just_progress::renderer::ProgressSimpleRenderer;
+//! use tokio::time::{sleep, Duration};
+//! use tokio::join;
+//!
+//! #[tokio::main]
+//! async fn main() {
+//!     // Initialize the progress center
+//!     let center = progress::init();
+//!     // Create a renderer and enable subprogress display
+//!     let renderer = ProgressSimpleRenderer::new().with_subprogress(true);
+//!     // Bind the renderer callback function
+//!     let bind = progress::bind(center, move |name, state| renderer.update(name, state));
+//!
+//!     // Concurrently execute progress binding and business logic
+//!     join!(bind, proc());
+//! }
+//!
+//! async fn proc() {
+//!     println!("Starting package download!");
+//!     sleep(Duration::from_millis(500)).await;
+//!
+//!     // Define multiple concurrent download tasks
+//!     let download_task = async {
+//!         for i in 1..21 {
+//!             sleep(Duration::from_millis(50)).await;
+//!             progress::update_progress("Download/Data", i as f32 * 0.05);
+//!         }
+//!     };
+//!
+//!     let extract_task = async {
+//!         for i in 1..11 {
+//!             sleep(Duration::from_millis(100)).await;
+//!             progress::update_progress("Download/Extract", i as f32 * 0.1);
+//!         }
+//!     };
+//!
+//!     let verify_sha256_task = async {
+//!         for i in 1..6 {
+//!             sleep(Duration::from_millis(300)).await;
+//!             progress::update_progress("Download/Verify/SHA256", i as f32 * 0.2);
+//!         }
+//!     };
+//!
+//!     let verify_md5_task = async {
+//!         for i in 1..6 {
+//!             sleep(Duration::from_millis(100)).await;
+//!             progress::update_progress("Download/Verify/MD5", i as f32 * 0.2);
+//!         }
+//!     };
+//!
+//!     let verify_blake3_task = async {
+//!         for i in 1..6 {
+//!             sleep(Duration::from_millis(500)).await;
+//!             progress::update_progress("Download/Verify/Blake3", i as f32 * 0.2);
+//!         }
+//!     };
+//!
+//!     // Concurrently execute all download tasks
+//!     join!(
+//!         download_task,
+//!         extract_task,
+//!         verify_sha256_task,
+//!         verify_blake3_task,
+//!         verify_md5_task
+//!     );
+//!
+//!     sleep(Duration::from_millis(500)).await;
+//!     progress::clear_all(); // Clear all progress after download completes
+//!     println!("Package download complete!");
+//!
+//!     progress::close(); // Close the progress channel, ending the program
+//! }
+//! ```
+//!
+
+/// Progress Module
+///
+/// Provides core functionality for progress management, including progress center initialization,
+/// status updates, and callback binding.
+///
+/// # Usage
+///
+/// 1. Initialize the progress center:
+/// ```rust
+/// # use just_progress::progress;
+/// let progress_center = progress::init();
+/// ```
+///
+/// 2. Bind a renderer callback:
+/// ```rust
+/// # use just_progress::progress;
+/// # use just_progress::renderer::ProgressSimpleRenderer;
+/// let center = progress::init();
+/// let renderer = ProgressSimpleRenderer::new().with_subprogress(true);
+/// let bind = progress::bind(center, move |name, state| renderer.update(name, state));
+/// // Run `bind` and business logic in an async context
+/// ```
+///
+/// 3. Update progress status:
+/// ```rust
+/// # use just_progress::progress::{self, ProgressInfo};
+/// // Update progress value
+/// progress::update_progress("download/file1", 0.5);
+///
+/// // Update status information
+/// progress::update_info("download/file1", ProgressInfo::Info("Downloading..."));
+///
+/// // Update both progress and status simultaneously
+/// progress::update("download/file1", 0.75, ProgressInfo::Warning("Slow network"));
+///
+/// // Mark as complete
+/// // Equivalent to progress::update_progress("download/file1", 1.0);
+/// progress::complete("download/file1");
+///
+/// // Clear all progress items
+/// progress::clear_all();
+///
+/// // Close the progress channel
+/// progress::close();
+/// ```
+///
+/// # Special Flags
+///
+/// The module uses two special flags internally to control the flow:
+/// - `_clear`: Clears all progress items
+/// - `_close`: Closes the binding channel, stopping callbacks
+///
+/// # Asynchronous Binding
+///
+/// The `bind` function creates an asynchronous Future that listens for progress changes and invokes the callback.
+/// The callback receives the progress name and state, making it suitable for use with renderers.
+///
+/// # Hierarchical Progress
+///
+/// Progress names can use slashes (`/`) to represent hierarchical relationships, e.g., `"parent/child"`.
+/// Renderers can leverage this structure to display indentation or calculate the average progress of parent tasks.
+///
+/// # Notes
+///
+/// - `init()` must be called before using any other functions.
+/// - The Future returned by `bind()` needs to be polled or awaited for callbacks to execute.
+/// - `clear_all()` sends a clear signal but does not immediately clear messages in the channel.
+/// - `close()` stops all `bind()` calls; progress updates are no longer possible afterward.
+///
+pub mod progress;
+
+/// Renderer Module
+///
+/// Provides the `ProgressSimpleRenderer` for displaying progress bars and status information.
+///
+/// # Usage
+///
+/// 1. Create a renderer instance:
+/// ```rust
+/// # use just_progress::renderer::ProgressSimpleRenderer;
+/// let renderer = ProgressSimpleRenderer::new();
+/// ```
+///
+/// 2. Configure the renderer (optional):
+/// ```rust
+/// # use just_progress::renderer::ProgressSimpleRenderer;
+/// # use just_progress::renderer::RendererSortingRule;
+/// let renderer = ProgressSimpleRenderer::new()
+///     .with_subprogress(true)                              // Enable subprogress
+///     .with_auto_remove_completed(true)                    // Automatically remove completed items
+///     .with_sorting(RendererSortingRule::AlphabeticalAsc); // Sort alphabetically ascending
+/// ```
+///
+/// 3. Trigger rendering:
+/// ```rust
+/// # use just_progress::renderer::ProgressSimpleRenderer;
+/// # use just_progress::renderer::RendererSortingRule;
+/// # use just_progress::progress::{ProgressState, ProgressInfo};
+/// # let renderer = ProgressSimpleRenderer::new();
+/// renderer.render_all();
+/// ```
+///
+/// # Subprogress
+///
+/// When `subprogress` is enabled, progress names can be separated by slashes (`/`) to represent hierarchical relationships:
+/// - `"parent"` - Top-level progress
+/// - `"parent/child"` - Subprogress, automatically indented when displayed
+/// - `"parent/child/grandchild"` - Deeper level progress
+///
+/// If a parent node does not have a directly corresponding progress state, the renderer will automatically calculate the average progress of its child nodes as the display value.
+///
+/// # Theme
+///
+/// Customize the rendering style via the `RendererTheme` struct:
+/// ```rust
+/// use just_progress::renderer::{RendererTheme, ProgressSimpleRenderer};
+/// let theme = RendererTheme {
+///  layout: "{name},{progress},{percent}",
+///  show_state: false,
+///  progress_content_len: 30,
+///  progress_filled_char: "█",
+///  progress_empty_char: "░",
+///  ..RendererTheme::default()
+/// };
+/// let renderer = ProgressSimpleRenderer::new().with_theme(theme);
+/// ```
+///
+/// # Layout
+///
+/// The `layout` field uses a comma-separated template string, supporting the following placeholders:
+/// - `{name}`: Progress name (supports indentation)
+/// - `{state}`: Status information (INFO/WARN/ERROR)
+/// - `{progress}`: Progress bar
+/// - `{percent}`: Percentage
+///
+/// Example: `"{name},{state},{progress},{percent}"`
+///
+pub mod renderer;