Skip to content

Commit 2c7b060

Browse files
steff456steff456
authored
Add support for reviving a JSON serialized regular expression (#522)
* Add RegExp reviver * Add to the examples and benchmark * Fix tests
1 parent 636dbb8 commit 2c7b060

File tree

10 files changed

+673
-0
lines changed

10 files changed

+673
-0
lines changed

‎lib/node_modules/@stdlib/regexp/reviver/README.md

+124
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2022 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# reviveRegExp
22+
23+
> Revive a JSON-serialized [regular expression][regexp].
24+
25+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
26+
27+
<section class="intro">
28+
29+
</section>
30+
31+
<!-- /.intro -->
32+
33+
<!-- Package usage documentation. -->
34+
35+
<section class="usage">
36+
37+
## Usage
38+
39+
```javascript
40+
var reviveRegExp = require( '@stdlib/regexp/reviver' );
41+
```
42+
43+
#### reviveRegExp( key, value )
44+
45+
Revives a JSON-serialized [regular expression][regexp].
46+
47+
```javascript
48+
var str = '{"type":"RegExp","pattern":"ab+c","flags":""}';
49+
50+
var regex = JSON.parse( str, reviveRegExp );
51+
// returns <RegExp>
52+
```
53+
54+
For details on the JSON serialization format, see [regexp-to-json][@stdlib/regexp/to-json].
55+
56+
</section>
57+
58+
<!-- /.usage -->
59+
60+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
61+
62+
<section class="examples">
63+
64+
## Examples
65+
66+
```javascript
67+
var regex2json = require( '@stdlib/regexp/to-json' );
68+
var reviveRegExp = require( '@stdlib/regexp/reviver' );
69+
70+
var regex = /ab+c/;
71+
var json = regex2json( regex );
72+
/* returns
73+
{
74+
'type': 'RegExp',
75+
'pattern': 'ab+c',
76+
'flags': ''
77+
}
78+
*/
79+
80+
var str = JSON.stringify( json );
81+
// returns '{"type":"RegExp","pattern":"ab+c","flags":""}'
82+
83+
var regex2 = JSON.parse( str, reviveRegExp );
84+
// returns <RegExp>
85+
86+
var bool = ( String( regex ) === String( regex2 ) );
87+
// returns true
88+
```
89+
90+
</section>
91+
92+
<!-- /.examples -->
93+
94+
<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
95+
96+
<section class="references">
97+
98+
</section>
99+
100+
<!-- /.references -->
101+
102+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
103+
104+
<section class="related">
105+
106+
</section>
107+
108+
<!-- /.related -->
109+
110+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
111+
112+
<section class="links">
113+
114+
<!-- <related-links> -->
115+
116+
[regexp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
117+
118+
[@stdlib/regexp/to-json]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/regexp/to-json
119+
120+
<!-- </related-links> -->
121+
122+
</section>
123+
124+
<!-- /.links -->

‎lib/node_modules/@stdlib/regexp/reviver/benchmark/benchmark.js

+117
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2022 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
// MODULES //
22+
23+
var bench = require( '@stdlib/bench' );
24+
var parseJSON = require( '@stdlib/utils/parse-json' );
25+
var regex2json = require( '@stdlib/regexp/to-json' );
26+
var pkg = require( './../package.json' ).name;
27+
var reviver = require( './../lib' );
28+
29+
30+
// MAIN //
31+
32+
bench( pkg, function benchmark( b ) {
33+
var values;
34+
var json;
35+
var o;
36+
var i;
37+
38+
values = [
39+
/beep/,
40+
/boop/,
41+
/.*/,
42+
/ab+c/
43+
];
44+
45+
b.tic();
46+
for ( i = 0; i < b.iterations; i++ ) {
47+
json = JSON.stringify( regex2json( values[ i%values.length ] ) );
48+
o = parseJSON( json, reviver );
49+
if ( typeof o !== 'object' ) {
50+
b.fail( 'should return an object' );
51+
}
52+
}
53+
b.toc();
54+
if ( typeof o !== 'object' ) {
55+
b.fail( 'should return an object' );
56+
}
57+
b.pass( 'benchmark finished' );
58+
b.end();
59+
});
60+
61+
bench( pkg+'::no_reviver', function benchmark( b ) {
62+
var values;
63+
var json;
64+
var o;
65+
var i;
66+
67+
values = [
68+
/beep/,
69+
/boop/,
70+
/.*/,
71+
/ab+c/
72+
];
73+
74+
b.tic();
75+
for ( i = 0; i < b.iterations; i++ ) {
76+
json = JSON.stringify( regex2json( values[ i%values.length ] ) );
77+
o = parseJSON( json );
78+
if ( typeof o !== 'object' ) {
79+
b.fail( 'should return an object' );
80+
}
81+
}
82+
b.toc();
83+
if ( typeof o !== 'object' ) {
84+
b.fail( 'should return an object' );
85+
}
86+
b.pass( 'benchmark finished' );
87+
b.end();
88+
});
89+
90+
bench( pkg+'::no_reviver,built-in', function benchmark( b ) {
91+
var values;
92+
var json;
93+
var o;
94+
var i;
95+
96+
values = [
97+
/beep/,
98+
/boop/,
99+
/.*/,
100+
/ab+c/
101+
];
102+
103+
b.tic();
104+
for ( i = 0; i < b.iterations; i++ ) {
105+
json = JSON.stringify( regex2json( values[ i%values.length ] ) );
106+
o = JSON.parse( json );
107+
if ( typeof o !== 'object' ) {
108+
b.fail( 'should return an object' );
109+
}
110+
}
111+
b.toc();
112+
if ( typeof o !== 'object' ) {
113+
b.fail( 'should return an object' );
114+
}
115+
b.pass( 'benchmark finished' );
116+
b.end();
117+
});

‎lib/node_modules/@stdlib/regexp/reviver/docs/repl.txt

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{{alias}}( key, value )
2+
Revives a JSON-serialized regular expression.
3+
4+
Parameters
5+
----------
6+
key: string
7+
Key.
8+
9+
value: any
10+
Value.
11+
12+
Returns
13+
-------
14+
out: any
15+
Value or regular expression.
16+
17+
Examples
18+
--------
19+
> var str = '{"type":"RegExp","pattern":"ab+c","flags":""}';
20+
> var err = JSON.parse( str, {{alias}} )
21+
<RegExp>
22+
23+
See Also
24+
--------

‎lib/node_modules/@stdlib/regexp/reviver/docs/types/index.d.ts

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
/*
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2022 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
// TypeScript Version: 2.0
20+
21+
/**
22+
* Revives a JSON-serialized regular expression.
23+
*
24+
* @param key - key
25+
* @param value - value
26+
* @returns value or regular expression
27+
*
28+
* @example
29+
* var str = '{"type":"RegExp","pattern":"ab+c","flags":""}';
30+
* var regex = JSON.parse( str, reviver );
31+
* // returns <RegExp>
32+
*/
33+
declare function reviver( key: string, value: any ): any;
34+
35+
36+
// EXPORTS //
37+
38+
export = reviver;

‎lib/node_modules/@stdlib/regexp/reviver/docs/types/test.ts

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
/*
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2022 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
import reviver = require( './index' );
20+
21+
22+
// TESTS //
23+
24+
// The function can be used to revive a serialized object...
25+
{
26+
JSON.parse( '{"type":"RegExp","pattern":"ab+c","flags":""}', reviver ); // $ExpectType any
27+
}
28+
29+
// The function does not compile if provided a first argument that is not a string...
30+
{
31+
reviver( true, 1 ); // $ExpectError
32+
reviver( false, 1 ); // $ExpectError
33+
reviver( null, 1 ); // $ExpectError
34+
reviver( undefined, 1 ); // $ExpectError
35+
reviver( 5, 1 ); // $ExpectError
36+
reviver( [], 1 ); // $ExpectError
37+
reviver( {}, 1 ); // $ExpectError
38+
reviver( ( x: number ): number => x, 1 ); // $ExpectError
39+
}
40+
41+
// The function does not compile if provided insufficient arguments...
42+
{
43+
reviver(); // $ExpectError
44+
reviver( 'beep' ); // $ExpectError
45+
}

‎lib/node_modules/@stdlib/regexp/reviver/examples/index.js

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2022 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
var regex2json = require( '@stdlib/regexp/to-json' );
22+
var reviveRegExp = require( './../lib' );
23+
24+
var regex = /ab+c/;
25+
var json = regex2json( regex );
26+
/* returns
27+
{
28+
'type': 'RegExp',
29+
'pattern': 'ab+c',
30+
'flags': ''
31+
}
32+
*/
33+
34+
var str = JSON.stringify( json );
35+
// returns '{"type":"RegExp","pattern":"ab+c","flags":""}'
36+
37+
var regex2 = JSON.parse( str, reviveRegExp );
38+
// returns <RegExp>
39+
40+
console.log( String( regex ) === String( regex2 ) );
41+
// => true

0 commit comments

Comments
 (0)