From 23857b03d824fe5e74064b46ba58664709339308 Mon Sep 17 00:00:00 2001 From: Jeronimo Date: Sun, 21 Jul 2024 21:10:21 +0200 Subject: [PATCH] fix: add Custom Regexes README info --- README.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 59 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6089e34..606a7ae 100644 --- a/README.md +++ b/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 | | 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: + +``` +{ + : [ + , + + ], + : [ + + ] +} +``` + +### Values + +#### \ + +Is one of "formatsTo" ("cmyk", "hex", "hsl", "hwb", "named", "rgb", "hex0x", "lab", "lch", "oklab", "oklch", "a98") + +#### \ + +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