Refactor dirname regular expression package

Author: Planeshifter

lib/node_modules/@stdlib/regexp/dirname/README.md

@@ -27,28 +27,54 @@ limitations under the License.
 ## Usage
 
 ```javascript
-var RE_DIRNAME = require( '@stdlib/regexp/dirname' );
+var reDirname = require( '@stdlib/regexp/dirname' );
 ```
 
-#### RE_DIRNAME
+#### reDirname( \[platform] )
 
-[Regular expression][regexp] to capture a path [dirname][dirname].
+Returns a [regular expression][regexp] to capture a path [dirname][dirname].
 
-#### RE_DIRNAME.posix
+```javascript
+var RE = reDirname();
+// returns <RegExp>
+
+RE = reDirname( 'posix' );
+// returns <RegExp>
+
+var dir = RE.exec( '/foo/bar/index.js' )[ 1 ];
+// returns '/foo/bar'
+
+RE = reDirname( 'win32' );
+// returns <RegExp>
+
+dir = RE.exec( 'C:\\foo\\bar\\index.js' )[ 1 ];
+// returns 'C:\\foo\\bar'
+```
+
+#### reBasename.REGEXP
+
+[Regular expression][regexp] to capture a path dirname.
+
+```javascript
+var bool = ( reDirname.REGEXP.toString() === reDirname().toString() );
+// returns true
+```
+
+#### reDirname.REGEXP_POSIX
 
 [Regular expression][@stdlib/regexp/dirname-posix] to capture a [POSIX][posix] path dirname. 
 
 ```javascript
-var dir = RE_DIRNAME.posix.exec( '/foo/bar/index.js' )[ 1 ];
+var dir = reDirname.REGEXP_POSIX.exec( '/foo/bar/index.js' )[ 1 ];
 // returns '/foo/bar'
 ```
 
-#### RE_DIRNAME.win32
+#### reDirname.REGEXP_WIN32
 
 [Regular expression][@stdlib/regexp/dirname-windows] to capture a Windows path dirname. 
 
 ```javascript
-var dir = RE_DIRNAME.win32.exec( 'C:\\foo\\bar\\index.js' )[ 1 ];
+var dir = reDirname.REGEXP_WIN32.exec( 'C:\\foo\\bar\\index.js' )[ 1 ];
 // returns 'C:\\foo\\bar'
 ```
 
@@ -60,7 +86,7 @@ var dir = RE_DIRNAME.win32.exec( 'C:\\foo\\bar\\index.js' )[ 1 ];
 
 ## Notes
 
--   The main exported [regular expression][regexp] is [platform][@stdlib/assert/is-windows]-dependent. If the current process is running on Windows, `re === re.win32`; otherwise, `re === re.posix`.
+-   The as `REGEXP` exported [regular expression][regexp] is [platform][@stdlib/assert/is-windows]-dependent. If the current process is running on Windows, `REGEXP === REGEXP_WIN32`; otherwise, `REGEXP === REGEXP_POSIX`.
 
 </section>
 
@@ -73,18 +99,18 @@ var dir = RE_DIRNAME.win32.exec( 'C:\\foo\\bar\\index.js' )[ 1 ];
 <!-- eslint no-undef: "error" -->
 
 ```javascript
-var RE_DIRNAME = require( '@stdlib/regexp/dirname' );
-
+var reDirname = require( '@stdlib/regexp/dirname' );
+var RE_DIRNAME = reDirname();
 var dir;
 
 // Assuming a POSIX platform...
 dir = RE_DIRNAME.exec( '/foo/bar/index.js' )[ 1 ];
 // returns '/foo/bar'
 
-dir = RE_DIRNAME.posix.exec( '/foo/bar/home.html' )[ 1 ];
+dir = reDirname.REGEXP_POSIX.exec( '/foo/bar/home.html' )[ 1 ];
 // returns '/foo/bar'
 
-dir = RE_DIRNAME.win32.exec( 'C:\\foo\\bar\\home.html' )[ 1 ];
+dir = reDirname.REGEXP_WIN32.exec( 'C:\\foo\\bar\\home.html' )[ 1 ];
 // returns 'C:\\foo\\bar'
 ```
 

lib/node_modules/@stdlib/regexp/dirname/benchmark/benchmark.js

@@ -25,7 +25,7 @@ var IS_WINDOWS = require( '@stdlib/assert/is-windows' );
 var isString = require( '@stdlib/assert/is-string' ).isPrimitive;
 var fromCodePoint = require( '@stdlib/string/from-code-point' );
 var pkg = require( './../package.json' ).name;
-var RE_DIRNAME = require( './../lib' );
+var reDirname = require( './../lib' );
 
 
 // MAIN //
@@ -39,7 +39,7 @@ bench( pkg, function benchmark( b ) {
 		b.tic();
 		for ( i = 0; i < b.iterations; i++ ) {
 			str = 'C:\\foo\\bar\\beep\\boop'+fromCodePoint( 97 + (i%26) )+'.js';
-			out = RE_DIRNAME.exec( str );
+			out = reDirname.REGEXP.exec( str );
 			if ( !out || !isString( out[ 1 ] ) ) {
 				b.fail( 'should capture a dirname' );
 			}
@@ -49,7 +49,7 @@ bench( pkg, function benchmark( b ) {
 		b.tic();
 		for ( i = 0; i < b.iterations; i++ ) {
 			str = '/foo/bar/beep/boop'+fromCodePoint( 97 + (i%26) )+'.js';
-			out = RE_DIRNAME.exec( str );
+			out = reDirname.REGEXP.exec( str );
 			if ( !out || !isString( out[ 1 ] ) ) {
 				b.fail( 'should capture a dirname' );
 			}
@@ -71,7 +71,7 @@ bench( pkg+':posix', function benchmark( b ) {
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
 		str = '/foo/bar/beep/boop'+fromCodePoint( 97 + (i%26) )+'.js';
-		out = RE_DIRNAME.posix.exec( str );
+		out = reDirname.REGEXP_POSIX.exec( str );
 		if ( !out || !isString( out[ 1 ] ) ) {
 			b.fail( 'should capture a dirname' );
 		}
@@ -92,7 +92,7 @@ bench( pkg+':win32', function benchmark( b ) {
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
 		str = 'C:\\foo\\bar\\beep\\boop'+fromCodePoint( 97 + (i%26) )+'.js';
-		out = RE_DIRNAME.win32.exec( str );
+		out = reDirname.REGEXP_WIN32.exec( str );
 		if ( !out || !isString( out[ 1 ] ) ) {
 			b.fail( 'should capture a dirname' );
 		}

lib/node_modules/@stdlib/regexp/dirname/docs/repl.txt

@@ -1,27 +1,60 @@
 
-{{alias}}
-    Regular expression to capture a path dirname.
+{{alias}}( [platform] )
+    Returns a regular expression to capture a path dirname.
 
     The regular expression is platform-dependent. If the current process is
-    running on Windows, the regular expression is `*.win32`; otherwise,
-    `*.posix`.
+    running on Windows, the regular expression is `*.REGEXP_WIN32`; otherwise,
+    `*.REGEXP_POSIX`.
+
+    Parameters
+    ----------
+    platform: string (optional)
+        Path platform (either `posix` or `win32`).
+
+    Returns
+    -------
+    re: RegExp
+        Regular expression.
+
+    Examples
+    --------
+    > var RE = {{alias}}()
+    <RegExp>
+    > var RE_POSIX = {{alias}}( 'posix' );
+    > var dir = RE_POSIX.exec( '/foo/bar/index.js' )[ 1 ]
+    '/foo/bar'
+    > var RE_WIN32 = {{alias}}( 'win32' );
+    > var dir = RE_WIN32.exec( 'C:\\foo\\bar\\index.js' )[ 1 ]
+    'C:\\foo\\bar'
+    > var str = RE.toString();
+    > var bool = ( str === RE_POSIX.toString() || str === RE_WIN32.toString() )
+    true
+
+
+{{alias}}.REGEXP
+    Regular expression to capture a path dirname.
+
+    Examples
+    --------
+    > var RE = {{alias}}.REGEXP
+    <RegExp>
 
 
-{{alias}}.posix
+{{alias}}.REGEXP_POSIX
     Regular expression to capture a POSIX path dirname.
 
     Examples
     --------
-    > var dir = {{alias}}.exec( '/foo/bar/index.js' )[ 1 ]
+    > var dir = {{alias}}.REGEXP_POSIX.exec( '/foo/bar/index.js' )[ 1 ]
     '/foo/bar'
 
 
-{{alias}}.win32
+{{alias}}.REGEXP_WIN32
     Regular expression to capture a Windows path dirname.
 
     Examples
     --------
-    > var dir = {{alias}}.exec( 'C:\\foo\\bar\\index.js' )[ 1 ]
+    > var dir = {{alias}}.REGEXP_WIN32.exec( 'C:\\foo\\bar\\index.js' )[ 1 ]
     'C:\\foo\\bar'
 
     See Also

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

@@ -0,0 +1,95 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2021 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+// TypeScript Version: 2.0
+
+type PLATFORM = 'win32' | 'posix';
+
+/**
+* Interface for a regular expression to capture a path dirname.
+*/
+interface ReDirname {
+	/**
+	* Returns a regular expression to capture a path dirname.
+	*
+	* @param platform - path platform (`win32` or `posix`)
+	* @returns regular expression
+	*
+	* @example
+	* // Returns a platform-dependent regular expression when no `platform` is supplied:
+	* var RE = reDirname();
+	* // returns <RegExp>
+	*
+	* var bool = ( RE === reDirname( 'win32' ) ) || ( RE === reDirname( 'posix' ) );
+	* // returns true
+	*/
+	( platform?: PLATFORM ): RegExp;
+
+	/**
+	* Regular expression to capture a path dirname.
+	*
+	* @example
+	* var RE = reDirname.REGEXP;
+	* // returns <RegExp>
+	*/
+	REGEXP: RegExp;
+
+	/**
+	* Regular expression to capture a Windows path dirname.
+	*
+	* @example
+	* var dir = reDirname.REGEXP_WIN32.exec( 'C:\\foo\\bar\\index.js' )[ 1 ];
+	* // returns 'C:\\foo\\bar'
+	*/
+	REGEXP_WIN32: RegExp;
+
+	/**
+	* Regular expression to capture a POSIX path dirname.
+	*
+	* @example
+	* var dir = reDirname.REGEXP_POSIX.exec( 'foo/bar/index.js' )[ 1 ]
+	* // returns 'foo/bar'
+	*/
+	REGEXP_POSIX: RegExp;
+}
+
+/**
+* Returns a regular expression to capture a path dirname.
+*
+* @returns regular expression
+*
+* @example
+* var RE_DIRNAME = reDirname();
+* // returns <RegExp>
+*
+* @example
+* var RE_DIRNAME = reDirname( 'posix' );
+* var dir = RE_DIRNAME.exec( '/foo/bar/index.js' )[ 1 ];
+* // returns '/foo/bar/'
+*
+* @example
+* var RE_DIRNAME = reDirname( 'win32' );
+* var dir = RE_DIRNAME.exec( 'C:\\foo\\bar\\index.js' )[ 1 ];
+* // returns 'C:\\foo\\bar'
+*/
+declare var reDirname: ReDirname;
+
+
+// EXPORTS //
+
+export = reDirname;

lib/node_modules/@stdlib/regexp/dirname/docs/types/test.ts

@@ -0,0 +1,63 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2021 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+import reDirname = require( './index' );
+
+
+// TESTS //
+
+// The function returns a regular expression...
+{
+	reDirname(); // $ExpectType RegExp
+	reDirname( 'win32' ); // $ExpectType RegExp
+	reDirname( 'posix' ); // $ExpectType RegExp
+}
+
+// The compiler throws an error if the function is provided an invalid argument...
+{
+	reDirname( 123 ); // $ExpectError
+	reDirname( 'abc' ); // $ExpectError
+	reDirname( [] ); // $ExpectError
+	reDirname( {} ); // $ExpectError
+	reDirname( true ); // $ExpectError
+	reDirname( false ); // $ExpectError
+	reDirname( ( x: number ): number => x ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided an unsupported number of arguments...
+{
+	reDirname( 'win32', 2 ); // $ExpectError
+}
+
+// Attached to main export is a `REGEXP` property that is a regular expression...
+{
+	// tslint:disable-next-line:no-unused-expression
+	reDirname.REGEXP; // $ExpectType RegExp
+}
+
+// Attached to main export is a `REGEXP_POSIX` property that is a regular expression...
+{
+	// tslint:disable-next-line:no-unused-expression
+	reDirname.REGEXP_POSIX; // $ExpectType RegExp
+}
+
+// Attached to main export is a `REGEXP_WIN32` property that is a regular expression...
+{
+	// tslint:disable-next-line:no-unused-expression
+	reDirname.REGEXP_WIN32; // $ExpectType RegExp
+}

lib/node_modules/@stdlib/regexp/dirname/examples/index.js

@@ -18,19 +18,19 @@
 
 'use strict';
 
-var RE_DIRNAME = require( './../lib' );
-
+var reDirname = require( './../lib' );
+var RE_DIRNAME = reDirname();
 var dir;
 
 // Assuming a POSIX platform...
 dir = RE_DIRNAME.exec( '/foo/bar/index.js' )[ 1 ];
 console.log( dir );
 // => '/foo/bar'
 
-dir = RE_DIRNAME.posix.exec( '/foo/bar/home.html' )[ 1 ];
+dir = reDirname.REGEXP_POSIX.exec( '/foo/bar/home.html' )[ 1 ];
 console.log( dir );
 // => '/foo/bar'
 
-dir = RE_DIRNAME.win32.exec( 'C:\\foo\\bar\\home.html' )[ 1 ];
+dir = reDirname.REGEXP_WIN32.exec( 'C:\\foo\\bar\\home.html' )[ 1 ];
 console.log( dir );
 // => 'C:\\foo\\bar'