Merge pull request #115 from jeronimoek/improve-readme

fix: add Custom Regexes README info

README.md

@@ -33,7 +33,7 @@ To see settings press `CTRL + ,` OR `⌘ + ,`
 | color-picker-universal.formatsFrom        | Enabled formats to translate from. Use "!" to exclude formats | ["*"]   | "\*" "device-cmyk" "hex" "hsl" "hwb" "named" "rgb" "hex0x" "lab" "lch" "oklab" "oklch" "a98"                | ["*", "!hex_0x", "!named"]                                                                                              |
 | color-picker-universal.formatsTo          | Enabled formats to translate into. Use "!" to exclude formats | ["*"]   | "\*" "cmyk" "hex" "hsl" "hwb" "named" "rgb" "hex0x" "lab" "lch" "oklab" "oklch" "a98"                       | ["*", "!hex_0x", "!cmyk", "!hwb"]                                                                                       |
 | color-picker-universal.maxDigits          | Max number of decimal digits                                  | 2       | <integer>                                                                                                   | 5                                                                                                                       |
-| color-picker-universal.customRegexes      | Set custom regexes. See [Custom Regexes](#-custom-regexes)    | {}      | See [Custom Regexes](#-custom-regexes)                                                                      | { "a98": ["my-a98\\((\\d+(?:\\.\\d+)?) \\$ (\\d+(?:\\.\\d+)?) \\$ (\\d+(?:\\.\\d+)?)(?: \\$ (\\d+(?:\\.\\d+)?))?\\)",]} |
+| color-picker-universal.customRegexes      | Set custom regexes for given formats                          | {}      | See [Custom Regexes](#-custom-regexes)                                                                      | { "a98": ["my-a98\\((\\d+(?:\\.\\d+)?) \\$ (\\d+(?:\\.\\d+)?) \\$ (\\d+(?:\\.\\d+)?)(?: \\$ (\\d+(?:\\.\\d+)?))?\\)",]} |
 
 ## ✍ Commands
 
@@ -57,7 +57,64 @@ To see the editor's context menu options press `right click` inside a file conte
 
 ## 🔧 Custom Regexes
 
-TODO: Soon...
+This setting allows the user to create custom presentations for the given formats.
+
+This takes an object with the following schema:
+
+```
+{
+    <format>: [
+        <regex>,
+        <regex2>
+    ],
+    <format2>: [
+        <regex3>
+    ]
+}
+```
+
+### Values
+
+#### \<format\>
+
+Is one of "formatsTo" ("cmyk", "hex", "hsl", "hwb", "named", "rgb", "hex0x", "lab", "lch", "oklab", "oklch", "a98")
+
+#### \<regex\>
+
+Is an escaped regex expression which matches the values of the color, and an optional alpha value (3 to 5 values, depending on the format).
+The values MUST be in the same format as in the standard presentation (can't pass a percentage value into a property that would typically only accept decimals, otherwise there could be unexpected outcomes).
+
+- Recommendation: test the standard presentations to check the allowed color properties presentations
+
+Here is a table with the standard presentations of each color format property (this follows closely the [W3C standards](https://www.w3.org/TR/css-color-4/))
+
+| Color Format/s       | Property/ies        | Presentations                                                                | Examples                                           |
+| -------------------- | ------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------- |
+| _ALL FORMATS_        | alpha (default = 1) | Number/String 0-1, String Percentage                                         | 0.5, '0.5', '50%'                                  |
+| RGB                  | r, g, b             | Number/String 0-255, String Percentage                                       | 123, '123', '50%'                                  |
+| A98                  | r, g, b             | Number/String 0-1                                                            | 0.5, '0.5'                                         |
+| HSL, HWB, LCH, OKLCH | h                   | Number/String 0-360, String Percentage, String Grad, String Rad, String Turn | 180, '180', '50%', '200grad', '3.14rad', '0.5turn' |
+| HSL                  | s, l                | Number/String 0-1, String Percentage                                         | 0.5, '0.5', '50%'                                  |
+| HWB                  | w, b                | Number/String 0-1, String Percentage                                         | 0.5, '0.5', '50%'                                  |
+| LAB, LCH             | l                   | Number/String 0-100, String Percentage                                       | 50, '50', '50%'                                    |
+| LAB                  | a, b                | Number/String -125 - 125, String Percentage -100% - 100%                     | -62.5, '-62.5', '-50%'                             |
+| LCH                  | c                   | Number/String 0-150, String Percentage                                       | 75, '75', '50%'                                    |
+| OKLAB, OKLCH         | l                   | Number/String 0-1, String Percentage                                         | 0.5, '0.5', '50%'                                  |
+| OKLAB                | a, b                | Number/String -0.4 - 0.4, String Percentage -100% - 100%                     | -0.2, '-0.2', '-50%'                               |
+| OKLCH                | c                   | Number/String 0-0.4, String Percentage                                       | 0.2, '0.2', '50%'                                  |
+| CMYK                 | c, m, y, k          | Number/String 0-1, String Percentage                                         | 0.5, '0.5', '50%'                                  |
+
+Here is a rgb regex example where we match r, g and b values, and an optional alpha. Note that it's missing percentage support
+
+```json
+"my-rgb\\((\\d+(?:\\.\\d+)?) \\$ (\\d+(?:\\.\\d+)?) \\$ (\\d+(?:\\.\\d+)?)(?: \\$ (\\d+(?:\\.\\d+)?))?\\)"
+```
+
+#### Regex Tips:
+
+- Doublequotes (") and backslashes (\\) are escaped with a backslash (\\).
+- The regex capture groups must only capture the required values, and the optional one (alpha) if desired
+- https://regexper.com/ This website is a great way to visualize and tweak regexes. [Here](https://regexper.com/#my-rgb%5C%28%28%5Cd%2B%28%3F%3A%5C.%5Cd%2B%29%3F%29%20%5C%24%20%28%5Cd%2B%28%3F%3A%5C.%5Cd%2B%29%3F%29%20%5C%24%20%28%5Cd%2B%28%3F%3A%5C.%5Cd%2B%29%3F%29%28%3F%3A%20%5C%24%20%28%5Cd%2B%28%3F%3A%5C.%5Cd%2B%29%3F%29%29%3F%5C%29) is the regex above visualized there. Note that **escape backslashes (\\) MUST be removed** when entering the regex there
 
 ## 🐞 Known Issues