We define these as string interpolations rules:

#. We write a *set* rule for the currency signs: "{{set data='£$¥€'}}"
#. We write a *counter* rule to count from 0 to 9: "{{counter min=0 max=9}}"
#. We create a file named 'friends.txt' with all the characters. Then we create a *file* rule as follows: "{{file filename='friends.txt'}}"

We put all these together as one string and execute it using Police:

$ police "{{file filename='friends.txt'}}{{counter min=0 max=9}}{{set data='£$¥€'}}"

Which should generate the following output::

Rachel0£
Monica0£
Phoebe0£
. . .
Joey9€
Chandler9€
Gunther9€

You may now use these candidates with a password recovery tool to find your lost password in no time.

Installing
----------

To install Interpol, first install golang then run this:

go install github.com/avahidi/interpol@latest

If you are interested in Police, this is what you want instead:

go install github.com/avahidi/interpol/cmd/police@latest

Documentation
-------------

In our example above the rules were defined as expressions embedded in a string.
Evaluating expressions within strings is often called *string interpolation*,
hence we have chosen to call each rule fragment an "interpolation" and the logic behind it an "interpolator".

An interpolation has the following syntax::

{{type parameter1=value1 parameter2=value2 ... }}

For example::

{{counter min=1 max=10 step=3}}

Interpolators
~~~~~~~~~~~~~

The following interpolators are currently available::

{{counter [min=0] [max=10] [step=1] [format="%d] }}
{{random [min=0] [max=100] [count=5] [format="%d"] }}
{{file filename="somefile" [count=-1] [mode=linear] [optional=false] }}
{{set data="some input" [sep=""] [count=-1] [mode=linear] [optional=false] }}
{{copy from="others-name" }}

Where

#. [parameter=value] indicates an optional parameter, value is the default value
#. valid values for mode are: linear, random or perm
#. format is standard Go fmt.Printf() format string (which is fairly similar to C format strings)
#. optional means the output is optional (i.e. it may be empty).
#. copy repeats the value of another interpolation (see below)

Copying
~~~~~~~

Interpolators may be given a name. This is needed when using copy:

"{{counter name=mycounter}} {{copy from=mycounter}}"

This will yield "0 0", "1 1", and so on.

Modifiers
~~~~~~~~~

Interpolators can also have an output *modifier*.
Currently the following modifiers exist:

- *empty*: the empty string "" (ignores input)
- *len*: length of the input (in raw bytes, no fancy UTF-8 support)
- *bitflip*: randomly flip one bit (again, using raw bytes)
- *byteswap*: randomly swap two bytes (raw bytes again)
- *reverse*: reverse (for once, this one supports UTF-8)
- *trim*: trim text (remove space before and after)
- *base64*: base64 encode
- *toupper*: make all characters upper case
- *tolower*: make all characters lower case
- *capitalize*: capitalize each word
- *1337*: leet speak modifier (random upper/lower case)

For example::

$ police '{{set data="YES,no,mayBE" sep="," modifier=capitalize}}'
Yes
No
Maybe

License
-------

This library is licensed under the GNU GENERAL PUBLIC LICENSE, version 2 (GPLv2).