Node Wandbox API

Access Social Compilation Service Wandbox via API from Node.js.

All rights reserved to planeshifter https://www.npmjs.com/~planeshifter -- https://github.com/Planeshifter

Installation

$ npm install api-wandbox

Usage

var runWandbox = require( 'api-wandbox' );

runWandbox( [dest,] src[, opts], clbk )

Compile and run programs on Wandbox. src has to be the path of the source file that Wandbox should compile. Results of API call are passed to clbk, a callback function which has an error and result parameter, and optionally saved to the file specified in dest. To change the default compiler options, an options object can be supplied (opts).

/* FILE: code.cpp
	#include <iostream>
	int main() {
		std::cout << "All is well" << std::endl;
	}
*/

// Pass results to callback function...
runWandbox( './code.cpp', clbk );

// Save results to JSON file...
runWandbox( './output.json', '/code.cpp', clbk );

function clbk( error, results ) {
	if ( error ) {
		throw new Error( error.message );
	}
	var out = results;
	/* OUTPUT:
		{
			program_message: 'All is well\n',
			program_output: 'All is well\n',
			status: '0'
		}
	*/
}

Per Node.js convention, the callback function receives two arguments: err and res. err will be an error object in case the GET request is not successful and null otherwise, in which case res will hold the results from running the code on Wandbox. According to the Wandbox API documentation, the result object might have the following key-value pairs:

• status: Exit code
• signal: Signal message
• compiler_output: stdout at compiling
• compiler_error: stderr at compiling
• compiler_message: merged messages compiler_output and compiler_error
• program_output: stdout at runtime
• program_error: stderr at runtime
• program_message: merged messages program_output and program_error

If save option is set to true, the result in addition have the following key-value pairs:

• permlink: permlink you can pass to GET /permlink/:link.
• url URL to display on browser.

runWandbox.fromString( [dest,] code[, opts], clbk )

Directly compile and execute code in a source code string.

runWandbox.fromString( '#include <iostream>\nint main() {\n\tstd::cout << "All is well" << std::endl;}', clbk );

function clbk( error, results ) {
	if ( error ) {
		throw new Error( error.message );
	}
	var out = results;
}

The two exported functions accept the following options:

• compiler: name of used compiler. Default: 'gcc-head'.
• codes: additional codes, objects with file and code keys. Default: [].
• options: used options for a compiler joined by comma. Default: ''.
• stdin: standard input. Default: ''.
• compiler-option-raw: additional compile-time options joined by line-break. Default: ''.
• runtime-option-raw: additional run-time options joined by line-break. Default: ''.
• save: boolean indicating whether permanent link should be generated. Default: false.

To specify which compiler to use, set the compiler option.

var code = 'print("I can also run Python.")';

runWandbox.fromString( code, { 'compiler': 'python-3.5.0' }, function clbk( errror, results ) {
	var out = results;
	/*
		{
			program_message: 'I can also run Python.\n',
			program_output: 'I can also run Python.\n',
			status: '0'
		}
	*/
});

To specify compile options, supply a comma-separated list to options.

var code = '#include <iostream>\r\n int main() { int x = 0; std::cout << "hoge" << std::endl; }';

runWandbox.fromString( code, { 'options': 'warning,gnu++1y' }, function clbk( error, results ) {
	var out = res;
	/*
		{ compiler_error: 'prog.cc: In function \'int main()\':\nprog.cc:2:19: warning: unused variable \'x\' [-Wunused-variable]\n  int main() { int x = 0; std::cout << "hoge" << std::endl; }\n                   ^\n',
		  compiler_message: 'prog.cc: In function \'int main()\':\nprog.cc:2:19: warning: unused variable \'x\' [-Wunused-variable]\n  int main() { int x = 0; std::cout << "hoge" << std::endl; }\n                   ^\n',
		  program_message: 'hoge\n',
		  program_output: 'hoge\n',
		  status: '0' }
	*/
});

To generate a permanent link to the compiled program, set save to true.

var code = 'print("I can also run Python.")';
runWandbox.fromString( code, {
	'compiler': 'python-3.5.0',
	'save': true
}, function clbk( error, results ) {
	var out = results;
	/*
		{
			permlink: 'hcx4qh0WIkX2YDps',
			program_message: 'I can also run Python.\n',
			program_output: 'I can also run Python.\n',
			status: '0',
			url: 'http://melpon.org/wandbox/permlink/hcx4qh0WIkX2YDps'
		}
	*/
});

Examples

var runWandbox = require( 'api-wandbox' );

// String:

var code = '#include <iostream>\nint main() {\n\tstd::cout << "All is well" << std::endl;}';
runWandbox.fromString( code, clbk );

// File:

// Pass result to callback function...
runWandbox( './examples/fixtures/code.cpp', clbk );

// Save output to file...
runWandbox( './examples/fixtures/output.json', './examples/fixtures/code.cpp', clbk );

function clbk( error, results ) {
	if ( error ) {
		throw new Error( error.message );
	}
	console.log( results );
}

To run the example code from the top-level application directory,

$ DEBUG=* node ./examples/index.js

CLI

Installation

To use the module as a general utility, install the module globally

$ npm install -g api-wandbox

Usage

Usage: runWandbox [options] src

Options:

  -h,  --help                Print this message.
  -V,  --version             Print the package version.
       --file                Boolean indicating whether src is a file path or code to be evaluated. Default: false.
       --compiler            Name of used compiler. Default: gcc-head.
       --options             Used options for a compiler joined by comma. Default: boost-1.60,warning,gnu++1y.
       --codes               Additional codes, objects with `file` and `code` keys. Default: [].
       --save                Boolean indicating whether permanent link should be generated. Default: false.
       --stdin               Standard input.
       --compiler-option-raw Additional compile-time options joined by line-break. Default: "".
       --runtime-option-raw  Additional run-time options joined by line-break. Default: "".
  -o,  --output file          Output file path.

Examples

Setting the compiler using the command-line option:

$ DEBUG=* runWandbox --compiler <compiler> <code comes here>
# => '[{...},{...},...]'

For local installations, modify the command to point to the local installation directory; e.g.,

$ DEBUG=* ./node_modules/.bin/runWandbox --file --compiler <compiler> <file_path comes here>
# => '[{...},{...},...]'

Or, if you have cloned this repository and run npm install, modify the command to point to the executable; e.g.,

$ DEBUG=* node ./bin/cli --compiler <compiler> <code comes here>
# => '[{...},{...},...]'

Tests

Unit

This repository uses tape for unit tests. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

Browser Support

This repository uses Testling for browser testing. To run the tests in a (headless) local web browser, execute the following command in the top-level application directory:

$ make test-browsers

To view the tests in a local web browser,

$ make view-browser-tests

License

MIT license.

Copyright

Copyright © 2016. Philipp Burckhardt.