Skip to content

Commit

Permalink
Fixes in front page and readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@kildom
kildom committed Mar 4, 2024
1 parent d11c588 commit 3badd54
Show file tree
Hide file tree
Showing 9 changed files with 143 additions and 99 deletions.
129 changes: 65 additions & 64 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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:
Expand All @@ -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;
Expand All @@ -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.
61 changes: 28 additions & 33 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@

* [<span><span class="material-symbols-outlined">school</span></span>Get started](#get-started)
* [<span><span class="material-symbols-outlined">rocket</span></span>Get started](#get-started)
* [<span><span class="material-symbols-outlined">school</span></span>Tutorial](tutorial.html)
* [<span><span class="material-symbols-outlined">menu_book</span></span>Docs](docs.html)
* [<span><span class="material-symbols-outlined">lightbulb</span></span>Demo](https://kildom.github.io/cre-web-demo/)
* <a href="https://kildom.github.io/cre-web-demo/" target="cre-web-demo"><span><span class="material-symbols-outlined">lightbulb</span></span>Demo</a>
* [<img src="npm.svg">npm](https://www.npmjs.com/package/con-reg-exp)
* [<img src="github-mark.svg">GitHub](https://github.com/kildom/con-reg-exp/)

Expand All @@ -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

Expand All @@ -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
Expand All @@ -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!!!";
Expand All @@ -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/)
* <a href="https://kildom.github.io/cre-web-demo/" target="cre-web-demo">Experiment with <b>web demo</b></a>

<!--
Copyright © 2024
Expand Down
1 change: 1 addition & 0 deletions docs/tmpl/docs.tmpl.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
<html>

<head>
<title>Convenient Regular Expressions</title>
<script src="docs.js"></script>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0" />
<link rel="stylesheet" href="docs.css" type="text/css" media="all" />
Expand Down
20 changes: 20 additions & 0 deletions docs/tmpl/index.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,26 @@ div.sample-part {
color: #b1b1b1;
}

a.try-it-button {
display: block;
float: right;
padding: 8px 14px;
background: #344d83;
margin: 5px;
border-radius: 5px;
text-decoration: none;
color: white;
font-weight: bold;
font-size: 110%;
box-shadow: inset 0px 0px 3px 2px #FFF1;
}

a.try-it-button:hover {
box-shadow: inset 0px 0px 3px 3px #FFF2;
color: white;
text-decoration: none;
}

/*---------------------------------------------------------------- DETAILS
*/

Expand Down
5 changes: 3 additions & 2 deletions docs/tmpl/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -208,11 +208,12 @@ function nextScript() {
nextEl: ".swiper-button-next",
prevEl: ".swiper-button-prev",
},
initialSlide: document.querySelectorAll('.swiper-slide').length - 2,
});

setupClicks();

swiper.slideTo(document.querySelectorAll('.swiper-slide').length - 2, 500);

document.querySelector(".mySwiper").style.visibility = 'visible';

document.querySelector(".swiper-wrapper").style.width = '1px';
}
2 changes: 2 additions & 0 deletions docs/tmpl/index.tmpl.html
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
<html>
<head>
<title>Convenient Regular Expressions</title>
<script src="https://code.jquery.com/jquery-3.7.1.min.js" integrity="sha256-/JqT3SQfawRcv/BIHPThkBvs0OEvtFFmqPF/lYI/Cxo=" crossorigin="anonymous"></script>
<script src="https://cdn.jsdelivr.net/npm/swiper@11/swiper-bundle.min.js"></script>
<script src="con-reg-exp.min.js"></script>
Expand Down Expand Up @@ -32,6 +33,7 @@
<% for (sample of samples) { %>
<div class="swiper-slide">
<div class="sample">
<a href="<%- sample.demoURL %>" target="cre-web-demo" class="try-it-button">▶&nbsp;&nbsp;Try it</a>
<pre class="sample-title language-javascriptwithcre">// <%- sample.title %></pre>
<div class="sample-part">Classic</div>
<pre
Expand Down
Loading

0 comments on commit 3badd54

Please sign in to comment.