diff --git a/docs/_snippets/features/text-transformation-extended.js b/docs/_snippets/features/text-transformation-extended.js index f6e9eb5..8d24ff6 100644 --- a/docs/_snippets/features/text-transformation-extended.js +++ b/docs/_snippets/features/text-transformation-extended.js @@ -17,9 +17,9 @@ ClassicEditor transformations: { remove: [ // Don't use the transformations from the - // 'symbols' and 'mathematical' groups. + // 'symbols' and 'quotes' groups. 'symbols', - 'mathematical', + 'quotes', // As well as the following transformations. 'arrowLeft', @@ -33,10 +33,20 @@ ClassicEditor { from: ':tada:', to: '🎉' }, // You can also define patterns using regexp. - // Note: the pattern must end with `$`. - // The following (naive) rule will remove @ from emails. - // For example, user@example.com will become user.at.example.com. - { from: /([a-z-]+)@([a-z]+\.[a-z]{2,})$/i, to: '$1.at.$2' } + // Note: the pattern must end with `$` and all its fragments must be wrapped + // with capturing groups. + // The following rule replaces ` "foo"` with ` «foo»`. + { + from: /(^|\s)(")([^"]*)(")$/, + to: [ null, '«', null, '»' ] + }, + + // Finally, you can define `to` as a callback. + // This (naive) rule will auto-capitalize first word after a period. + { + from: /(\. )([a-z])$/, + to: matches => [ null, matches[ 1 ].toUpperCase() ] + } ], } } diff --git a/docs/features/text-transformation.md b/docs/features/text-transformation.md index f521467..be2356c 100644 --- a/docs/features/text-transformation.md +++ b/docs/features/text-transformation.md @@ -101,9 +101,9 @@ ClassicEditor transformations: { remove: [ // Don't use the transformations from the - // 'symbols' and 'mathematical' groups. + // 'symbols' and 'quotes' groups. 'symbols', - 'mathematical', + 'quotes', // As well as the following transformations. 'arrowLeft', @@ -117,10 +117,20 @@ ClassicEditor { from: ':tada:', to: '🎉' }, // You can also define patterns using regexp. - // Note: the pattern must end with `$`. - // The following (naive) rule will remove @ from emails. - // For example, user@example.com will become user.at.example.com. - { from: /([a-z-]+)@([a-z]+\.[a-z]{2,})$/i, to: '$1.at.$2' } + // Note: the pattern must end with `$` and all its fragments must be wrapped + // with capturing groups. + // The following rule replaces ` "foo"` with ` «foo»`. + { + from: /(^|\s)(")([^"]*)(")$/, + to: [ null, '«', null, '»' ] + }, + + // Finally, you can define `to` as a callback. + // This (naive) rule will auto-capitalize first word after a period. + { + from: /(\. )([a-z])$/, + to: matches => [ null, matches[ 1 ].toUpperCase() ] + } ], } } @@ -129,7 +139,9 @@ ClassicEditor .catch( ... ); ``` -You can test the above configuration here: +You can read more about the format of transformation rules in {@link module:typing/texttransformation~TextTransformationDescription}. + +Test the rules defined above: {@snippet features/text-transformation-extended} diff --git a/src/texttransformation.js b/src/texttransformation.js index ba306d8..f73ef5a 100644 --- a/src/texttransformation.js +++ b/src/texttransformation.js @@ -233,23 +233,24 @@ function expandGroupsAndRemoveDuplicates( definitions ) { } /** - * Text transformation definition object. Describes what should be replace with what. + * Text transformation definition object. Describes what should be replaced with what. * - * Input value ("replace from") can be passed either as a `String` or a `RegExp` instance. + * The input value (`from`) can be passed either as a string or a regexp. * - * * If `String` is passed it will be simply checked if the end of the input matches it. - * * If `RegExp` is passed, all parts of it's parts have to be inside capturing groups. Also, since it is compared against the end of - * an input, it has to include `$` token to be correctly matched. See examples below. + * * If a string is passed it will be simply checked if the end of the input matches it. + * * If a regexp is passed, its entire length must be covered with capturing groups (e.g. `/(foo)(bar)$/`). + * Also, since it is compared against the end of the input, it has to end with `$` to be correctly matched. + * See examples below. * - * Output value ("replace to") can be passed either as a `String` or an `Array` or a `Function`. + * The output value (`to`) can be passed either as a string or an array or a function. * - * * If a `String` is passed, it will be used as a replacement value as-is. Note, that a `String` output value can be used only if - * the input value is a `String` too. - * * If an `Array` is passed it has to have the same number of elements as there are capturing groups in the input value `RegExp`. - * Each capture group will be replaced by a corresponding `String` from the passed `Array`. If given capturing group should not be replaced, - * use `null` instead of passing a `String`. - * * If a `Function` is used, it should return an array as described above. The function is passed one parameter - an array with matches - * for the input value `RegExp`. See examples below. + * * If a string is passed, it will be used as a replacement value as-is. Note, that a string output value can be used only if + * the input value is a string too. + * * If an array is passed it has to have the same number of elements as there are capturing groups in the input value regexp. + * Each capture group will be replaced by a corresponding string from the passed array. If given capturing group should not be replaced, + * use `null` instead of passing a string. + * * If a function is used, it should return an array as described above. The function is passed one parameter — an array with matches + * by the regexp. See the examples below. * * Simple string-to-string replacement: * @@ -259,7 +260,7 @@ function expandGroupsAndRemoveDuplicates( definitions ) { * the text inside quotes are not replaced (`null` passed as the first and the third value in `to` parameter): * * { - * from: /(\\s)(")([^"]*)(")$/, + * from: /(^|\s)(")([^"]*)(")$/, * to: [ null, '“', null, '”' ] * } * @@ -303,7 +304,7 @@ function expandGroupsAndRemoveDuplicates( definitions ) { * - `ellipsis`: transforms `...` to `…` * - `enDash`: transforms ` -- ` to ` – ` * - `emDash`: transforms ` --- ` to ` — ` - * * Quotations (group name: `quotations`) + * * Quotations (group name: `quotes`) * - `quotesPrimary`: transforms `"Foo bar"` to `“Foo bar”` * - `quotesSecondary`: transforms `'Foo bar'` to `‘Foo bar’` * * Symbols (group name: `symbols`)