build.js

/* eslint-disable no-sync */
'use strict';

// MODULES //

var logger = require( 'debug' );
var writeFile = require( 'fs' ).writeFileSync;
var resolvePath = require( 'path' ).resolve;
var getKeys = require( 'object-keys' ).shim();
var replace = require( '@stdlib/string/replace' );
var docs = require( '@stdlib/repl/help' );


// VARIABLES //

var debug = logger( 'repl:examples:build' );

// Examples output file path:
var EXAMPLES_OUTPUT = resolvePath( __dirname, '..', 'lib', 'db.js' );

// Output file preamble:
var PREAMBLE = '// This file is generated by scripts/build.js.\n\'use strict\';\n\n/* eslint-disable quotes, max-lines */\n\n';

// Identifier for inserting 'See Also' links:
var SEE_ALSO = '\n    See Also\n    --------\n';

// Identifier for an examples section:
var EXAMPLES = '    Examples';

// Identifier for an examples heading underline:
var EXAMPLES_UNDERLINE = '    --------';

// Regular expression for a line that starts with a space:
var RE_SPACE = /^\s/;

// Regular expression for a command prompt:
var RE_PROMPT = /^(\s{4}>\s*)/;

// Regular expression for a command continuation:
var RE_CONTINUATION = /^(\s{4}\.{3}\s)/;

// Regular expression for command input:
var RE_COMMAND_INPUT = /^(\s{4}(?:>|\.{3})\s*)/;

// Regular expression for a comment:
var RE_COMMENT = /^(\s{4}\/\/.+)/;

// Regular expression for indentation:
var RE_IDENTATION = /^(\s{4})/;

// Regular expression for indentation (global):
var RE_IDENTATION_GLOBAL = /^(\s{4})/g;

// Regular expression for variable declaration:
var RE_VAR_DECLARATION = /^(var\s+)/;


// FUNCTIONS //

/**
* Generates a hash for REPL examples.
*
* @private
* @param {Object} docs - hash containing REPL help text
*/
function createExamples( docs ) {
	var aliases;
	var alias;
	var fopts;
	var lines;
	var line;
	var acc;
	var txt;
	var out;
	var flg;
	var i;
	var j;

	fopts = {
		'encoding': 'utf8'
	};
	out = {};

	aliases = getKeys( docs );
	for ( i = 0; i < aliases.length; i++ ) {
		alias = aliases[ i ];

		debug( 'Loading REPL text: %s', alias );
		txt = docs[ alias ];

		debug( 'Extracting examples section.' );
		lines = txt.split( '\n' );
		flg = false;
		acc = '';

		// NOTE: the following only extracts the first example!!!
		for ( j = 0; j < lines.length; j++ ) {
			line = lines[ j ];
			if (
				line === EXAMPLES &&
				lines[ j+1 ] === EXAMPLES_UNDERLINE
			) {
				debug( 'Found an examples section.' );
				flg = true;
				acc = '';
				j += 1; // skip the next line
				continue;
			}
			if ( flg === false ) {
				continue;
			}
			if (
				line !== SEE_ALSO &&
				RE_SPACE.test( line )
			) {
				if ( RE_COMMAND_INPUT.test( line ) ) {
					line = replace( line, RE_PROMPT, '' );
					line = replace( line, RE_CONTINUATION, '' );
					line = replace( line, RE_IDENTATION_GLOBAL, '  ' );
					line = replace( line, RE_VAR_DECLARATION, '' ); // NOTE: the REPL silences output when declaring a variable. So we remove any variable declarations here.
					acc += line + '\n';
				} else if ( RE_COMMENT.test( line ) ) {
					line = replace( line, RE_IDENTATION, '' );
					acc += '\n' + line + '\n';
				}
			} else if ( line !== '' ) {
				debug( 'Finished extracting section.' );
				flg = false;
				break;
			}
		}
		if ( acc === '' ) {
			debug( 'Unable to extract an examples section.' );
		} else {
			out[ alias ] = acc;
		}
	}
	debug( 'Writing REPL example hash to file.' );
	out = PREAMBLE+'module.exports = '+JSON.stringify( out, null, '\t' )+';\n';
	writeFile( EXAMPLES_OUTPUT, out, fopts );
} // end FUNCTION createExamples()

/**
* Main execution sequence.
*
* @private
*/
function main() {
	debug( 'Generating REPL examples.' );
	createExamples( docs() );
} // end FUNCTION main()


// MAIN //

main();