feat: prototype for C source doctesting

lib/node_modules/@stdlib/_tools/doctest/c/bin/cli

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2026 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.
+*/
+
+'use strict';
+
+// MODULES //
+
+var resolve = require( 'path' ).resolve;
+var readFileSync = require( '@stdlib/fs/read-file' ).sync;
+var CLI = require( '@stdlib/cli/ctor' );
+var cdoctest = require( './../lib' );
+
+
+// MAIN //
+
+/**
+* Main execution sequence.
+*
+* @private
+* @returns {void}
+*/
+function main() {
+	var flags;
+	var args;
+	var opts;
+	var cli;
+
+	// Create a command-line interface:
+	cli = new CLI({
+		'pkg': require( './../package.json' ),
+		'options': require( './../etc/cli_opts.json' ),
+		'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), {
+			'encoding': 'utf8'
+		})
+	});
+
+	// Get any provided command-line options:
+	flags = cli.flags();
+	if ( flags.help || flags.version ) {
+		return;
+	}
+
+	// Get any provided command-line arguments:
+	args = cli.args();
+
+	if ( args.length === 0 ) {
+		return cli.error( new Error( 'insufficient arguments. Must provide one or more source file paths.' ) );
+	}
+
+	// Set up options:
+	opts = {
+		'files': args
+	};
+	if ( flags.compiler ) {
+		opts.compiler = flags.compiler;
+	}
+	if ( flags.include ) {
+		if ( typeof flags.include === 'string' ) {
+			opts.include = [ flags.include ];
+		} else {
+			opts.include = flags.include;
+		}
+	}
+	if ( flags.libpath ) {
+		if ( typeof flags.libpath === 'string' ) {
+			opts.libpath = [ flags.libpath ];
+		} else {
+			opts.libpath = flags.libpath;
+		}
+	}
+	if ( flags.library ) {
+		if ( typeof flags.library === 'string' ) {
+			opts.libraries = [ flags.library ];
+		} else {
+			opts.libraries = flags.library;
+		}
+	}
+	if ( flags.source ) {
+		if ( typeof flags.source === 'string' ) {
+			opts.sourceFiles = [ flags.source ];
+		} else {
+			opts.sourceFiles = flags.source;
+		}
+	}
+	if ( flags.timeout ) {
+		opts.timeout = parseInt( flags.timeout, 10 );
+	}
+	if ( flags.quiet ) {
+		opts.verbose = false;
+	}
+
+	cdoctest( opts, done );
+
+	/**
+	* Callback invoked upon completion.
+	*
+	* @private
+	* @param {(Error|null)} error - error object
+	* @param {Object} results - test results
+	* @returns {void}
+	*/
+	function done( error, results ) {
+		if ( error ) {
+			return cli.error( error );
+		}
+		console.log( '\n=== C Doctest Results ===' ); // eslint-disable-line no-console
+		console.log( 'Total: %d', results.total ); // eslint-disable-line no-console
+		console.log( 'Pass:  %d', results.pass ); // eslint-disable-line no-console
+		console.log( 'Fail:  %d', results.fail ); // eslint-disable-line no-console
+
+		if ( results.errors.length > 0 ) {
+			console.log( '\nErrors:' ); // eslint-disable-line no-console
+			var i;
+			for ( i = 0; i < results.errors.length; i++ ) {
+				console.log( '  - %s (line %d): %s', results.errors[ i ].file, results.errors[ i ].line || 0, results.errors[ i ].error ); // eslint-disable-line no-console
+			}
+		}
+		if ( results.fail > 0 ) {
+			process.exitCode = 1;
+		}
+	}
+}
+
+main();

lib/node_modules/@stdlib/_tools/doctest/c/docs/usage.txt

@@ -0,0 +1,2 @@
+
+Usage: c-doctest [options] <file> [<file> ...]

lib/node_modules/@stdlib/_tools/doctest/c/etc/cli_opts.json

@@ -0,0 +1,40 @@
+{
+	"string": [
+		"compiler",
+		"include",
+		"libpath",
+		"library",
+		"source"
+	],
+	"boolean": [
+		"help",
+		"version",
+		"quiet"
+	],
+	"alias": {
+		"help": [
+			"h"
+		],
+		"version": [
+			"V"
+		],
+		"compiler": [
+			"c"
+		],
+		"include": [
+			"I"
+		],
+		"libpath": [
+			"L"
+		],
+		"library": [
+			"l"
+		],
+		"source": [
+			"s"
+		],
+		"quiet": [
+			"q"
+		]
+	}
+}

lib/node_modules/@stdlib/_tools/doctest/c/lib/defaults.json

@@ -0,0 +1,17 @@
+{
+  "compiler": "gcc",
+  "flags": [
+    "-std=c99",
+    "-O2",
+    "-Wall"
+  ],
+  "libraries": [
+    "-lm"
+  ],
+  "include": [],
+  "libpath": [],
+  "sourceFiles": [],
+  "verbose": true,
+  "timeout": 120000,
+  "maxBuffer": 10485760
+}