{"id":22697534,"url":"https://github.com/tomaskraus/simple-string-pattern","last_synced_at":"2025-03-29T18:26:45.007Z","repository":{"id":246010627,"uuid":"819831949","full_name":"tomaskraus/simple-string-pattern","owner":"tomaskraus","description":"A very simple pattern format used to match a string.","archived":false,"fork":false,"pushed_at":"2024-08-28T19:32:35.000Z","size":216,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-04T19:24:28.491Z","etag":null,"topics":["pattern","regexp","string-matching","testing"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tomaskraus.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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-25T09:29:55.000Z","updated_at":"2024-07-30T00:10:11.000Z","dependencies_parsed_at":"2024-06-25T10:59:52.650Z","dependency_job_id":"3b80bfdc-0a70-4070-b105-df8304c138d5","html_url":"https://github.com/tomaskraus/simple-string-pattern","commit_stats":null,"previous_names":["tomaskraus/simple-string-pattern"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomaskraus%2Fsimple-string-pattern","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomaskraus%2Fsimple-string-pattern/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomaskraus%2Fsimple-string-pattern/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomaskraus%2Fsimple-string-pattern/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tomaskraus","download_url":"https://codeload.github.com/tomaskraus/simple-string-pattern/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246225363,"owners_count":20743548,"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":["pattern","regexp","string-matching","testing"],"created_at":"2024-12-10T05:14:17.314Z","updated_at":"2025-03-29T18:26:44.986Z","avatar_url":"https://github.com/tomaskraus.png","language":"JavaScript","readme":"# Simple String Pattern\n\nA **Simple String Pattern** (a.k.a. **SSP**) is a very simple yet well defined pattern format used to match a string.  \nA **simple-string-pattern** is also a name of the library to dealing with _Simple String Patterns_, [here](#simple-string-pattern-library) in this document.\n\nUnlike [Regular Expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions), _Simple String Pattern_ intentionally has only a few features, to be very easy to read and understand.\n\nThe motivation to create such a thing as the SSP was the need for a simple pattern format in [Clogtest testing tool](https://github.com/tomaskraus/clogtest), which runs a piece of code and tests the code output against specially commented assertions:\n\n```js\n// We expect the output to be 2\nconsole.log(1 + 1);\n//=\u003e 2\n\nconsole.log(1 + 1 === 2);\n//=\u003e true\n\n// Here, we only write the beginning of what we expect to be the output\nconsole.log('abcd'.split(''));\n//=\u003e [ 'a', 'b' ...\n\n// What the end of the output should look like (including the space at the end.)\nconsole.log('Thats All! ');\n//=\u003e ... \"All! \"\n\n// What the (possibly multi-line) output should contain\nconsole.log('Line: 155 \\nError: Division by zero!');\n//=\u003e ... zero ...\n\n// In the expected output,\n// we can describe common special characters using escape sequences\nconsole.log('a' + String.fromCharCode(9) + '1');\n//=\u003e a\\t1\n\n// And yes we can go beyond the ASCII:\nconsole.log('絵文字: 😀.');\n//=\u003e 絵文字: 😀.\n```\n\nIn the code example above, there are SSPs within those `//=\u003e` comments.\n\nAs you can see, the SSP really is a string that may contain spaces and some escaped characters, optionally double-quoted, possibly surrounded by three dots (\"...\") on either side.\n\n#### Solid Foundation\n\nFrom the very beginning, **SSP** format aims to be well defined, hence it has its own [SSP Grammar](#ssp-grammar).\n\n## SSP Examples\n\n- `abc`: Does match the string '`abc`' only.\n- `\" abc\"`: Does match the string '` abc`' only. Double quotes ensure that leading and trailing spaces matter in the matching process. Those outermost double quotes are not part of the matching.\n- `\\\" abc\"`: Does match the string '`\" abc\"`' including those double quotes. The leading backslash (`\\`) character cancels the special meaning of the outermost double quotes.\n- `abc ...`: Does match any string that starts with '`abc`'.\n- `... abc`: Does match any string that ends with '`abc`'.\n- `... abc ...`: Does match any string that contains at least one '`abc`'.\n- `... \" = \" ...`: Does match any string that contains at least one (`=`) character having at least one space before and after.\n- `... \\n ...`: Does match any string that contains at least one _newline_ character.\n- `... \\\\ ...`: Does match any string that contains at least one backslash character (`\\`). Note that the _backslash_ character is also escaped.\n\n\u003e All SSPs are _case sensitive_: `abc` does match the string '`abc`' but not the '`ABc`'\n\n## The Great Escape\n\nIn this document, SSP examples are written in the way they appear in the console or a file.  \nShould you use SSPs as a string literal in javascript, just **double** those backslashes in that literal.\n\nExample: `Hello \\n \\\\backslashes\\\\!` SSP expression will appear as \u003ccode\u003e'Hello\u0026nbsp;\\\\\\\\n\u0026nbsp;\\\\\\\\\\\\\\\\backslashes\\\\\\\\\\\\\\\\!'\u003c/code\u003e string literal in a javascript file. It will match this input:\n\n\u003e \u003ccode\u003eHello\u0026nbsp; \u003c/code\u003e  \n\u003e \u003ccode\u003e\u0026nbsp;\\backslashes\\!\u003c/code\u003e\n\n## Pattern Definition\n\n_Simple String Pattern_ (a.k.a. SSP) is a **trimmed** string with some **escape sequences**, intended to match **multi-line** _input_ in a **case-sensitive** manner.\n\nSSP consist of _Pattern Body_ (i.e. exact string to match), which can be surrounded by a _*Partial Mark*_ (`...`) on either side, to match the beginning, the end or the inside of the possible _input_.  \nThere must be exactly one space between a _Partial Mark_ and _Pattern Body_.\n\n\u003e **Note**: Only the _Pattern Body_ is matched against the input in the matching process. Partial Marks only tell how to do the match.\n\nA simplified SSP structure (in an [ABNF](https://en.wikipedia.org/wiki/Augmented_Backus%E2%80%93Naur_form)):\n\n```abnf\nssp = [partial-mark space] pattern-body [space partial-mark]\n```\n\nThe pattern body itself can be surrounded by double quotes (`\"`), to make its leading and trailing spaces significant. This outermost double quote pair is not a part of the matching process.\n\nSome special characters (such as the _newline_ one) can be written in an SSP using **escape-sequence**, with a backslash (`\\`) as an escape symbol.  \n Escape the backslash itself to use the backslash in an SSP.\n\n\u003e For a complete SSP definition, see the [SSP Grammar](#ssp-grammar) chapter.\n\n## SSP Types:\n\nDepending on where in the pattern the _partial mark_ (`...`) is, the pattern is one of four types:\n\n1. _Full_: `XXX`\n2. _Start_: `XXX ...`\n3. _End_: `... XXX`\n4. _Middle_: `... XXX ...`\n\nOnly the _Full Pattern_ matches the input as a whole.\n\nThere are some real examples:\n\n1. `Hello\\n \"World\"`: The _Full Pattern_ example. There is only a _Pattern Body_ (`Hello\\n \"World\"`) in the _Full Pattern_, without any _Partial Marks_.  \n   This _Full Pattern_ does match the whole string '`Hello\\n \"World\"`'.\n2. \u003ccode\u003e\"Hello\u0026nbsp;\" ...\u003c/code\u003e: The _Start Pattern_. Consists of a _Pattern Body_ (\u003ccode\u003eHello\u0026nbsp;\u003c/code\u003e) and a _Partial Mark_ (`...`) at the end. Here, the _Pattern Body_ is leading-and-trailing-space significant.  \n   This _Start Pattern_ match any string that begins with '`Hello `'.\n3. `... World\"`: The _End Pattern_. With the leading _Partial Mark_, followed by a _Pattern Body_ (`World\"`). Being not surrounded by double quotes, the _Pattern Body_ does not preserve leading or trailing spaces.  \n   This _End Pattern_ does match any string that ends with '`World\"`'.\n4. `... Wo ...`: The _Middle Pattern_, with a _Pattern Body_ (`Wo`), surrounded by _Pattern Marks_.  \n   This _Middle Pattern_ does match any string that contains the string '`Wo`'.\n\nAll of these SSP examples match this multi-line string input:\n\n```\nHello\n \"World\"\n```\n\n## On Double Quotes:\n\nBecause of special meaning of double quotes surrouding the pattern body:\n\n- `\"abc\"`: Does match the string '`abc`' only.\n- `\"... abc ...\"`: Does match the string '`... abc ...`'.\n\nShould we need to match a string surrounded by double quotes, just escape the leading double quote:\n\n- `\\\"abc\"`: Does match the string '`\"abc\"`' only.\n\nIf a pattern body is not completely surrounded by double quotes, that outermost double-quote character is treated as a normal one - i.e. is a part of a search:\n\n- `abc\"`: Does match the string '`abc\"`' only.\n- `\"abc`: Does match the string '`\"abc`' only.\n\n## Some special SSPs:\n\n- `\"\"` the full empty pattern, does match the empty input only\n- `\"\" ...` the start empty pattern (does match everything)\n- `... \"\"` the end empty pattern (does match everything)\n- `... \"\" ...` the middle empty pattern (does match everything)\n\n## Invalid SSP Examples:\n\nThe empty string is not a valid SSP. Use `\"\"` as an SSP that does (and only) match the empty input.\n\nThe string \u003ccode\u003e\u0026nbsp;hello\u003c/code\u003e is not a valid SSP, as it starts with a whitespace, so it is not trimmed.\n\nThe string \u003ccode\u003e\u0026nbsp;\u003c/code\u003e is not a valid SSP, as it starts with a whitespace, so it is not trimmed. Use the full exact pattern to match an input containing spaces at the beginning/end.\n\nThe string:\n\n    Hello\n    \"World\"\n\nis not a valid SSP, as it contains an unescaped newline character.\n\n\u003e Tips to fix an invalid SSP:\n\u003e\n\u003e 1. Enclose it with double_quotes.\n\u003e 2. Use escape sequences for control characters, such as `\\t` for tabs and `\\n` for newlines\n\u003e 3. Be sure to escape a backslash `\\` if you want to use it as an ordinary character.\n\u003e 4. Do not escape characters that don't need to be escaped.\n\n## SSP Grammar\n\nThere is a [Simple String Pattern Grammar](./src/ssp.abnf) file, expressed in [ABNF](https://en.wikipedia.org/wiki/Augmented_Backus%E2%80%93Naur_form).\n\n# simple-string-pattern library\n\nThe **simple-string-pattern** library contains an object that encapsulates the SSP and provides methods to create an SSP and test SSP against a string input.\n\nThis library is:\n\n- Typed, with `d.ts` for javascript\n- Well tested, with 100% code coverage\n\n## Installation\n\n```bash\n$ npm i simple-string-pattern\n```\n\n## Usage\n\n### Import\n\nTypescript / ES module:\n\n```ts\nimport SSP from 'simple-string-pattern';\n```\n\nJavascript / CommonJS:\n\n```js\nconst SSP = require('simple-string-pattern').default;\n```\n\n### Create a Pattern\n\nSSP constructor expect a string in an SSP format as a parameter:\n\n```js\nconst patt = new SSP('Hello,\\\\n \"World\"!');\n```\n\nFrom the above example, the _patt_ object holds this pattern: `Hello,\\n \"World\"!`\n\n\u003e SSP constructor throws an _Error_ if its argument is not a valid SSP string.\n\n### value() method\n\nTo get a string representation of the pattern, use the _value()_ method of the SSP object:\n\n```js\nconst patt = new SSP('hello');\nconsole.log(patt.value());\n//=\u003e hello\n\nconst patt2 = new SSP('\"abc\"');\nconsole.log(patt2.value());\n//=\u003e \\\\\"abc\"\n```\n\n### test() method\n\nReturns _true_ if pattern does match the string parameter, _false_ otherwise:\n\n```js\nconst patt = new SSP('... lazy ...');\n\nconsole.log(patt.test('See?\\nWhat a lazy fox!'));\n//=\u003e true\nconsole.log(patt.test('lazy'));\n//=\u003e true\nconsole.log(patt.test('See?\\nWhat a l-a-z-y fox!'));\n//=\u003e false\n```\n\n### parse() method\n\n_parse()_ static method creates an SSP instance from an input string \"as is\", escaping newlines and other line breaks:\n\n```js\nconst s = `Hello\n world!`;\n\nconst patt = SSP.parse(s);\n// patt points to an SSP object instance\n```\n\nFrom the above example, the _patt_ object holds this pattern: `Hello\\n world!`\n\n_Parse()_ method creates such an SSP object that does match the input argument of _Parse()_ method itself:\n\n```js\n// creates an SSP pattern literally\nconst patt = SSP.parse('... abc ...');\nconsole.log(patt.value());\n//=\u003e \"... abc ...\"\nconsole.log(patt.test('... abc ...'));\n//=\u003e true\nconsole.log(patt.test('abc'));\n//=\u003e false\n```\n\nUnlike the SSP constructor, _parse()_ method treats its argument as a text a newly created SSP object will match, instead of a textual representation of a pattern (a.k.a. SSP expression).\n\nThe _parse()_ method can create an empty SSP object from an empty input:\n\n```js\nconst patt = SSP.parse('');\nconsole.log(patt.value());\n//=\u003e \"\"\nconsole.log(patt.test(''));\n//=\u003e true\n```\n\n_SSP.parse()_ method throws an _Error_ if a valid SSP cannot be created from its argument:\n\n```js\nSSP.parse(String.fromCharCode(0));\n// throws an Error\n```\n\n\u003e _Note_: _SSP.parse()_ always returns a _Full Pattern_ SSP object.\n\n### limitPatternLen() method\n\nReturns at least \"the-same-matching\", new SSP object with its body length being less or equal the original object's one.\n\n_value()_ of the SSP object returned can be of \"Start Pattern\" type.\n\n```js\n// squares: array of squared integers from 0 to 14\nconst squares = new Array(15).fill(null).map((_, i) =\u003e i * i);\n\nconst pattern = SSP.parse(squares);\nconsole.log(pattern.value());\n//=\u003e 0,1,4,9,16,25,36,49,64,81,100,121,144,169,196\n\nconst patternShortened = pattern.limitPatternLen(10);\nconsole.log(patternShortened.value());\n//=\u003e 0,1,4,9,16 ...\n\n// Both pattern and patternShortened match the original input.\nconsole.log(pattern.test(squares.toString()));\n//=\u003e true\nconsole.log(patternShortened.test(squares.toString()));\n//=\u003e true\n```\n\n_limitPatternLen()_ method throws an _Error_ if its object's pattern type is not _Full Pattern_ or _Start Pattern_:\n\n```js\nconst patt = new SSP(\"... That's end.\");\nconst patt2 = patt.limitPatternLen(4); // throws Error\n```\n\nFor more about pattern types, see the [SSP Types](#ssp-types) chapter.\n\n### On SSP objects equality\n\nTwo SSP objects are considered equal if they do match the same inputs.  \nIf both SSP object holds the same SSP string (available via their _value()_ method), then those two SSP object are equal. However, two SSP object can be equal without having the same SSP string:\n\n```js\nconst patt1 = new SSP('\"abc\"');\nconst patt2 = new SSP('abc');\n\nconsole.log(patt1.value() === patt2.value());\n//=\u003e false\nconsole.log(patt1.test('abc') \u0026\u0026 patt2.test('abc'));\n//=\u003e true\n```\n\nThe following holds true:\n\n```js\n// we assume the patt1 is defined and is a valid SSP object.\nconst patt3 = new SSP(patt1.value());\nconsole.log(patt1.value() === patt3.value());\n//=\u003e true\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomaskraus%2Fsimple-string-pattern","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomaskraus%2Fsimple-string-pattern","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomaskraus%2Fsimple-string-pattern/lists"}