{"id":13624339,"url":"https://github.com/pemistahl/grex-js","last_synced_at":"2025-03-24T04:31:10.647Z","repository":{"id":55138362,"uuid":"516797668","full_name":"pemistahl/grex-js","owner":"pemistahl","description":"A JavaScript / WebAssembly library for generating regular expressions from user-provided test cases","archived":false,"fork":false,"pushed_at":"2023-08-02T08:59:28.000Z","size":1712,"stargazers_count":176,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-04-19T19:07:57.498Z","etag":null,"topics":["javascript","javascript-library","regex","regex-pattern","regexp","regular-expression","regular-expressions","wasm","webassembly"],"latest_commit_sha":null,"homepage":"https://pemistahl.github.io/grex-js/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pemistahl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-07-22T15:20:33.000Z","updated_at":"2024-02-03T22:42:21.000Z","dependencies_parsed_at":"2024-01-14T03:47:03.902Z","dependency_job_id":"814f7c3a-261e-426c-8ed6-a33ceec85f95","html_url":"https://github.com/pemistahl/grex-js","commit_stats":{"total_commits":14,"total_committers":1,"mean_commits":14.0,"dds":0.0,"last_synced_commit":"0215616f0675467c33bddf091b496f5d426ad846"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pemistahl%2Fgrex-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pemistahl%2Fgrex-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pemistahl%2Fgrex-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pemistahl%2Fgrex-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pemistahl","download_url":"https://codeload.github.com/pemistahl/grex-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245210996,"owners_count":20578324,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","javascript-library","regex","regex-pattern","regexp","regular-expression","regular-expressions","wasm","webassembly"],"created_at":"2024-08-01T21:01:41.472Z","updated_at":"2025-03-24T04:31:09.772Z","avatar_url":"https://github.com/pemistahl.png","language":"JavaScript","funding_links":[],"categories":["javascript"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n  ![grex](logo.png)\n\n  \u003cbr\u003e\n\n  [![build](https://github.com/pemistahl/grex-js/actions/workflows/build.yml/badge.svg)](https://github.com/pemistahl/grex-js/actions/workflows/build.yml)\n  [![docs](https://doxdox.org/images/badge-flat.svg)](https://doxdox.org/pemistahl/grex-js/master)\n  [![npm](https://img.shields.io/badge/npm-1.0.2-red?logo=npm)](https://www.npmjs.com/package/@pemistahl/grex)\n  [![demo](https://img.shields.io/badge/-Demo%20Website-orange?logo=HTML5\u0026labelColor=white)](https://pemistahl.github.io/grex-js/)\n  [![wasm](https://img.shields.io/badge/-WebAssembly-blueviolet?logo=WebAssembly\u0026labelColor=white)](https://webassembly.org/)\n  [![license](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n## 1. What does this library do?\n\n*grex* is a library that is meant to simplify the often complicated and tedious \ntask of creating regular expressions. It does so by automatically generating a \nsingle regular expression from user-provided test cases. The resulting\nexpression is guaranteed to match the test cases which it was generated from.\n\nThis project has started as a [Rust port](https://github.com/pemistahl/grex) of \nthe JavaScript tool [*regexgen*](https://github.com/devongovett/regexgen) \nwritten by [Devon Govett](https://github.com/devongovett). Although a lot of \nfurther useful features could be added to it, its development was apparently \nceased several years ago. The Rust library offers new features and extended \nUnicode support. By compiling it to [WebAssembly](https://webassembly.org) (WASM), \nthese improvements are now back in the browser and in [Node.js](https://nodejs.org/en/about).\nThis repository here contains only the compiled WASM modules and the generated\nJavaScript bindings. They have been created from the Rust source code with the help\nof [`wasm-pack`](https://github.com/pemistahl/grex#7-webassembly-support).\n\nThe philosophy of this project is to generate the most specific regular expression\npossible by default which exactly matches the given input only and nothing else.\nWith the use of preprocessing methods, more generalized expressions can be created.\n\nThe produced expressions are [Perl-compatible regular expressions](https://www.pcre.org).\nThey are mostly compatible with JavaScript's \n[`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp)\nimplementation but not all PCRE features are supported. An alternative is the [`XRegExp`](https://xregexp.com)\nlibrary which virtually supports the entire PCRE feature set. Other regular expression parsers or \nrespective libraries from other programming languages have not been tested so far, \nbut they ought to be mostly compatible as well.\n\nThere is a [demo website](https://pemistahl.github.io/grex-js/) available where you can give grex a try.\n\n![demo website](https://raw.githubusercontent.com/pemistahl/grex-js/main/website.jpg)\n\n## 2. Do I still need to learn to write regexes then?\n\n**Definitely, yes!** Using the standard settings, *grex* produces a regular expression that is guaranteed\nto match only the test cases given as input and nothing else. However, if the conversion to shorthand \ncharacter classes such as `\\w` is enabled, the resulting regex matches a much wider scope of test cases. \nKnowledge about the consequences of this conversion is essential for finding a correct regular expression \nfor your business domain.\n\n*grex* uses an algorithm that tries to find the shortest possible regex for the given test cases.\nVery often though, the resulting expression is still longer or more complex than it needs to be.\nIn such cases, a more compact or elegant regex can be created only by hand.\nAlso, every regular expression engine has different built-in optimizations. *grex* does not know anything\nabout those and therefore cannot optimize its regexes for a specific engine.\n\n**So, please learn how to write regular expressions!** The currently best use case for *grex* is to find\nan initial correct regex which should be inspected by hand if further optimizations are possible.\n\n## 3. Current Features\n- literals\n- character classes\n- detection of common prefixes and suffixes\n- detection of repeated substrings and conversion to `{min,max}` quantifier notation\n- alternation using `|` operator\n- optionality using `?` quantifier\n- escaping of non-ascii characters, with optional conversion of astral code points to surrogate pairs\n- case-sensitive or case-insensitive matching\n- capturing or non-capturing groups\n- optional anchors `^` and `$`\n- fully compliant to [Unicode Standard 15.0](https://unicode.org/versions/Unicode15.0.0)\n- correctly handles graphemes consisting of multiple Unicode symbols\n- produces more readable expressions indented on multiple using optional verbose mode\n- optional syntax highlighting for nicer output in supported terminals\n\n## 4. How to install?\n\n```\nnpm install @pemistahl/grex\n```\n\nThe current version 1.0.2 corresponds to the latest version 1.4.2 of the Rust\nlibrary and command-line tool.\n\n## 5. How to use?\n\nDetailed explanations of the available settings are provided in the [API section](#53-the-api).\n\n### 5.1 In the browser\n\n*grex* is available as an ECMAScript module. So it can be used in the browser,\nbut it needs a module bundler. As WebAssembly is a pretty new technology, the\nonly bundler which is currently compatible is [Webpack 5](https://webpack.js.org).\nIn your `webpack.config.js` file, you need to add the following setting to enable\nWASM support:\n\n```javascript\nmodule.exports = {\n    ...\n    experiments: {\n        asyncWebAssembly: true    \n    }\n};\n```\n\nAfterwards, you can import the library as shown below and bundle your JavaScript as usual.\n\n```javascript\nimport { RegExpBuilder } from '@pemistahl/grex';\n\nconst testCases = ['hello', 'world'];\nconst pattern = RegExpBuilder.from(testCases).build();\nconsole.log(pattern === '^(?:hello|world)$');\n\nconst regexp = RegExp(pattern);\nfor (const testCase of testCases) {\n    console.log(regexp.test(testCase));\n}\n```\n\n### 5.2 In Node.js\n\nThe library is also available as a CommonJS module, so it can be easily used in Node.js.\n\n```javascript\nconst { RegExpBuilder } = require('@pemistahl/grex');\n\nconst testCases = ['hello', 'world'];\nconst pattern = RegExpBuilder.from(testCases).build();\nconsole.log(pattern === '^(?:hello|world)$');\n\nconst regexp = RegExp(pattern);\nfor (const testCase of testCases) {\n    console.log(regexp.test(testCase));\n}\n```\n\n### 5.3 The API\n\nThe entire API docs are hosted on [doxdox.org](https://doxdox.org/pemistahl/grex-js).\n\n#### 5.3.1 Default settings\n\n```javascript\nconst regexp = RegExpBuilder.from(['a', 'aa', 'aaa']).build();\nconsole.assert(regexp === '^a(?:aa?)?$');\n```\n\n#### 5.3.2 Convert to character classes\n\n```javascript\nconst regexp = RegExpBuilder.from(['a', 'aa', '123'])\n    .withConversionOfDigits()\n    .withConversionOfWords()\n    .build();\nconsole.assert(regexp === '^(?:\\\\d\\\\d\\\\d|\\\\w(?:\\\\w)?)$');\n```\n\n#### 5.3.3 Convert repeated substrings\n\n```javascript\nconst regexp = RegExpBuilder.from(['aa', 'bcbc', 'defdefdef'])\n    .withConversionOfRepetitions()\n    .build();\nconsole.assert(regexp === '^(?:a{2}|(?:bc){2}|(?:def){3})$');\n```\n\nBy default, *grex* converts each substring this way which is at least a single character long\nand which is subsequently repeated at least once. You can customize these two parameters if you like.\n\nIn the following example, the test case `aa` is not converted to `a{2}` because the repeated substring\n`a` has a length of 1, but the minimum substring length has been set to 2.\n\n```javascript\nconst regexp = RegExpBuilder.from(['aa', 'bcbc', 'defdefdef'])\n    .withConversionOfRepetitions()\n    .withMinimumSubstringLength(2)\n    .build();\nconsole.assert(regexp === '^(?:aa|(?:bc){2}|(?:def){3})$');\n```\n\nSetting a minimum number of 2 repetitions in the next example, only the test case `defdefdef` will be\nconverted because it is the only one that is repeated twice.\n\n```javascript\nconst regexp = RegExpBuilder.from(['aa', 'bcbc', 'defdefdef'])\n    .withConversionOfRepetitions()\n    .withMinimumRepetitions(2)\n    .build();\nconsole.assert(regexp === '^(?:bcbc|aa|(?:def){3})$');\n```\n\n#### 5.3.4 Escape non-ascii characters\n\n```javascript\nconst regexp = RegExpBuilder.from(['You smell like 💩.'])\n    .withEscapingOfNonAsciiChars(false)\n    .build();\nconsole.assert(regexp === '^You smell like \\\\u{1f4a9}\\\\.$');\n```\n\nOld versions of JavaScript do not support Unicode escape sequences for the astral code planes\n(range `U+010000` to `U+10FFFF`). In order to support these symbols in JavaScript regular\nexpressions, the conversion to surrogate pairs is necessary. More information on that matter\ncan be found [here](https://mathiasbynens.be/notes/javascript-unicode).\n\n```javascript\nconst regexp = RegExpBuilder.from(['You smell like 💩.'])\n    .withEscapingOfNonAsciiChars(true)\n    .build();\nconsole.assert(regexp === '^You smell like \\\\u{d83d}\\\\u{dca9}\\\\.$');\n```\n\n#### 5.3.5 Case-insensitive matching\n\nThe regular expressions that *grex* generates are case-sensitive by default.\nCase-insensitive matching can be enabled like so:\n\n```javascript\nconst regexp = RegExpBuilder.from(['big', 'BIGGER'])\n    .withCaseInsensitiveMatching()\n    .build();\nconsole.assert(regexp === '(?i)^big(?:ger)?$');\n```\n\n#### 5.3.6 Capturing Groups\n\nNon-capturing groups are used by default.\nExtending the previous example, you can switch to capturing groups instead.\n\n```javascript\nconst regexp = RegExpBuilder.from(['big', 'BIGGER'])\n    .withCaseInsensitiveMatching()\n    .withCapturingGroups()\n    .build();\nconsole.assert(regexp === '(?i)^big(ger)?$');\n```\n\n#### 5.3.7 Verbose mode\n\nIf you find the generated regular expression hard to read, you can enable verbose mode.\nThe expression is then put on multiple lines and indented to make it more pleasant to the eyes.\n\n```javascript\nconst regexp = RegExpBuilder.from(['a', 'b', 'bcd'])\n    .withVerboseMode()\n    .build();\nconsole.assert(regexp ===\n`(?x)\n^\n  (?:\n    b\n    (?:\n      cd\n    )?\n    |\n    a\n  )\n$`);\n```\n\n#### 5.3.8 Disable anchors\n\nBy default, the anchors `^` and `$` are put around every generated regular expression in order\nto ensure that it matches only the test cases given as input. Often enough, however, it is\ndesired to use the generated pattern as part of a larger one. For this purpose, the anchors\ncan be disabled, either separately or both of them.\n\n```javascript\nconst regexp = RegExpBuilder.from(['a', 'aa', 'aaa'])\n    .withoutAnchors()\n    .build();\nconsole.assert(regexp === 'a(?:aa?)?');\n```\n\n### 6. How does it work?\n\n1. A [deterministic finite automaton](https://en.wikipedia.org/wiki/Deterministic_finite_automaton) (DFA)\n   is created from the input strings.\n\n2. The number of states and transitions between states in the DFA is reduced by applying\n   [Hopcroft's DFA minimization algorithm](https://en.wikipedia.org/wiki/DFA_minimization#Hopcroft.27s_algorithm).\n\n3. The minimized DFA is expressed as a system of linear equations which are solved with\n   [Brzozowski's algebraic method](http://cs.stackexchange.com/questions/2016/how-to-convert-finite-automata-to-regular-expressions#2392),\n   resulting in the final regular expression.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpemistahl%2Fgrex-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpemistahl%2Fgrex-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpemistahl%2Fgrex-js/lists"}