From 4a6376a331c46e67aa2d27e3b2922949765ec5eb Mon Sep 17 00:00:00 2001
From: catatsuy <catatsuy@catatsuy.org>
Date: Sun, 31 Mar 2024 15:59:24 +0900
Subject: [PATCH] Update Purl CLI options for clarity and consistency

---
 README.md  | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 cli/cli.go | 12 +++++------
 2 files changed, 63 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index a81572a..971e4fe 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,58 @@
-# Purl: Streamlining Text Processing
+# Purl
 
-Purl is inspired by a knitting action and the sound of water. 'Purl' in knitting is doing the same thing over and over to make a pattern. The sound of a stream is also a steady flow. This tool, Purl, helps you change text easily, similar to Perl one-liners, but smoothly. It does tasks again and again inside, making working with text easy and smooth.
+Purl is a versatile text processing tool designed to easily and efficiently modify and replace text in files or from standard input. Inspired by the action of purling in knitting and the sound of a flowing stream, "Purl" symbolizes the concept of seamless repetition and smooth progress. Just as purling creates a fabric through consistent patterns and the stream's flow produces a calming rhythm, Purl facilitates effortless and repeated transformations of text. Aimed at providing the smoothness and efficiency of Perl one-liners, it is perfect for those looking for a tool to handle text processing tasks with ease and precision.
+
+## Features
+
+- **Auto Color Output by Default**: Purl automatically decides whether to colorize output based on the environment, enhancing readability. This auto-color feature aims to provide optimal visibility under various conditions without manual intervention.
+
+- **Overwrite Option**: By specifying the `-overwrite` option, you can direct Purl to apply changes directly to the files. This functionality is not enabled by default to allow full control over when and how files are modified.
+
+- **Flexible Input Options**: Purl accepts input either directly from specified files on the command line or through standard input, catering to a wide array of workflows and preferences.
+
+## Options
+
+- **`-overwrite`**: Use this option to enable Purl to overwrite the original files with the modified content. Without this option, Purl will display the results to standard output, leaving the original files unchanged.
+- **`-replace`**: This option requires a replacement expression to specify the text you intend to change. Format your command as "@search@replace@", with "search" being the text to find and "replace" the text to insert.
+- **`-color`** and **`-no-color`**: By default, Purl's output colorization is set to auto, determining the best mode based on your environment. Use `-no-color` if you prefer the output without colorization, regardless of the environment.
+- **`-help`**: Display information about Purl and its various options.
+
+## Usage Examples
+
+### Preview Changes Before Applying
+
+```bash
+purl -replace "@search@replace@" yourfile.txt
+```
+
+This command searches for "search" in `yourfile.txt`, shows how it would be replaced with "replace", but does not modify the file itself.
+
+### Directly Modify Files
+
+```bash
+purl -overwrite -replace "@search@replace@" yourfile.txt
+```
+
+Using the `-overwrite` option, Purl will replace "search" with "replace" in `yourfile.txt` and save the changes to the file.
+
+### Using Standard Input
+
+Purl can also process input piped from other commands, offering flexibility in how it's used:
+
+```bash
+cat yourfile.txt | purl -replace "@search@replace@"
+```
+
+This feeds the content of `yourfile.txt` into Purl, which processes and displays the modified text according to the specified replacement pattern.
+
+### Advanced Usage with Git Grep and Xargs
+
+For users looking to apply replacements across multiple files in a Git repository:
+
+```bash
+git grep -l 'search_pattern' | xargs purl -overwrite -replace "@search_pattern@replace_text@"
+```
+
+This sequence finds all files containing 'search_pattern', then uses Purl to replace it with 'replace_text', directly modifying the files where the changes are applied.
+
+Purl is crafted to offer simplicity for quick tasks as well as the capability to perform complex text processing, embodying the spirit of its name in every action it performs.
diff --git a/cli/cli.go b/cli/cli.go
index 76d96d7..31567ed 100644
--- a/cli/cli.go
+++ b/cli/cli.go
@@ -143,12 +143,12 @@ func (c *CLI) parseFlags(args []string) (*flag.FlagSet, error) {
 
 	var noColor bool
 
-	flags.BoolVar(&c.isOverwrite, "overwrite", false, "overwrite the file in place")
-	flags.StringVar(&c.replaceExpr, "replace", "", `Replacement expression, e.g., "@search@replace@"`)
-	flags.Var(&c.filters, "filter", `filter expression`)
-	flags.Var(&c.excludes, "exclude", `exclude expression`)
-	flags.BoolVar(&c.color, "color", false, `Colorize output`)
-	flags.BoolVar(&noColor, "no-color", false, `Disable colorize output`)
+	flags.BoolVar(&c.isOverwrite, "overwrite", false, "Replace original file with results.")
+	flags.StringVar(&c.replaceExpr, "replace", "", "Format: '@match@replacement@'.")
+	flags.Var(&c.filters, "filter", "Apply search refinement.")
+	flags.Var(&c.excludes, "exclude", "Exclude lines matching regex.")
+	flags.BoolVar(&c.color, "color", false, "Colored output. Default auto.")
+	flags.BoolVar(&noColor, "no-color", false, "Disable colored output.")
 	flags.BoolVar(&c.help, "help", false, `Show help`)
 
 	flags.Usage = func() {