milarin/format
1
0
Fork 0
Code Issues Pull Requests Projects Releases 2 Wiki Activity

improved README.md

Browse Source
This commit is contained in:
Timon Ringwald 2022-07-25 17:55:05 +02:00
parent 5bf2f81d98
commit b849cd47b1
1 changed files with 54 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

87
README.md
View File

@ -1,13 +1,27 @@
# format # 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. 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). 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. 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. 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. 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. 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 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. Use the `{<group_index>}` syntax to use a specific capturing group.
- `{0}` always matches the whole line. - `{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 - `{2}` matches the second capturing group
- and so on - 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. 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. 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 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}`. 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. 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. 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. 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 ## Examples
### Copying ### Copying
Copying is the default behavior of `format`
Input: Input:
``` ```txt
1 1
2 2
3 3
@ -83,7 +101,7 @@ format
``` ```
Output: Output:
``` ```txt
1 1
2 2
3 3
@ -95,7 +113,7 @@ Output:
Only keep lines which contains an `i` Only keep lines which contains an `i`
Input: Input:
``` ```txt
one one
two two
three three
@ -114,7 +132,7 @@ format -i '.*i.*'
``` ```
Output: Output:
``` ```txt
five five
six six
eight eight
@ -123,9 +141,10 @@ nine
### Removing leading zeros ### Removing leading zeros
Use printf syntax on a capturing group in the output pattern
Input: Input:
``` ```txt
001 001
002 002
003 003
@ -138,7 +157,7 @@ format -i '\d+' -o '{0:%d}'
``` ```
Output: Output:
``` ```txt
1 1
2 2
3 3
@ -148,7 +167,7 @@ Output:
### Extracting dates ### Extracting dates
Input: Input:
``` ```txt
2022-04-18 2022-04-18
1970-01-01 1970-01-01
2006-01-02 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: Output:
``` ```txt
day: 18 | month: 4 | year: 2022 day: 18 | month: 4 | year: 2022
day: 1 | month: 1 | year: 1970 day: 1 | month: 1 | year: 1970
day: 2 | month: 1 | year: 2006 day: 2 | month: 1 | year: 2006
``` ```
### Applying multiple formats ### 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: Input:
``` ```txt
2022-04-18 2022-04-18
1970-01-01 1970-01-01
02.01.2006 02.01.2006
@ -180,11 +198,12 @@ Input:
Command: Command:
```sh ```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: Output:
``` ```txt
day: 18 | month: 4 | year: 2022 day: 18 | month: 4 | year: 2022
day: 1 | month: 1 | year: 1970 day: 1 | month: 1 | year: 1970
day: 2 | month: 1 | year: 2006 day: 2 | month: 1 | year: 2006
@ -192,9 +211,10 @@ day: 2 | month: 2 | year: 1962
``` ```
### Parsing multi-line patterns ### Parsing multi-line patterns
Use `-n` to change the amount of lines fed into the input pattern
Input: Input:
``` ```txt
year: 2022 year: 2022
month: 04 month: 04
day: 18 day: 18
@ -215,7 +235,7 @@ format -n 3 -i '^year: (\d{4})\nmonth: (\d{2})\nday: (\d{2})$' -o 'day: {3:%d} |
``` ```
Output: Output:
``` ```txt
day: 18 | month: 4 | year: 2022 day: 18 | month: 4 | year: 2022
day: 1 | month: 1 | year: 1970 day: 1 | month: 1 | year: 1970
day: 2 | month: 1 | year: 2006 day: 2 | month: 1 | year: 2006
@ -223,9 +243,10 @@ day: 2 | month: 2 | year: 1962
``` ```
### Adding 2 values together ### Adding 2 values together
Use mutators to apply simple arithmetic on
Input: Input:
``` ```txt
5 7 5 7
3 2 3 2
10 152 10 152
@ -238,7 +259,7 @@ format -i '(-?\d+) (-?\d+(?:.\d+)?)' -o '{1} + {2} = {1:%g:+(2)}'
``` ```
Output: Output:
``` ```txt
5 + 7 = 12 5 + 7 = 12
3 + 2 = 5 3 + 2 = 5
10 + 152 = 162 10 + 152 = 162
@ -247,10 +268,10 @@ Output:
### Bulk renaming files ### Bulk renaming files
Rename a bunch of files at once using format Rename a bunch of files at once using `format`
Output of `ls`: Output of `ls`:
``` ```txt
000.jpg 000.jpg
001.jpg 001.jpg
002.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: Output of `ls` afterwards:
``` ```txt
1.jpg 1.jpg
2.jpg 2.jpg
3.jpg 3.jpg
@ -291,7 +312,7 @@ There are a few things to consider using this script:
Example usage of this script: Example usage of this script:
Output of `ls`: Output of `ls`:
``` ```txt
000.jpg 000.jpg
001.jpg 001.jpg
002.jpg 002.jpg
@ -303,7 +324,7 @@ bulkrename '(\d+)\.jpg' '{1:%d:+1}.jpg'
``` ```
Output: Output:
``` ```txt
mv "000.jpg" "1.jpg" mv "000.jpg" "1.jpg"
mv "001.jpg" "2.jpg" mv "001.jpg" "2.jpg"
mv "002.jpg" "3.jpg" mv "002.jpg" "3.jpg"
@ -317,8 +338,8 @@ bulkrename '(\d+)\.jpg' '{1:%d:+1}.jpg' exec
``` ```
Output of `ls` afterwards: Output of `ls` afterwards:
``` ```txt
1.jpg 1.jpg
2.jpg 2.jpg
3.jpg 3.jpg
``` ```