From b849cd47b1e4bce9f2e308fa681d8955cc9fee32 Mon Sep 17 00:00:00 2001 From: Timon Ringwald Date: Mon, 25 Jul 2022 17:55:05 +0200 Subject: [PATCH] improved README.md --- README.md | 87 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 54 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 129a6c5..2de8b4d 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,27 @@ # format -format greps lines from stdin, parses them via regex and reformats them according to a given format string +## Source code -## Input pattern +You can find the source code here: https://git.tordarus.net/Tordarus/format + +## Installation + +If you have Go installed, you can simply go install the program: `go install git.tordarus.net/Tordarus/format@latest` + +There are pre-compiled executables for various platforms on the [repository](https://git.tordarus.net/Tordarus/format/releases). + +## License + +Distributed under the MIT License. See [LICENSE.md](https://git.tordarus.net/Tordarus/format/src/branch/main/LICENSE.md) + +## Usage + +### Input pattern The input pattern describes the format in which the lines are parsed from stdin. This pattern is a regular expression according to [Go's regexp spec](https://pkg.go.dev/regexp). -Be default, the input pattern will only be applied to every single line. +By default, the input pattern will only be applied to every single line. When using multiline patterns, you can provide an amount of lines using the command line argument `-n` followed by an integer amount of lines. Use subgroups for extracting specific parts of the input line. @@ -16,13 +30,15 @@ Provide your custom input pattern with the command line argument `-i '' The default value is `^.*?$` which simply matches the whole line. -## Output pattern +### Output pattern The output pattern describes the format in which lines are generated for stdout using data from the input pattern. +Provide an output pattern via `-o ''`. + The default value is `{0}` which always matches the full input pattern -### Capturing groups +#### Capturing groups Use the `{}` syntax to use a specific capturing group. - `{0}` always matches the whole line. @@ -30,7 +46,7 @@ Use the `{}` syntax to use a specific capturing group. - `{2}` matches the second capturing group - and so on -### Formatting +#### Formatting When referencing capturing groups, you can add a specific format for some data types as well using a simplified printf syntax. @@ -41,7 +57,7 @@ See a full list of formatting options at [Go's fmt spec](https://pkg.go.dev/fmt) Currently only `%s`, `%d`, `%f` and `%g` are supported though. -### Mutators +#### Mutators Mutators are a simple way of manipulating number values like integers and floats using a simple math-like expression @@ -57,11 +73,11 @@ The following operators are supported for `%d`, `%f` and `%g` formats: It is possible to add multiple mutators by just concatenating them: `{1:%d:*2+1}`. -Multiple mutators will not follow any order of operations. They are simply applied from left to right! +**Multiple mutators will not follow any order of operations. They are simply applied from left to right!** Furthermore you can reference caputring groups which will be parsed as the same type to apply its value. This is done via the following syntax: `{1:%d:+(2)}`. It will parse the first and second capturing group into integers and adds them. -## Handling unmatched lines +### Handling unmatched lines By default, lines which do not match the input pattern will be dropped. Use `-k` to keep them unchanged. They will be copied into stdout. @@ -69,8 +85,10 @@ Use `-k` to keep them unchanged. They will be copied into stdout. ## Examples ### Copying +Copying is the default behavior of `format` + Input: -``` +```txt 1 2 3 @@ -83,7 +101,7 @@ format ``` Output: -``` +```txt 1 2 3 @@ -95,7 +113,7 @@ Output: Only keep lines which contains an `i` Input: -``` +```txt one two three @@ -114,7 +132,7 @@ format -i '.*i.*' ``` Output: -``` +```txt five six eight @@ -123,9 +141,10 @@ nine ### Removing leading zeros +Use printf syntax on a capturing group in the output pattern Input: -``` +```txt 001 002 003 @@ -138,7 +157,7 @@ format -i '\d+' -o '{0:%d}' ``` Output: -``` +```txt 1 2 3 @@ -148,7 +167,7 @@ Output: ### Extracting dates Input: -``` +```txt 2022-04-18 1970-01-01 2006-01-02 @@ -160,18 +179,17 @@ format -i '(\d{4})-(\d{2})-(\d{2})' -o 'day: {3:%d} | month: {2:%d} | year: {1}' ``` Output: -``` +```txt day: 18 | month: 4 | year: 2022 day: 1 | month: 1 | year: 1970 day: 2 | month: 1 | year: 2006 ``` ### Applying multiple formats - -Every format process can only apply a single pattern. Use `-k` to keep unmatched lines so the next format instance can apply another input pattern to them +Every `format` process can only apply a single pattern. Use `-k` to keep unmatched lines so the next `format` instance can apply another input pattern to them Input: -``` +```txt 2022-04-18 1970-01-01 02.01.2006 @@ -180,11 +198,12 @@ Input: Command: ```sh -format -i '(\d{4})-(\d{2})-(\d{2})' -o 'day: {3:%d} | month: {2:%d} | year: {1}' -k | format -i '(\d{2})\.(\d{2})\.(\d{4})' -o 'day: {1:%d} | month: {2:%d} | year: {3}' -k +format -i '(\d{4})-(\d{2})-(\d{2})' -o 'day: {3:%d} | month: {2:%d} | year: {1}' -k | +format -i '(\d{2})\.(\d{2})\.(\d{4})' -o 'day: {1:%d} | month: {2:%d} | year: {3}' -k ``` Output: -``` +```txt day: 18 | month: 4 | year: 2022 day: 1 | month: 1 | year: 1970 day: 2 | month: 1 | year: 2006 @@ -192,9 +211,10 @@ day: 2 | month: 2 | year: 1962 ``` ### Parsing multi-line patterns +Use `-n` to change the amount of lines fed into the input pattern Input: -``` +```txt year: 2022 month: 04 day: 18 @@ -215,7 +235,7 @@ format -n 3 -i '^year: (\d{4})\nmonth: (\d{2})\nday: (\d{2})$' -o 'day: {3:%d} | ``` Output: -``` +```txt day: 18 | month: 4 | year: 2022 day: 1 | month: 1 | year: 1970 day: 2 | month: 1 | year: 2006 @@ -223,9 +243,10 @@ day: 2 | month: 2 | year: 1962 ``` ### Adding 2 values together +Use mutators to apply simple arithmetic on Input: -``` +```txt 5 7 3 2 10 152 @@ -238,7 +259,7 @@ format -i '(-?\d+) (-?\d+(?:.\d+)?)' -o '{1} + {2} = {1:%g:+(2)}' ``` Output: -``` +```txt 5 + 7 = 12 3 + 2 = 5 10 + 152 = 162 @@ -247,10 +268,10 @@ Output: ### Bulk renaming files -Rename a bunch of files at once using format +Rename a bunch of files at once using `format` Output of `ls`: -``` +```txt 000.jpg 001.jpg 002.jpg @@ -262,7 +283,7 @@ ls | format -i '(\d+)\.jpg' -o 'mv "{0}" "{1:%d:+1}.jpg"' | xargs -0 sh -c ``` Output of `ls` afterwards: -``` +```txt 1.jpg 2.jpg 3.jpg @@ -291,7 +312,7 @@ There are a few things to consider using this script: Example usage of this script: Output of `ls`: -``` +```txt 000.jpg 001.jpg 002.jpg @@ -303,7 +324,7 @@ bulkrename '(\d+)\.jpg' '{1:%d:+1}.jpg' ``` Output: -``` +```txt mv "000.jpg" "1.jpg" mv "001.jpg" "2.jpg" mv "002.jpg" "3.jpg" @@ -317,8 +338,8 @@ bulkrename '(\d+)\.jpg' '{1:%d:+1}.jpg' exec ``` Output of `ls` afterwards: -``` +```txt 1.jpg 2.jpg 3.jpg -``` \ No newline at end of file +```