commit 043958adad2a2297e0f824f105a902acb39599d8
parent b50429aadb6bd9b127f013d49029e31a378cbbe3
Author: Friedel Schön <[email protected]>
Date: Wed, 7 Aug 2024 00:33:23 +0200
update readme and man-page
Diffstat:
| M | README.md | | | 103 | ++++++++++++++++++++++++++++--------------------------------------------------- |
| M | textselect.1 | | | 69 | ++++++++++++++++++++++++++++++++++++++------------------------------- |
2 files changed, 74 insertions(+), 98 deletions(-)
diff --git a/README.md b/README.md
@@ -1,98 +1,67 @@
# textselect
-`textselect` is a command-line utility for interactively selecting lines from a text file using an ncurses interface. Selected lines can be saved to a file or passed as arguments to a command.
+`textselect` is a command-line utility that allows users to interactively select lines from a text file and optionally execute a command with the selected lines. This can be particularly useful for filtering input before processing it with other tools or scripts.
## Features
-- **Interactive Selection**: Navigate through lines of a text file and select or deselect lines using an ncurses interface.
-- **Customizable Output**: Save selected lines to a file or pass them as arguments to another command.
-- **Invert Selection**: Toggle the inversion of selection to easily change which lines are selected.
-- **Use with `xargs`**: Pass selected lines as arguments to a command.
+- Interactively select lines from a text file using a curses-based interface.
+- Save selected lines to an output file.
+- Execute commands with the selected lines as arguments.
+- Flexible options for command execution, including passing selected lines as arguments, replacing placeholders in commands, or executing commands for each selected line.
## Installation
-To build and install `textselect`, follow these steps:
+To build `textselect` from source, you'll need a C compiler and the `ncurses` library. Clone the repository and run the following commands:
-1. **Clone the Repository**:
-
- ```sh
- git clone https://github.com/friedelschoen/textselect
- cd textselect
- ```
-
-2. **Compile the Program**:
-
- ```sh
- make
- ```
-
-3. **Install the Program** (optional):
-
- ```sh
- sudo make install
- ```
+```sh
+git clone https://github.com/friedelschoen/textselect.git
+cd textselect
+make
+```
## Usage
```sh
-textselect [-hvx] [-o output] <input> [command [args...]]
+textselect [-hvxil] [-o output] <input> [command [args...]]
```
### Options
-- `-h`
- Display help information and exit.
-
-- `-v`
- Invert the selection of lines.
-
-- `-x`
- Pass the selected lines as arguments to the specified command.
-
-- `-o output`
- Specify an output file to save the selected lines. If not specified, the selected lines are printed to stdout.
+- `-h`: Display the help message and exit.
+- `-v`: Invert the selection of lines.
+- `-x`: Call command with selected lines as arguments (mutually exclusive with `-i` and `-l`).
+- `-i`: Replace occurrences of `{}` in the command with each selected line, one at a time (mutually exclusive with `-x` and `-l`).
+- `-l`: Execute the command once for each selected line (mutually exclusive with `-x` and `-i`).
+- `-o output`: Specify an output file to save the selected lines.
### Navigation and Selection Keys
-- `UP`, `LEFT`
- Move the cursor up.
-
-- `DOWN`, `RIGHT`
- Move the cursor down.
-
-- `v`
- Invert the selection of lines.
-
-- `SPACE`
- Select or deselect the current line.
-
-- `ENTER`, `q`
- Quit the selection interface.
+- `UP, LEFT`: Move the cursor up.
+- `DOWN, RIGHT`: Move the cursor down.
+- `v`: Invert the selection of lines.
+- `SPACE`: Select or deselect the current line.
+- `ENTER, q`: Quit the selection interface.
### Examples
-- **Select lines from `input.txt` and save them to `output.txt`**:
+```sh
+# Interactively select lines from input.txt and save the selected lines to output.txt
+textselect -o output.txt input.txt
- ```sh
- textselect -o output.txt input.txt
- ```
+# Interactively select lines from input.txt and pass the selected lines as arguments to the sort command
+textselect input.txt sort
-- **Select lines from `input.txt` and pass them as arguments to the `sort` command**:
+# Interactively select lines from input.txt and execute the echo command for each selected line, replacing {} with the selected line
+textselect -i input.txt echo {}
- ```sh
- textselect input.txt sort
- ```
+# Interactively select lines from input.txt and execute the echo command for each selected line
+textselect -l input.txt echo
+```
-- **Select lines from `input.txt` and pass them as arguments to a command using `xargs`**:
+## License
- ```sh
- textselect -x input.txt ls
- ```
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
## Contributing
-Contributions are welcome! Please open an issue or submit a pull request with any improvements or fixes.
-
-## License
-
-`textselect` is licensed under the Zlib License. See the [LICENSE](LICENSE) file for details.
+Contributions are welcome! Please open an issue or submit a pull request on GitHub.
diff --git a/textselect.1 b/textselect.1
@@ -1,38 +1,40 @@
-.TH TEXTSELECT 1 "August 2024" "1.0" "Text Selection Utility"
+.TH textselect 1 "2024-08-07" "textselect 0.1" "User Commands"
.SH NAME
-textselect \- interactively select lines from a text file and optionally execute a command with the selected lines
-
+textselect \- Interactively select lines from a text file and optionally execute a command with the selected lines.
.SH SYNOPSIS
.B textselect
-.RI [ options ] " <input> [command [args...]]"
-
+.RB [ \-hvx ]
+.RB [ \-o \ output ]
+.I input
+.I [command [args...]]
.SH DESCRIPTION
.B textselect
-is a utility that allows users to interactively select lines from a text file using an ncurses interface. The selected lines can then be saved to an output file or passed as input to another command.
-
+allows users to interactively select lines from a text file. The selected lines can be saved to an output file or passed to a command for execution.
.SH OPTIONS
.TP
.B \-h
-Display usage information and exit.
+Display this help message and exit.
.TP
.B \-v
Invert the selection of lines.
.TP
.B \-x
-Call command with lines as arguments.
+Call command with selected lines as arguments (mutually exclusive with \-i and \-l).
.TP
-.B \-o \fIoutput\fP
-Specify an output file to save the selected lines. If not specified, the selected lines are printed to stdout.
-
-.SH USAGE
-The program reads the input file line by line, displaying the lines in a scrollable ncurses window. Users can navigate through the lines and select or deselect lines using the keyboard.
-
-Navigation and selection keys:
+.B \-i
+Replace occurrences of \fB{}\fR in the command with each selected line, one at a time (mutually exclusive with \-x and \-l).
+.TP
+.B \-l
+Execute the command once for each selected line (mutually exclusive with \-x and \-i).
+.TP
+.B \-o \fIoutput\fR
+Specify an output file to save the selected lines.
+.SH NAVIGATION AND SELECTION KEYS
.TP
-.B KEY_UP
+.B UP, LEFT
Move the cursor up.
.TP
-.B KEY_DOWN
+.B DOWN, RIGHT
Move the cursor down.
.TP
.B v
@@ -41,20 +43,26 @@ Invert the selection of lines.
.B SPACE
Select or deselect the current line.
.TP
-.B q
+.B ENTER, q
Quit the selection interface.
-
-If a command and its arguments are specified, the selected lines are passed as input to the command. Otherwise, the selected lines are saved to the specified output file or printed to stdout.
-
.SH EXAMPLES
.TP
-Select lines from "input.txt" and save them to "output.txt":
-.B
-textselect \-o output.txt input.txt
+.B textselect \-o output.txt input.txt
+Interactively select lines from \fIinput.txt\fR and save the selected lines to \fIoutput.txt\fR.
.TP
-Select lines from "input.txt" and pass them as input to the "sort" command:
-.B
-textselect input.txt sort
-
+.B textselect input.txt sort
+Interactively select lines from \fIinput.txt\fR and pass the selected lines as arguments to the \fBsort\fR command.
+.TP
+.B textselect \-i input.txt echo \{\}
+Interactively select lines from \fIinput.txt\fR and execute the \fBecho\fR command for each selected line, replacing \{\} with the selected line.
+.TP
+.B textselect \-l input.txt echo
+Interactively select lines from \fIinput.txt\fR and execute the \fBecho\fR command for each selected line.
+.SH SEE ALSO
+.BR sort (1),
+.BR echo (1)
.SH AUTHOR
-Written by Friedel Schon.
-\ No newline at end of file
+Written by Friedel Schon.
+.SH BUGS
+Issue bugs at https://github.com/friedelschoen/textselect.
+
