@j-ulrich/release-it-regex-bumper 2.0.0 → 3.0.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Jochen Ulrich
+Copyright (c) 2020-2022 Jochen Ulrich
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -3,8 +3,8 @@
 > Regular expression based version read/write plugin for release-it
 
 ![CI](https://github.com/j-ulrich/release-it-regex-bumper/workflows/CI/badge.svg)
-[![Test Coverage](https://app.codacy.com/project/badge/Coverage/bf3c6e8740a9472b9acd7dac231adf4e)](https://www.codacy.com/manual/j-ulrich/release-it-regex-bumper?utm_source=github.com&utm_medium=referral&utm_content=j-ulrich/release-it-regex-bumper&utm_campaign=Badge_Coverage)
-[![Code Quality](https://app.codacy.com/project/badge/Grade/bf3c6e8740a9472b9acd7dac231adf4e)](https://www.codacy.com/manual/j-ulrich/release-it-regex-bumper?utm_source=github.com&utm_medium=referral&utm_content=j-ulrich/release-it-regex-bumper&utm_campaign=Badge_Grade)
+[![Test Coverage](https://app.codacy.com/project/badge/Coverage/bf3c6e8740a9472b9acd7dac231adf4e)](https://www.codacy.com/gh/j-ulrich/release-it-regex-bumper/dashboard?utm_source=github.com&utm_medium=referral&utm_content=j-ulrich/release-it-regex-bumper&utm_campaign=Badge_Coverage)
+[![Code Quality](https://app.codacy.com/project/badge/Grade/bf3c6e8740a9472b9acd7dac231adf4e)](https://www.codacy.com/gh/j-ulrich/release-it-regex-bumper/dashboard?utm_source=github.com&utm_medium=referral&utm_content=j-ulrich/release-it-regex-bumper&utm_campaign=Badge_Grade)
 
 This [release-it](https://github.com/release-it/release-it) plugin reads and/or writes versions
 using regular expressions.
@@ -34,13 +34,13 @@ For example:
 {
     "plugins": {
         "@j-ulrich/release-it-regex-bumper": {
-            "in": "path/to/versionfile.txt",
+            "in": "path/to/version_file.txt",
             "out": [
-                "path/to/versionfile.txt",
+                "path/to/version_file.txt",
                 {
                     "file": "README.md",
                     "search": "Version \\d+\\.\\d+\\.\\d+",
-                    "replace": "Version {{version}}"
+                    "replace": "Version {{versionWithoutPrerelease}}"
                 }
             ]
         }
@@ -48,7 +48,7 @@ For example:
 }
 ```
 
-For a more complex example, see [here](https://gitlab.com/julrich/MockNetworkAccessManager/-/blob/b31fd6d956ab0f61c1017432265e9e1c99a17bee/.release-it.json).
+For a more complex example, see [here](https://gitlab.com/julrich/MockNetworkAccessManager/-/blob/main/.release-it.json).
 
 
 ## Regular Expressions ##
@@ -64,7 +64,8 @@ example, the pattern `\d+` needs to be written as `"\\d+"` inside JSON.
 
 ## Configuration Options ##
 
-> **Note:** Options without a default value are required.
+> ℹ️ **Note:**    
+> Options without a default value are required.
 
 ### `in` ###
 
@@ -111,12 +112,26 @@ If `in.search` is an object, it takes the following properties:
 
 **Type:** `string`
 
-The regular expression pattern to find the version inside `in.file`.
+The regular expression pattern template to find the version inside `in.file`.
 
 Capturing groups can be used to extract the version from a part of the whole match. See the
 documentation of the configuration option `in.search.versionCaptureGroup` for a description of the
 handling of capturing groups.
 
+The `in.search.pattern` also supports a set of placeholders (since version 3.0.0):
+
+- `{{semver}}` is matching any version string complying to the semantic versioning specification (meaning at least
+  "major.minor.patch").
+- `{{now:<format>}}` is matching the current timestamp in a format specified by the `<format>` parameter.
+  The supported format syntax can be found in the [date-fns format](https://date-fns.org/v2.8.0/docs/format)
+  documentation.    
+  Example: `{{now:yyyy-MM-dd}}`
+- `{{{}}` is matching a literal `{`. This can be used to match a literal placeholder.    
+  For example: `{{{}}{foo}}` is matching `{{foo}}`
+
+> ℹ️ **Note:**    
+> All the placeholders are contained in a non-capturing group (`(?:...)`) so they behave like "atomic" constructs.
+
 ### `in.search.flags` ###
 
 **Type:** `string`    
@@ -124,6 +139,8 @@ handling of capturing groups.
 
 The flags for the regular expression `in.search.pattern`.
 
+If this option is `null` or not defined, the [global `search.flags`](#searchflags) are used.
+
 ### `in.search.versionCaptureGroup` ###
 
 **Type:** `integer|string`    
@@ -192,7 +209,7 @@ If both, this option and `out.files` are given, both are processed.
 **Since:** 1.1.0
 
 A path or an array of paths to files where the new version is written to. This option behaves the
-same as the `out.file` option but allows specifing multiple files or patterns. Accordingly, the
+same as the `out.file` option but allows specifying multiple files or patterns. Accordingly, the
 entries are also parsed with [fast-glob](https://github.com/mrmlnc/fast-glob):
 
 ```json
@@ -225,7 +242,7 @@ If this option is `null` or not defined, the [global `encoding`](#encoding) opti
 
 Defines the regular expression to find the text which is replaced with the new version inside
 `out.file`.
-If this option is `null` or not defined, the [global `search`](#search) option is used.
+If this option is `null` or not defined, the [global `search`](#search) is used.
 
 If `out.search` is a string, it is interpreted as the regular expression pattern.
 
@@ -235,12 +252,45 @@ If `out.search` is an object, it takes the following properties:
 
 **Type:** `string`
 
-The regular expression pattern to find the text to be replaced with the new version inside
+The regular expression pattern template to find the text to be replaced with the new version inside
 `out.file`.
 
 In contrast to `in.search.pattern`, capturing groups are not treated special in this pattern. So
 `out.replace` always replaces the *whole* match.
 
+If this option is `null` or not defined, the [global `search`](#search) resp.
+[global `search.pattern`](#searchpattern) is used.
+
+The `out.search.pattern` also supports a set of placeholders (since version 3.0.0):
+
+- `{{version}}` is matching the current version (before the increment).
+- `{{major}}` is matching the major part of the current version.
+- `{{minor}}` is matching the minor part of the current version.
+- `{{patch}}` is matching the patch part of the current version.
+- `{{prerelease}}` is matching the prerelease part of the current version. If the version does
+  not have a prerelease part, it is omitted (matching empty string).
+- `{{prefixedPrerelease}}` is matching a dash ('-') followed by the prerelease part of the current version. If the
+  version does not have a prerelease part, it is omitted (matching empty string).
+- `{{build}}` is matching the build part of the current version. If the version does not have a
+  build part, it is omitted (matching empty string).
+- `{{prefixedBuild}}` is matching a plus ('+') followed by the build part of the current version. If the version
+  does not have a build part, it is omitted (matching empty string).
+- `{{versionWithoutBuild}}` is matching the current version without the build part.
+- `{{versionWithoutPrerelease}}` is matching the current version without the prerelease and build parts.
+- `{{tag}}` is matching the current VCS tag (before the bump).
+- `{{newVersion}}` is matching the new version (after the increment).
+- `{{semver}}` is matching any version string complying to the semantic versioning specification (meaning at least
+  "major.minor.patch").
+- `{{now:<format>}}` is matching the current timestamp in a format specified by the `<format>` parameter.
+  The supported format syntax can be found in the [date-fns format](https://date-fns.org/v2.8.0/docs/format)
+  documentation.    
+  Example: `{{now:yyyy-MM-dd}}`
+- `{{{}}` is matching a literal `{`. This can be used to match a literal placeholder.    
+  For example: `{{{}}{foo}}` is matching `{{foo}}`
+
+> ℹ️ **Note:**    
+> All the placeholders are contained in a non-capturing group (`(?:...)`) so they behave like "atomic" constructs.
+
 ### `out.search.flags` ###
 
 **Type:** `string`    
@@ -248,6 +298,8 @@ In contrast to `in.search.pattern`, capturing groups are not treated special in
 
 The flags for the regular expression `out.search.pattern`.
 
+If this option is `null` or not defined, the [global `search.flags`](#searchflags) are used.
+
 ### `out.replace` ###
 
 **Type:** `string`    
@@ -263,31 +315,39 @@ XRegExp](http://xregexp.com/syntax/#replacementText).
 
 The template string also supports a set of placeholders:
 
-- `{{version}}` is replaced with the new version.
-- `{{major}}` is replaced with the major part of the new version.    
+- `{{version}}` is replaced by the new version.
+- `{{major}}` is replaced by the major part of the new version.    
   Since: 1.2.0
-- `{{minor}}` is replaced with the minor part of the new version.    
+- `{{minor}}` is replaced by the minor part of the new version.    
   Since: 1.2.0
-- `{{patch}}` is replaced with the patch part of the new version.    
+- `{{patch}}` is replaced by the patch part of the new version.    
   Since: 1.2.0
-- `{{prerelease}}` is replaced with the prerelease part of the new version.    
+- `{{prerelease}}` is replaced by the prerelease part of the new version or an empty string if the version does not
+  have a prerelease part.    
   Since: 1.2.0
-- `{{build}}` is replaced with the build part of the new version.    
+- `{{prefixedPrerelease}}` is replaced by a dash ('-') followed by the prerelease part of the new version or and empty
+  string if the version does not have a prerelease part.    
+  Since: 3.0.0
+- `{{build}}` is replaced by the build part of the new version or an empty string if the version does not have a
+  build part.    
   Since: 1.2.0
-- `{{versionWithoutBuild}}` is replaced with the new version without the build part.    
+- `{{prefixedBuild}}` is replaced by a plus ('+') followed by the build part of the new version or an empty string
+  if the version does not have a build part.    
+  Since: 3.0.0
+- `{{versionWithoutBuild}}` is replaced by the new version without the build part.    
   Since: 1.2.0
-- `{{versionWithoutPrerelease}}` is replaced with the new version without the prelease and build
+- `{{versionWithoutPrerelease}}` is replaced by the new version without the prerelease and build
   parts.    
   Since: 1.2.0
-- `{{latestVersion}}` is replaced with the current version, that is the version before the increase.
-- `{{latestTag}}` is replaced with the current VCS tag.
-- `{{now}}` is replaced with the current timestamp in ISO 8601 format.
-- `{{now:<format>}}` is replaced with the current timestamp in a format specified by the `<format>`
+- `{{latestVersion}}` is replaced by the current version, that is the version before the increase.
+- `{{latestTag}}` is replaced by the current VCS tag.
+- `{{now}}` is replaced by the current timestamp in ISO 8601 format.
+- `{{now:<format>}}` is replaced by the current timestamp in a format specified by the `<format>`
   parameter. The supported format syntax can be found in the [date-fns
   format](https://date-fns.org/v2.8.0/docs/format) documentation.    
   Example: `{{now:yyyy-MM-dd}}`
-- `{{{}}` is replaced with a literal `{`. This can be used to write a literal placeholder.    
-  For example: `{{{}}{foo}}` is replaced with `{{foo}}`    
+- `{{{}}` is replaced by a literal `{`. This can be used to write a literal placeholder.    
+  For example: `{{{}}{foo}}` is replaced by `{{foo}}`    
   Since: 1.2.0
 
 The placeholders are replaced before the template string is used in the search and replace and thus
@@ -309,17 +369,26 @@ If `search` is an object, it takes the following properties:
 ### `search.pattern` ###
 
 **Type:** `string`    
-**Default:** A pattern matching versions according to the semantic version specification.
+**Default:** `"{{semver}}"`
+
+The default regular expression pattern template which is used when `in.search.pattern` or
+`out.search.pattern` is `null` or not defined. See [`in.search.pattern`](#insearchpattern) and
+[`out.search.pattern`](#outsearchpattern) for more information.
 
-The default regular expression pattern which is used when `in.search.pattern` or
-`out.search.pattern` is `null` or not defined.
+> ⚠️ **Warning:**    
+> Note that the global `search.pattern` is used for both `in.search.pattern` and `out.search.pattern` unless
+> overridden explicitly. But `in.search.pattern` does not support all the placeholders of `out.search.pattern` and
+> using unsupported placeholders raises an error.
+
+If this option is not defined or set to `null`, the default value is used.
 
 ### `search.flags` ###
 
 **Type:** `string`    
 **Default:** `null`
 
-The flags for the regular expression `search.pattern`.
+The default flags for the search pattern which are used when `in.search.flags` or
+`out.search.flags` are `null` or not defined.
 
 ### `search.versionCaptureGroup` ###
 
@@ -352,9 +421,18 @@ encodings are the ones supported by Node's `fs` module.
 
 If this option is not defined or set to `null`, the default value is used.
 
+## Tips ##
+
+### Disable Output via Command-Line Parameter ###
+To completely disable changing any files by the plugin, you can use the command-line parameter `--no-plugins.@j-ulrich/release-it-regex-bumper.out`.
+For example:
+```
+npx release-it --no-plugins.@j-ulrich/release-it-regex-bumper.out
+```
+
 
 # License #
 
-Copyright (c) 2020-2021 Jochen Ulrich
+Copyright (c) 2020-2022 Jochen Ulrich
 
 Licensed under [MIT license](LICENSE).