improve documentation

Author: lalvarezt

README.md

@@ -13,30 +13,46 @@ A flexible, composable string transformation CLI tool and library for Rust origi
 - **Append and prepend**: Add text before or after.
 - **Escaping**: Use `\:` and `\\` to include literal colons and backslashes in arguments.
 - **Negative indices**: Support for negative indices (like Python) in ranges and slices.
+- **Stdin support**: Read input from stdin when no input argument is provided.
 - **Tested**: Comprehensive test suite.
 
 ## Usage
 
 ### As a CLI
 
 ```sh
-cargo run -- "input string" "{template}"
+# With input argument
+cargo run -- "{template}" "input string"
+
+# With stdin input
+echo "input string" | cargo run -- "{template}"
 ```
 
 **Examples:**
 
 ```sh
 # Get the second item in a comma-separated list
-cargo run -- "a,b,c" "{split:,:1}"
+cargo run -- "{split:,:1}" "a,b,c"
+# Output: b
+
+# Using stdin
+echo "a,b,c" | cargo run -- "{split:,:1}"
 # Output: b
 
 # Replace all spaces with underscores and uppercase
-cargo run -- "foo bar baz" "{replace:s/ /_/g:upper}"
+cargo run -- "{replace:s/ /_/g:upper}" "foo bar baz"
 # Output: FOO_BAR_BAZ
 
 # Trim, split, and append
-cargo run -- " a, b,c , d , e " "{split:,:..:trim:append:!}"
+cargo run -- "{split:,:..:trim:append:!}" " a, b,c , d , e "
 # Output: a!,b!,c!,d!,e!
+
+# Using stdin for processing file content
+cat data.txt | cargo run -- "{split:\n:..:trim:prepend:- }"
+
+# Pipeline processing
+echo "hello,world,test" | cargo run -- "{split:,:0..2:join: | :upper}"
+# Output: HELLO | WORLD
 ```
 
 ### Template Syntax
@@ -67,20 +83,60 @@ To include a literal `:` or `\` in an argument, escape it as `\:` or `\\`.
 
 ```sh
 # Get the last item
-cargo run -- "a,b,c" "{split:,:-1}"
+cargo run -- "{split:,:-1}" "a,b,c"
 # Output: c
 
-# Replace 'foo' with 'bar'
-cargo run -- "foo foo" "{replace:s/foo/bar/g}"
+# Get a range of items
+cargo run -- "{split:,:1..=3}" "a,b,c,d,e"
+# Output: b,c,d
+
+# Replace 'foo' with 'bar' globally
+cargo run -- "{replace:s/foo/bar/g}" "foo foo"
 # Output: bar bar
 
-# Uppercase, then append
-cargo run -- "hello" "{upper:append:!}"
+# Chain operations: uppercase, then append
+cargo run -- "{upper:append:!}" "hello"
 # Output: HELLO!
 
 # Prepend with a colon (escaped)
-cargo run -- "bar" "{prepend:\:foo}"
+cargo run -- "{prepend:\:foo}" "bar"
 # Output: :foobar
+
+# Complex chaining: split, select range, join, replace, uppercase
+cargo run -- "{split:,:0..2:join:-:replace:s/a/X/:upper}" "a,b,c"
+# Output: X-B
+
+# Slice string characters
+cargo run -- "{slice:1..=3}" "hello"
+# Output: ell
+
+# Split, trim each item, then prepend
+echo " a , b , c " | cargo run -- "{split:,:..:trim:prepend:item_}"
+# Output: item_a,item_b,item_c
+
+# Strip custom characters
+cargo run -- "{strip:xy}" "xyhelloxy"
+# Output: hello
+```
+
+### Advanced Examples
+
+```sh
+# Process CSV-like data
+echo "name,age,city" | cargo run -- "{split:,:1..}" 
+# Output: age,city
+
+# Format file paths
+echo "/home/user/documents/file.txt" | cargo run -- "{split:/:-1:prepend:dir }"
+# Output: dir file.txt
+
+# Extract file extension
+echo "document.pdf" | cargo run -- "{split:.:-1:upper}"
+# Output: PDF
+
+# Process log entries with timestamps
+echo "2023-01-01 ERROR Failed to connect" | cargo run -- "{split: :1..:join: :lower}"
+# Output: error failed to connect
 ```
 
 ## Library Usage
@@ -100,6 +156,32 @@ use your_crate::process;
 
 let result = process("foo,bar,baz", "{split:,:1:upper}").unwrap();
 assert_eq!(result, "BAR");
+
+// Chain multiple operations
+let result = process("  hello world  ", "{trim:split: :join:_:upper}").unwrap();
+assert_eq!(result, "HELLO_WORLD");
+
+// Work with ranges
+let result = process("a,b,c,d,e", "{split:,:1..=3:join:-}").unwrap();
+assert_eq!(result, "b-c-d");
+```
+
+## Error Handling
+
+The tool provides helpful error messages for common issues:
+
+```sh
+# Invalid template format
+cargo run -- "split:,:0" "test"
+# Error: Template must start with '{' and end with '}'
+
+# Invalid range
+cargo run -- "{split:,:abc}" "a,b,c"  
+# Error: Invalid index
+
+# Invalid regex
+cargo run -- "{replace:s/[/replacement/}" "test"
+# Error: regex parse error
 ```
 
 ## Running Tests
@@ -108,6 +190,14 @@ assert_eq!(result, "BAR");
 cargo test
 ```
 
+## Use Cases
+
+- **Data extraction**: Parse CSV, logs, or structured text
+- **Text transformation**: Clean and format strings in pipelines
+- **File processing**: Extract parts of filenames or paths
+- **Configuration parsing**: Process environment variables or config files
+- **Shell scripting**: Quick text manipulation in scripts
+
 ## License
 
 MIT