smart-patcher

Patcher based on rules. Written for Deployer.

Features:

• embedded script support (Lua, Rhai) - to find, replace, or decode/encode
• any shell command support - to find, replace, or decode/encode
• regexes

Build

Install the Deployer and run:

deployer build

Or build by cargo:

cargo install --path .

Usage

See the patch examples in examples folder. You can run tests with them by Deployer.

The usage is easy:

smart-patcher test {patch-file.json} {folder-to-patch}   # to test if the patch is correct
smart-patcher apply {patch-file.json} {folder-to-patch}  # to apply the patch

If you use any scripts, make sure that the path to the script files is relative to the patch file.

Also you can use smart-patcher as library and even specify needed features:

[dependencies]
smart-patcher = { version = "0.4", features = ["lua", "rhai"] }

Patches

To write a patch you must define:

1. Set of rules to select files to patch
2. Set of rules to find file section to patch
3. Replace or inplace content
4. (Optionally) Decoder and encoder for any non-text files

Typical patch file looks like this:

{
  "patches": [
    {
      "files": [...],
      "decoder": ...,
      "encoder": ...,
      "patch_area": [...],
      "replace": ...,
      "insert": ...
    },..
  ]
}

1. Select rules

There are two types of select rules: just and re:

[
  {
    "just": "test_v5.docx"
  },
  {
    "re": ".*\\.docx"
  }
]

For match just rule, file path has to end with just value (e.g., tests/test_v5.docx). For re rule, file path has to match with Rust regular expression (read regex crate documentation).

2. File section rules

There are several rule types to cut text sections step by step:

1. contains - if file isn't contain the text described by contains value's regular expression, the patch is not applied to it
2. not_contains - nearly the same
3. before and after - cuts the patchable area before and after specified regular expression matches
4. cursor_at_begin and cursor_at_end - moves the inplace cursor at begin or at end of the text area
5. find_by_{lua,sh,rhai} - cuts the section by Lua/Rhai or shell script

This is how a step by step set looks like:

{
  "patch_area": [
    {
      "contains": "file must contain this text to apply the patch"
    },
    {
      "before": "we select all before this text..."
    },
    {
      "after": "...but after this."
    },
    {
      "find_by_sh": "some_script_afterall.py"
    }
  ]
}

Script examples can be found at tests folder.

3. replace and insert content

{
  "replace": {
    "from_to": [
      "some text to be replaced",
      "some resulting text"
    ]
  },
  "insert": "some text at cursor"
}

insert value will be inserted at begin or end of selected text area. If the last file section rule was before, cursor will be at the end of section; otherwise it will be at the begin of section, if you're not using the scripts. Any script can specify cursot_at_end = True|False as third return value of the find function (e.g. see tests/test_v4.py and examples/patch4.json).

replace value will perform the replacement only and only if selected text area isn't empty. Simple from_to form just replace all matches of a first text with a second text. regex_to form use regular expressions to capture text and groups and replace with another text. But you can specify by_{lua,python,rhai} form:

{
  "replace":   {
    "by_rhai": "some_script.rhai"
  }
}

For example, see tests/test_v8.py.

4. decoder and encoder content

See the tests/test_v5.py example (and tests/test_v5.docx file). This is simple example how you can transform your Microsoft Word document - and any other type of files - to text and vice versa to patch the content you need.

{
  "decoder": {
    "sh": "tests/test_v5.py"
  },
  "encoder": {
    "sh": "tests/test_v5.py"
  },
}

You can also specify lua and rhai values instead of sh.

5. Shell vs Rhai/Lua (0.3 -> 0.4 migration)

If lua or rhai feature is enabled, smart-patcher can patch files without any external runtime dependencies. Unfortunately, Python can't be embedded within smart-patcher due to pyo3 library, therefore now you can choose to shebang your Python scripts and use them again.

Nevertheless, API was slightly changed. Requests are written in JSON files and responses are read from JSON files too. See Python scripts implementations in tests folder to see how them are adapted to new smart-patcher.

For novices, in smart-patcher v0.4 you can propose any scripts to handle next patch tasks: find, replace, and decode from/encode to any binary data. For Rhai/Lua scripts, you should write functions with proposed names (find, replace, decode and encode), and for shell scripts you should use file system I/O and JSON utilities to read requests and write responses in paths provided by command arguments.