From d23880ef9d831a8ca4e1c7a10f3228bad400969a Mon Sep 17 00:00:00 2001 From: Ventsy Velev Date: Fri, 10 Nov 2023 11:21:52 -0500 Subject: [PATCH] Updates the documentation --- README.md | 101 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 66 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 1dd746a..731e8d4 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,8 @@ Given a pattern, generate all possible combinations. -Pattern Expander was intended as password recovery tool where the -password follows a certain pattern. +Pattern Expander was intended as password recovery tool where the password follows a certain pattern. +It uses UTF-8 and has been tested with Cyrillic, but it shoud be able to support other alphabets as well. For example `p[a@][s$][s$]` will result in: @@ -19,11 +19,10 @@ p@$$ ``` -Characters between [ ] are a group. Every character in a group is substituted -at the given position. - ## Installation +There are no binary distributions at this time, you have to compile it from source. + ### Requirements - gcc - make @@ -34,12 +33,14 @@ On Debian, those can be installed via: `sudo apt-get install build-essential libgtest-dev gcovr` ### Build and install +Clone the repo, cd into the source directory and run the following + ```sh make -sudo make install ``` You don't need to install patext, after building, you can run it from the the `./bin/` folder +but if you want it to be in the path `sudo make install` will copy it to `/usr/local/bin` ## Usage ``` @@ -47,7 +48,7 @@ patexp [-h | --help] [] commands: run [ .. ] | : Generates strings from a list of patterns validate [ .. ] | : Validates if the patterns provided are syntaxically correct - configure: Sets the various configuration options + configure: Sets the various configuration options ``` ### Examples @@ -89,41 +90,31 @@ abc3 ### Static strings Any unadorned strings are considered static. For example given the pattern -`abc[123]` - abc is static part. That part of the pattern doesn't change. +`abc[123]` - `abc` is static part. That part of the pattern doesn't change. -### Groups: -A group is a group of characters that are possible -- [abc] - Substitubes one each of the listed symbols -- [a - z] - Range. Expands to be equivalend to [a...z] -- \ : Escape character +#### Example + Pattern: "abcd" + Result: "abcd" -All characters are case sensative. +### Groups: +A group is a group of characters that are possible at the given position +- [abc] - Substitubes one each of the listed symbols at the given position +- [a-z] - Range. Expands to be equivalend to [a...z] works for numeric values as well ( [0-9] only ) +- [z-a] - Range. Expands to be equivalend to [z...a] works for numeric values as well ( [0-9] only ) -## Examples: -### Static examples - Pattern: "abcd" - Result: "abcd" - - Pattern: "abcd//e" - Result: "abcd/e" - - Pattern: "abcd/-" - Result: "abcd-" - - -### Group examples +#### Examples Pattern: "[abc]" - Result: "a", "b", "c" + Result: a, b, c Pattern: [a-c] - Result: "a", "b", "c" + Result: a, b, c Pattern: [c-a] - Result: "c", "b", "a" + Result: c, b, a Pattern: [A-C] - Result: "A", "B", "C" + Result: A, B, C Pattern: [123][abc] Result: 1a, 2a, 3a, 1b, 2b, 3b, 1c, 2c, 3c @@ -133,14 +124,54 @@ All characters are case sensative. Pattern: [123[a-c]] Result: 1a, 2a, 3a, 1b, 2b, 3b, 1c, 2c, 3c + +### Escape character +To include special characters such as `[ ]` and `-` in your pattern you have to escape them. This is done with the `/` character + + Pattern: "abcd/[e" + Result: "abcd[e" + + Pattern: "abcd/]" + Result: "abcd]" + +You do not need to escape the range (`-`) character in static portions of the stiring. For example: + + Pattern: "a-bcd" + Result: "a-bcd" + + Pattern: "a/bcd" + Result: "a/bcd" + +You do need to escape the escape character (`/`) in the next character is a reserved character. For example: + + Pattern: a//[1-3] + Result: a/1, a/2, a/3 + +Inside groups, you need to escape the range (`-`) symbol: + + Pattern: [a/-b] + Result: a, -, b + + +### Quotes +Quotes are used to denote static sections. They can be useful when you have a section that contains a lot of special characters. +Be aware that when running from the shell, you'll need to escape those. Using single quotes around your patters works well. + + Pattern: "[a-c]" + Result: [a-c] + +You can escape quotes in the usual fashion: + + Pattern: /"[a-b]/" + Result: "a", "b", "c" ## Development ### Targets: - release: default target. Builds the main executable -- debug: Builds with debug information and test coverage enabled -- test: Builds with debug information and test coverage enabled. Builds and runs the unit tests. +- debug: Builds the main executable with debug information and test coverage enabled +- test: Builds the main executable with debug information and test coverage enabled. Builds and runs the unit tests. - report: Creates a test coverage report @@ -149,11 +180,11 @@ Some example patters are given in the `test_data` folder. Those can be used for For example: ```sh -cat test_data/valid_patterns.txt | patext run +cat test_data/valid_patterns.txt | ./bin/patext run ``` ```sh -cat test_data/valid_patterns.txt | xargs patext run +cat test_data/valid_patterns.txt | xargs ./bin/patext run ``` ### Run unit tests