{"id":19838132,"url":"https://github.com/textlint/textlint-util-to-string","last_synced_at":"2025-05-01T18:31:03.265Z","repository":{"id":60775281,"uuid":"46692059","full_name":"textlint/textlint-util-to-string","owner":"textlint","description":"[textlint] Convert Paragraph Node to plain text with Source Map.","archived":false,"fork":false,"pushed_at":"2023-11-25T05:04:54.000Z","size":494,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-08T12:50:58.298Z","etag":null,"topics":["textlint","textlint-util","txtast"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/textlint.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":"2015-11-23T02:31:26.000Z","updated_at":"2023-12-03T16:29:58.000Z","dependencies_parsed_at":"2024-06-18T19:52:37.141Z","dependency_job_id":"2e35374b-73a8-4dea-a1c8-943f98930f19","html_url":"https://github.com/textlint/textlint-util-to-string","commit_stats":{"total_commits":71,"total_committers":4,"mean_commits":17.75,"dds":"0.21126760563380287","last_synced_commit":"99f54cee6778aa56004f002e17f2e1f57fda250f"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/textlint%2Ftextlint-util-to-string","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/textlint%2Ftextlint-util-to-string/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/textlint%2Ftextlint-util-to-string/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/textlint%2Ftextlint-util-to-string/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/textlint","download_url":"https://codeload.github.com/textlint/textlint-util-to-string/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224269997,"owners_count":17283649,"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":["textlint","textlint-util","txtast"],"created_at":"2024-11-12T12:16:51.776Z","updated_at":"2024-11-12T12:16:52.657Z","avatar_url":"https://github.com/textlint.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# textlint-util-to-string [![Actions Status: test](https://github.com/textlint/textlint-util-to-string/workflows/test/badge.svg)](https://github.com/textlint/textlint-util-to-string/actions?query=workflow%3A\"test\")\n\nConvert `Paragraph` Node to plain text with SourceMap.\nIt means that you can get original position from plain text.\n\nThis library is for [textlint](https://github.com/textlint/textlint \"textlint\") and [textstat](https://github.com/azu/textstat \"textstat\").\n\n## Installation\n\n    npm install textlint-util-to-string\n\n## Terminology\n\nThe concepts `position` and `index` are the same with [TxtAST Interface](https://textlint.github.io/docs/txtnode.html) and [textlint/structured-source](https://github.com/textlint/structured-source).\n\n- `position` is a `{ line, column }` object.\n  - The `column` property of `position` is **0-based**.\n  - The `line` property of `position` is **1-based**.\n- `index` is an offset number.\n  - The `index` property is **0-based**.\n\n## API\n\n### `new StringSource(node: TxtParentNode, options?: StringSourceOptions)`\n\nCreate new `StringSource` instance for `paragraph` Node.\n\n### `toString(): string`\n\nGet plain text from `Paragraph` Node.\n\nThis plain text is concatenated from `value` of all children nodes of `Paragraph` Node.\n\n```ts\nimport { StringSource } from \"textlint-util-to-string\";\nconst report = function (context) {\n    const { Syntax, report, RuleError } = context;\n    return {\n        // \"This is **a** `code`.\"\n        [Syntax.Paragraph](node) {\n            const source = new StringSource(node);\n            const text = source.toString(); // =\u003e \"This is a code.\"\n        }\n    }\n};\n```\n\nIn some cases, you may want to replace some characters in the plain text for avoiding false positives.\nYou can replace `value` of children nodes by `options.replacer`.\n\n`options.replacer` is a function that takes a `node` and commands like `maskValue` or `emptyValue`.\nIf you want to modify the `value` of the node, return command function calls.\n\n```ts\n// \"This is a `code`.\"\nconst source = new StringSource(paragraphNode, {\n    replacer({ node, maskValue }) {\n        if (node.type === Syntax.Code) {\n            return maskValue(\"_\"); // code =\u003e ____\n        }\n    }\n});\nconsole.log(source.toString()); // =\u003e \"This is a ____.\"\n```\n\n- `maskValue(character: string)`: mask the `value` of the node with the given `character`.\n- `emptyValue()`: replace the `value` of the node with an empty string.\n\n### `originalIndexFromIndex(generatedIndex): number | undefined`\n\nGet original index from generated index value\n\n### `originalPositionFromPosition(position): Position | undefined`\n\nGet original position from generated position\n\n### `originalIndexFromPosition(generatedPosition): number | undefined`\n\nGet original index from generated position\n\n### `originalPositionFromIndex(generatedIndex): Position | undefined`\n\nGet original position from generated index\n\n## Examples\n\nCreate plain text from `Paragraph` Node and get original position from plain text.\n\n```js\nimport assert from \"assert\";\nimport { StringSource } from \"textlint-util-to-string\";\nconst report = function (context) {\n    const { Syntax, report, RuleError } = context;\n    return {\n        // \"This is [Example！？](http://example.com/)\"\n        [Syntax.Paragraph](node) {\n            const source = new StringSource(node);\n            const text = source.toString(); // =\u003e \"This is Example！？\"\n            // \"Example\" is located at the index 8 in the plain text\n            //  ^\n            const index1 = result.indexOf(\"Example\");\n            assert.strictEqual(index1, 8);\n            // The \"Example\" is located at the index 9 in the original text\n            assert.strictEqual(source.originalIndexFromIndex(index1), 9);\n            assert.deepStrictEqual(source.originalPositionFromPosition({\n                line: 1,\n                column: 8\n            }), {\n                line: 1,\n                column: 9\n            });\n\n            // Another example with \"！？\", which is located at 15 in the plain text\n            // and at 16 in the original text\n            const index2 = result.indexOf(\"！？\");\n            assert.strictEqual(index2, 15);\n            assert.strictEqual(source.originalIndexFromIndex(index2), 16);\n        }\n    }\n};\n```\n\n### Integration with sentence-splitter\n\n[sentence-splitter](https://github.com/textlint-rule/sentence-splitter) splits a paragraph into sentences.\nYou can pass the Sentence node to `StringSource` to get the plain text of the sentence.\n\n```ts\nimport assert from \"assert\";\nimport { splitAST, SentenceSplitterSyntax } from \"sentence-splitter\";\nimport { StringSource } from \"textlint-util-to-string\";\nimport type { TextlintRuleModule } from \"@textlint/types\";\nconst report: TextlintRuleModule\u003cOptions\u003e = function (context) {\n    const { Syntax, report, RuleError } = context;\n    return {\n        // \"First sentence. Second sentence.\"\n        [Syntax.Paragraph](node) {\n          // { children: [Sentence, WhiteSpace, Sentence] }\n          const sentenceRoot = splitAST(node);\n          // [\"First sentence.\" node, \"Second sentence.\" node]\n          const sentences = sentenceRoot.children.filter((node) =\u003e node.type === SentenceSplitterSyntax.Sentence);\n          for (const sentence of sentences) {\n            const sentenceSource = new StringSource(sentence);\n            const sentenceText = sentenceSource.toString();\n            console.log(sentenceText);\n            const sentenceIndex = sentenceText.indexOf(\"sentence\");\n            const originalSentenceIndex = sentenceSource.originalIndexFromIndex(sentenceIndex);\n            console.log({ sentenceIndex, originalSentenceIndex });\n          }\n        }\n    }\n};\nexport default report;\n```\n\n## Rules that use this library\n\n- [textlint-rule-first-sentence-length: textlint rule that limit maximum length of First sentence of the section.](https://github.com/textlint-rule/textlint-rule-first-sentence-length)\n- [textlint-rule-en-max-word-count: textlint rule that specify the maximum word count of a sentence.](https://github.com/textlint-rule/textlint-rule-en-max-word-count)\n- [textlint-rule-spellchecker: textlint rule to check spellings with native spellchecker](https://github.com/nodaguti/textlint-rule-spellchecker)\n\n\n## FAQ\n\n### Why return relative position from rootNode?\n\n```js\nconst AST = {...}\nconst rootNode = AST.children[10];\nconst source = new StringSource(rootNode);\nsource.originalIndexFor(0); // should be 0\n```\n\nTo return relative position easy to compute position(We think).\n\nOne space has a single absolute position, The other should be relative position.\n\n## Related Libraries\n\n- \u003chttps://github.com/textlint/textlint/wiki/Collection-of-textlint-rule#rule-libraries\u003e\n\n## Tests\n\n    npm test\n\n## Contributing\n\n1. Fork it!\n2. Create your feature branch: `git checkout -b my-new-feature`\n3. Commit your changes: `git commit -am 'Add some feature'`\n4. Push to the branch: `git push origin my-new-feature`\n5. Submit a pull request :D\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftextlint%2Ftextlint-util-to-string","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftextlint%2Ftextlint-util-to-string","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftextlint%2Ftextlint-util-to-string/lists"}