From b849cd47b1e4bce9f2e308fa681d8955cc9fee32 Mon Sep 17 00:00:00 2001
From: Timon Ringwald <timon.ringwald@mequen.de>
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 '<pattern>'
 
 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 '<pattern>'`.
+
 The default value is `{0}` which always matches the full input pattern
 
-### Capturing groups
+#### Capturing groups
 
 Use the `{<group_index>}` syntax to use a specific capturing group.
 - `{0}` always matches the whole line.
@@ -30,7 +46,7 @@ Use the `{<group_index>}` 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
+```