|
1 | 1 | //! # string_pipeline |
2 | 2 | //! |
3 | | -//! A powerful string transformation CLI tool and Rust library that makes complex text processing simple. |
4 | | -//! Transform data using intuitive **template syntax** — chain operations like **split**, **join**, **replace**, |
5 | | -//! **filter**, and **20+ others** in a single readable expression. |
| 3 | +//! A string transformation library and CLI tool for Rust. Chain operations like split, join, |
| 4 | +//! replace, and filter using template syntax. |
6 | 5 | //! |
7 | 6 | //! ## Features |
8 | 7 | //! |
9 | 8 | //! - **🔗 Chainable Operations**: Pipe operations together naturally |
10 | | -//! - **🎯 Precise Control**: Python-like ranges with Rust syntax (`-2..`, `1..=3`) |
11 | 9 | //! - **🗺️ Powerful Mapping**: Apply sub-pipelines to each list item |
12 | 10 | //! - **🔍 Regex Support**: sed-like patterns for complex transformations |
13 | | -//! - **🐛 Debug Mode**: Hierarchical operation visualization with detailed tracing |
14 | | -//! - **📥 Flexible I/O**: CLI tool + embeddable Rust library |
15 | | -//! - **🦀 Performance optimized**: Zero-copy operations where possible, efficient memory usage |
16 | | -//! - **🌍 Unicode support**: Full UTF-8 and Unicode character handling |
17 | | -//! - **🛡️ Error handling**: Comprehensive error reporting for invalid operations |
| 11 | +//! - **🐛 Debug Mode**: Step-by-step operation visualization |
18 | 12 | //! |
19 | 13 | //! ## Quick Start |
20 | 14 | //! |
|
110 | 104 | //! assert_eq!(result, "First: apple Second: banana"); |
111 | 105 | //! ``` |
112 | 106 | //! |
| 107 | +//! ## Type System |
| 108 | +//! |
| 109 | +//! The pipeline system has a clear type system that distinguishes between: |
| 110 | +//! - **String operations**: Work only on strings (e.g., `upper`, `lower`, `trim`, `replace`) |
| 111 | +//! - **List operations**: Work only on lists (e.g., `sort`, `unique`, `slice`) |
| 112 | +//! - **Type-preserving operations**: Accept both types (e.g., `filter`, `reverse`) |
| 113 | +//! - **Type-converting operations**: Change between types (e.g., `split` converts string→list, `join` converts list→string) |
| 114 | +//! |
| 115 | +//! Use `map:{operation}` to apply string operations to each item in a list. |
| 116 | +//! |
| 117 | +//! ## Structured Templates |
| 118 | +//! |
| 119 | +//! **Added in v0.13.0**: Apply multiple inputs to different template sections with individual separators. |
| 120 | +//! This enables powerful scenarios like batch processing, command construction, and data transformation. |
| 121 | +//! |
| 122 | +//! ```rust |
| 123 | +//! use string_pipeline::Template; |
| 124 | +//! |
| 125 | +//! // Multiple inputs per template section with different separators |
| 126 | +//! let template = Template::parse("Users: {upper} | Files: {lower}").unwrap(); |
| 127 | +//! let result = template.format_with_inputs(&[ |
| 128 | +//! &["john doe", "jane smith"], // Multiple users for first section |
| 129 | +//! &["FILE1.TXT", "FILE2.TXT"] // Multiple files for second section |
| 130 | +//! ], &[" ", ","]).unwrap(); // Space separator for users, comma for files |
| 131 | +//! assert_eq!(result, "Users: JOHN DOE JANE SMITH | Files: file1.txt,file2.txt"); |
| 132 | +//! |
| 133 | +//! // Template introspection |
| 134 | +//! let sections = template.get_template_sections(); // Get template section info |
| 135 | +//! assert_eq!(sections.len(), 2); // Two template sections: {strip_ansi|lower} and {} |
| 136 | +//! ``` |
| 137 | +//! |
| 138 | +//! ## Error Handling |
| 139 | +//! |
| 140 | +//! All operations return `Result<String, String>` for comprehensive error handling: |
| 141 | +//! |
| 142 | +//! ```rust |
| 143 | +//! use string_pipeline::Template; |
| 144 | +//! |
| 145 | +//! // Invalid template syntax |
| 146 | +//! let result = Template::parse("{split:}"); |
| 147 | +//! assert!(result.is_err()); |
| 148 | +//! |
| 149 | +//! // Type mismatch errors are clear and helpful |
| 150 | +//! let template = Template::parse("{sort}").unwrap(); |
| 151 | +//! let result = template.format("not_a_list"); |
| 152 | +//! assert!(result.is_err()); |
| 153 | +//! // Error: "Sort operation can only be applied to lists" |
| 154 | +//! ``` |
| 155 | +//! |
113 | 156 | //! ## Common Use Cases |
114 | 157 | //! |
115 | 158 | //! ### Basic Text Processing |
|
189 | 232 | //! assert_eq!(result, "app.py\ntest.py"); |
190 | 233 | //! ``` |
191 | 234 | //! |
192 | | -//! ## Type System |
193 | | -//! |
194 | | -//! The pipeline system has a clear type system that distinguishes between: |
195 | | -//! - **String operations**: Work only on strings (e.g., `upper`, `lower`, `trim`, `replace`) |
196 | | -//! - **List operations**: Work only on lists (e.g., `sort`, `unique`, `slice`) |
197 | | -//! - **Type-preserving operations**: Accept both types (e.g., `filter`, `reverse`) |
198 | | -//! - **Type-converting operations**: Change between types (e.g., `split` converts string→list, `join` converts list→string) |
199 | | -//! |
200 | | -//! Use `map:{operation}` to apply string operations to each item in a list. |
201 | | -//! |
202 | | -//! ## Structured Templates (Advanced) |
203 | | -//! |
204 | | -//! **NEW in v0.13.0**: Apply multiple inputs to different template sections with individual separators. |
205 | | -//! This enables powerful scenarios like batch processing, command construction, and data transformation. |
206 | | -//! |
207 | | -//! ```rust |
208 | | -//! use string_pipeline::Template; |
209 | | -//! |
210 | | -//! // Multiple inputs per template section with different separators |
211 | | -//! let template = Template::parse("Users: {upper} | Files: {lower}").unwrap(); |
212 | | -//! let result = template.format_with_inputs(&[ |
213 | | -//! &["john doe", "jane smith"], // Multiple users for first section |
214 | | -//! &["FILE1.TXT", "FILE2.TXT"] // Multiple files for second section |
215 | | -//! ], &[" ", ","]).unwrap(); // Space separator for users, comma for files |
216 | | -//! assert_eq!(result, "Users: JOHN DOE JANE SMITH | Files: file1.txt,file2.txt"); |
217 | | -//! |
218 | | -//! // Template introspection |
219 | | -//! let sections = template.get_template_sections(); // Get template section info |
220 | | -//! assert_eq!(sections.len(), 2); // Two template sections: {strip_ansi|lower} and {} |
221 | | -//! ``` |
222 | | -//! |
223 | | -//! **Key Features:** |
224 | | -//! - **🎯 Flexible Input**: Each template section can receive multiple input values |
225 | | -//! - **⚙️ Custom Separators**: Individual separator for each template section |
226 | | -//! - **🔍 Introspection**: Examine template structure before processing |
227 | | -//! - **🏗️ Batch Processing**: Perfect for processing multiple items per section |
228 | | -//! |
229 | | -//! ## Error Handling |
230 | | -//! |
231 | | -//! All operations return `Result<String, String>` for comprehensive error handling: |
232 | | -//! |
233 | | -//! ```rust |
234 | | -//! use string_pipeline::Template; |
235 | | -//! |
236 | | -//! // Invalid template syntax |
237 | | -//! let result = Template::parse("{split:}"); |
238 | | -//! assert!(result.is_err()); |
239 | | -//! |
240 | | -//! // Type mismatch errors are clear and helpful |
241 | | -//! let template = Template::parse("{sort}").unwrap(); |
242 | | -//! let result = template.format("not_a_list"); |
243 | | -//! assert!(result.is_err()); |
244 | | -//! // Error: "Sort operation can only be applied to lists" |
245 | | -//! ``` |
246 | | -//! |
247 | 235 | //! ## Performance Notes |
248 | 236 | //! |
249 | 237 | //! - Templates are compiled once and can be reused efficiently |
|
0 commit comments