diff --git a/README.md b/README.md index 39d9ce0..758df7b 100644 --- a/README.md +++ b/README.md @@ -5,12 +5,18 @@ 〚 [Docs](https://kildom.github.io/con-reg-exp/docs.html) 〛  〚 [Web Demo](https://kildom.github.io/cre-web-demo/) 〛  -This is a JavaScript module that provides different syntax for regular expressions. -The syntax is more convenient making it much easier to understand, review, maintain, and more. +> [!WARNING] +> This is a project in an early stage of development. +> The main functionality is done. +> More work is needed especially in the context of documentation and tests. -> [!NOTE] -> This is still work in progress project. The main functionality is done. -> More work is needed in context of documentation, tests, build and deployment. +## Regular expression syntax redefined + +The "Convenient Regular Expressions" give an alternative syntax for regular expressions. +The main goal is to introduce a syntax that is easily manageable in complex regular expressions. + +The module is still using a standard JavaScript's [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) object. +Essentially, it is a runtime transpiler that converts "Convenient Regular Expression" into a classic regular expression. ## Usage @@ -23,7 +29,7 @@ The syntax is more convenient making it much easier to understand, review, maint 2. Import it: ```javascript - import cre from "con-reg-exp"; // or: const cre = require("con-reg-exp") + import cre from "con-reg-exp"; ``` 3. Use it as a tagged template: @@ -32,82 +38,75 @@ The syntax is more convenient making it much easier to understand, review, maint const myRegExp = cre`"Write your expression here."`; ``` +You can find more details on usage in [the documentation](https://kildom.github.io/con-reg-exp/docs.html). + +If you want to start using it, go to the [tutorial](https://kildom.github.io/con-reg-exp/tutorial.html). + ## Benefits -* **You can add whitespaces** +* **You can use whitespaces** - This allows you to organize with spaces, - new lines and indentation. + Organize your expression structure with spaces, new lines, and indentation. -* **You can add comments** - - When a pice of code is not self-explanatory, a good comment - makes a huge difference. +* **You can use comments** + + A good comment can clarify an expression a lot making it easier to understand later. * **You are using words** - The words that describe the regular expression, are significantly - more readable. It is easier to memorize words which means - something than some arbitrarily selected special characters. + The words are significantly more readable than some arbitrarily selected special characters. * **Maintenance is simpler** - If you want to make a change in a well structured code, you simply - do it. With regular expression, you have to parse it your head, - track brackets, groups, and divide it into pieces. + If you want to make a change in a well-structured expression, you simply do it. + With complex classic regular expressions, first, you have to parse it in your head, track brackets, and groups, and divide it into pieces. * **Code review is faster and more accurate** - It easier to understand well formatted convenient code and changes - that are happening there. Have you ever try to review changes - in regular expression that are longer than 100 characters? - What was the felling? - -* **You can reuse code** - - You can put pieces of your expression into variables and simply - insert them into you expression. This is like splitting your - code into functions. + It is easier to understand well-structured expressions and changes in such expressions. + Have you ever tried to review changes in regular expressions that are longer than 100 characters? -* **You can forget about double meaning** +* **You can reuse the expressions** - Some flags are automatically taken care. For example, you - don't need to think if dot character includes new lines or not. + You can put pieces of your expression into variables and reuse them multiple times later. + It is like splitting your code into functions. -* **You are using sain language** +* **You are using sane syntax** - Long regular expressions looks like those esoteric programming - languages created just to give you a headache. + Long and complex regular expressions look like some esoteric programming languages created just to make the code unreadable. ## Some example Let's play a game. You have two functions. Try to understand what they are doing. -Pure RegExp implementation: +Classic RegExp implementation: ```javascript -function guessWhatDoesThisFunction(text) { - return /^\s*\[\s*(?:(?:[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?\s*,\s*)*[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?\s*)?\]\s*$/ - .test(text); +const pattern = /^\s*\[\s*(?:(?:-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?\s*,\s*)*-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?\s*)?\]\s*$/; + +function guessWhatDoesThisFunctionDo(text) { + return pattern.test(text); } ``` Convenient Regular Expressions: ```javascript - -import cre from 'con-reg-exp'; +import cre from "con-reg-exp"; const number = cre` - optional [+-]; // Sign - { - at-least-1 digit; // Integral part - optional (".", repeat digit); // Optional factional part + optional "-"; // Sign + { // Integral part + "0"; // Zero is special case } or { - ".", at-least-1 digit; // Variant with only fractional part + [1-9], repeat digit; // Everything above zero + } + optional { // Optional factional part + "."; + at-least-1 digit; } - optional { // Optional exponent part + optional { // Optional exponent part [eE]; optional [+-]; at-least-1 digit; @@ -116,27 +115,29 @@ const number = cre` const ws = cre`repeat whitespace`; -function guessWhatDoesThisFunction(text) { - return cre` - begin-of-text, ${ws}; // Trim leading whitespaces - "[", ${ws}; // Begin of array - optional { // Optional, because array can be empty - repeat { // Numbers with trailing comma - ${number}, ${ws}; - ",", ${ws}; - } - ${number}, ${ws}; // Last number has no comma +const pattern = cre` + begin-of-text, ${ws}; // Trim leading whitespaces + "[", ${ws}; // Begin of array + optional { // Optional, because array can be empty + repeat { // Numbers with trailing comma + ${number}, ${ws}; + ",", ${ws}; } - "]", ${ws}; // End of array - end-of-text; - `.test(text); + ${number}, ${ws}; // Last number has no comma + } + "]", ${ws}; // End of array + end-of-text; +`; + +function guessWhatDoesThisFunctionDo(text) { + return pattern.test(text); } ``` -Which one was easier to understand? I assuming that you don't know -the convenient regular expressions [syntax](docs/overview.md) yet. Were you able to guess +Which one was easier to understand? I'm assuming that you don't know +the convenient regular expressions [syntax](https://kildom.github.io/con-reg-exp/docs.html#syntax) yet. Were you able to guess despite this? -Click or hover the link to see [the answer](#It-validates-if-the-input-is-a-json-containing-an-array-of-numbers). +Click the link to see [the answer](https://kildom.github.io/cre-web-demo/#1nVZRa9swEN6zf4UQAxOqGNt52sr2sOGHwVgf1r1MNsxN1NSjVoqVpnQl/33fSZYtp1lGa0iwpbvvdPfdnU7ft3O4UT8m7W/zBklkC5tRI2B2nfIdQleqM1F0OhOiCPoo+p3SjdJbahsIR8fQOzplDMISRa4cHWCfERHl+MAsn/Pz5zX+HUli5Z5O94Iv6DjrDjDoXFurQA9Pn2F6hZ+q27DGgCi1bKBHJW71XEUOEDKbv6uET5ieSgdR7FT3iFrXa1ZfbXaK/QGmw5i6duTsUL/w29fg3b1ND5/w8+EjyFR3hlfYAVcbTfxMzEhVVKOdAUuezYPlf5n/Be4dsw+mZ7WP1Jjgo4zNq4vrby6rwiyYlLVAgj6Yfc8cPLjsmpbB/opCPQIbq8olnypMnP9EwJTK1vb/whVES+BMy/oe3dpVw7LWWGGqvds6GHp6Xw+BAON9xCVyg0uiblDUa4b7sK0HbXrePrmS2HsfJrtcDL4N647zo7qD9a+gytfaTW3QyQLTDoBXp8JWoHNMghY2Wss6hH4Y9EDHrb9448/uxl+9h8FjlMfiYGkcB2YzwNJdber27lZdwhTliLT2Y5mJXCyqWLhPJlnGBMvxW7CK+eVSy1JnotS5KLtSL0pd4d7sN2WaZIKlSU5/I5TMFJYzdUb/SZoW9ALRYp6NMoE0zjH94gs+LiSBUpaE7zCQ0zfKKrIDB/lKAaVIBz5jBLA6NJwcxooGKFKZeSE7nQQEHAxyVlaw+MNHBN7uucnOYfRV3A8lL8PDILSrb5tV7FGiffQX). -Imagine that you want modify both functions to allow strings in the array. +Imagine that you want to modify the function to allow strings in the array. diff --git a/docs/index.md b/docs/index.md index f55e3b5..726b3a8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,8 @@ -* [schoolGet started](#get-started) +* [rocketGet started](#get-started) +* [schoolTutorial](tutorial.html) * [menu_bookDocs](docs.html) -* [lightbulbDemo](https://kildom.github.io/cre-web-demo/) +* lightbulbDemo * [npm](https://www.npmjs.com/package/con-reg-exp) * [GitHub](https://github.com/kildom/con-reg-exp/) @@ -13,58 +14,52 @@ * review your RegExp. * express in words your RegExp. * reuse your RegExp. -* clear your RegExp. * improve your RegExp. -## What is Convenient Regular Expression? +## What are Convenient Regular Expressions? ### Regular expression syntax redefined -The "Convenient Regular Expression" gives a different approach to -a regular expressions syntax. The main goal is to provide -a syntax that is more manageable in complex regular expressions. -It looks more like actual program source code with clearly -visible structure, comments, and meaning. +The "Convenient Regular Expressions" give an alternative syntax for regular expressions. +The main goal is to introduce a syntax that is easily manageable in complex regular expressions. ### Under the hood -Under the hood, the module is still using a standard JavaScript's `RegExp` -object, so it is basically a runtime transpiler that converts -"Convenient Regular Expression" into standard regular expression. +The module is still using a standard JavaScript's [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) object. +Essentially, it is a runtime transpiler that converts "Convenient Regular Expression" into a classic regular expression. ## Why Convenient Regular Expressions? -### You can add whitespaces +### You can use whitespaces -This allows you to organize with spaces, new lines and indentation. +Organize your expression structure with spaces, new lines, and indentation. -### You can add comments +### You can use comments -When a pice of code is not self-explanatory, a good comment makes a huge difference. +A good comment can clarify an expression a lot making it easier to understand later. ### You are using words -The words that describe the regular expression, are significantly more readable. It is easier to memorize words which means something than some arbitrarily selected special characters. +The words are significantly more readable than some arbitrarily selected special characters. ### Maintenance is simpler -If you want to make a change in a well structured code, you simply do it. With regular expression, you have to parse it your head, track brackets, groups, and divide it into pieces. +If you want to make a change in a well-structured expression, you simply do it. +With complex classic regular expressions, first, you have to parse it in your head, track brackets, and groups, and divide it into pieces. ### Code review is faster and more accurate -It easier to understand well formatted convenient code and changes that are happening there. Have you ever try to review changes in regular expression that are longer than 100 characters? What was the felling? +It is easier to understand well-structured expressions and changes in such expressions. +Have you ever tried to review changes in regular expressions that are longer than 100 characters? -### You can reuse code +### You can reuse the expressions -You can put pieces of your expression into variables and simply insert them into you expression. This is like splitting your code into functions. +You can put pieces of your expression into variables and reuse them multiple times later. +It is like splitting your code into functions. -### You can forget about double meaning +### You are using sane syntax -Some flags are automatically taken care. For example, you don't need to think if dot character includes new lines or not. - -### You are using sain language - -Long regular expressions looks like those esoteric programming languages created just to give you a headache. +Long and complex regular expressions look like some esoteric programming languages created just to make the code unreadable. ## Get started @@ -74,7 +69,7 @@ Long regular expressions looks like those esoteric programming languages created npm install con-reg-exp ``` -Or, if you prefer to [download](https://github.com/kildom/con-reg-exp/releases/latest/download/con-reg-exp.browser.zip) +Or, if you prefer to [download](https://github.com/kildom/con-reg-exp/releases/latest/download/con-reg-exp-browser.zip) and use in an HTML tag: ```html @@ -95,7 +90,7 @@ const cre = require("con-reg-exp"); If you are using an HTML tag, the `cre` symbol is globally available and you don't need to import anything. -### Write your first Convenient Regular Expressions +### Write your first Convenient Regular Expression ```javascriptwithcre const inputText = "Hello World!!!"; @@ -106,16 +101,16 @@ const pattern = cre.global` const words = inputText.match(pattern); -console.log(...words); +console.log(words); ``` ### Learn more -* [Learn basics with the tutorial](tutorial.html) +* [Learn basics with the **tutorial**](tutorial.html) -* [Learn details from the documentation](docs.html) +* [Learn details from the **documentation**](docs.html) -* [Experiment with web demo](https://kildom.github.io/cre-web-demo/) +* Experiment with web demo