runmany 0.4.1

A tool to run many programs written in many languages from one file.

RunMany

Intro | Installation | Usage | Syntax | Settings | About

A tool to run many programs written in many languages from one file.

Suppose you want to practice multiple programming languages at once. Normally you'd have to juggle multiple files or multiple projects, perhaps multiple IDEs. RunMany lets you write multiple programs in the same file using any programming languages you like, and then run them all at once.

For example, give RunMany this simple file:

Python:
    print("Hi")
JavaScript:
    console.log("Hi")
Rust:
    fn main() {
        println!("Hi");
    }

And it will number and run each program, giving this output:

************************************************************
1. Python
-------------------- output from line 2 --------------------
Hi


************************************************************
2. JavaScript
-------------------- output from line 4 --------------------
Hi


************************************************************
3. Rust
-------------------- output from line 6 --------------------
Hi


************************************************************
3/3 programs successfully run!
3/3 had the exact same stdout!
************************************************************

In general, RunMany can be used for:

• Crestomathy - Writing identically behaving programs in many languages, like on Rosetta Code. (example/output)
• Performance Testing - Timing different implementations of a program, even across languages. (example/output)
• Input Testing - Easily giving many combinations of argv or stdin input to programs. (example/output)
• Polyglots - Making esoteric code that can be executed in multiple languages at once. (example/output)

Overall RunMany is hopefully a good tool for anyone who wants to play with multiple programming languages at once.

Installation (supports Python 3.6+)

pip install runmany

If that doesn't work try pip3 install runmany or python -m pip install runmany or python3 -m pip install runmany.

PyPI Package Page | Bleeding edge version on TestPyPI

Usage

Running From Command Line

runmany myfile.many

More generally:

runmany [-h --help] [-j --json <settings-file>] [-o --output <output-file>] <input-file>

• <input-file> is the required .many file to run.
• <settings-json> is the optional .json file that defines how languages are run and how the output is formatted.
• <output-file> is the optional file to send the output to. When omitted output goes to stdout.

When a settings JSON file is not provided, the hardcoded settings JSON at the top of the .many file is used. If neither is present, or for any missing settings, default_settings.json is used as a fallback.

See the examples folder for some .many files to try. Note that RunMany expects the system to already have the necessary interpreters and compilers installed for the programming languages it runs. RunMany runs them internally with normal console commands.

By default, RunMany has preset commands for a handful of languages (Python, Python 2, JavaScript, TypeScript, Java, Kotlin, Rust, Go, C, C++, and C#) but these may fail depending on OS and system configuration. However, commands can be overridden and new languages can be added by modifying the settings JSON. See more information below.

Running From Python

from runmany import runmany, runmany_to_s, runmany_to_f

# Run to stdout
runmany('path/to/input.many', 'path/to/settings.json') # settings JSON is always optional

# Run to output file
runmany('path/to/input.many', 'path/to/settings.json', 'path/to/output.txt')

# Run to string
string = runmany_to_s('path/to/input.many', 'path/to/settings.json')

# Run to file object
with open('output.txt', 'w') as file_obj:
    runmany_to_f(file_obj, 'path/to/input.many', 'path/to/settings.json')

As with the command line, the settings JSON provided as an argument takes precedence over the one that may be at the top of the .many file, and default_settings.json is used as a fallback for all settings.

In each of the 3 runmany functions, the settings JSON argument may be given as a path to the .json file or a JSON-like Python dictionary.

Additionally, the .many file contents may be given as a string rather than a file path with from_string=True.

The function runmany.cmdline, which takes a list of command line arguments, is also present as an alternative to using the command line directly.

.many Syntax

The .many file format is what RunMany expects when given a file to run. (Though, of course, ".many" is not required as an extension.)

Principally, a .many file consists of unindented lines which are section headers that define the languages and context for the lines indented below them. Languages are given as a comma separated list and the 3 contexts are argv, stdin, and code. Section headers end with a colon.

Argv for Python, JavaScript:
    foo
Stdin for Python:
    bar
Python:
    import sys
    print(sys.argv[1] + input())  # will be "foobar"
JavaScript:
    console.log(process.argv[2])  // will be "foo"

The keywords Argv and Stdin are used to define the argument vector and standard input for a set of languages. Otherwise the section is assumed to be code.

So the RunMany program above will send "foo" to Python and JavaScript on argv, and "bar" to Python on stdin when it runs each language's code.

Importantly, a .many file always runs from top to bottom just-in-time, that is, the top lines will run normally even if the bottom lines are invalid syntax. For this reason, argv and stdin sections only apply to code sections that come after them.

Those are the essentials but read on for more details and nuance about the syntax of .many files. Notably the Also Section and hardcoded settings.

Also check syntax.many and the other examples for concrete syntax samples.

Syntax Specifics

---

Comments

% at the very start of a line makes an inline comment.

/% at the very start of a line up to a matching %/ at the very start of another line makes a multiline comment.

% this is a comment

/%
this is a block comment
%/

---

Section Syntax

A .many file can be split up into sections, each of which has an unindented header line that ends in a colon (:), and a potentially multiline string of content that can appear after the colon and on indented lines below the header. The indents must be either single tabs or 4 spaces and do not end up as part of the content.

Any whitespace just after the colon of the section header is ignored, so this is a working Code Section:

Python: import math
    print(math.pi)

As it corresponds to the Python program:

import math
print(math.pi)

As detailed below, only a few types of sections exist and some require comma (,) separated language lists in their headers. Language names are stripped of whitespace and matched to corresponding "name" keys in the languages arrays of the settings JSON.

Language names are not case-sensitive (Python is the same as python) but other keywords like Argv, Stdin, for, Also, and Exit are.

Language names cannot contain , or : and to be safe they should not start with Argv, Stdin, Also, Exit, or !.

---

Code Section

A Code Section starts right out with a comma separated list of languages and its content is the program to be run in those languages.

One language in the list is almost always sufficient unless you are writing polyglots,

JavaScript:
    console.log('This is some code that will be run in JS.')
Python, Python 2:
    print('This is some code that will be run in Python 3 and then Python 2.')

---

Argv Section

An Argv Section can either start Argv: to apply to all languages, or Argv for Language1, Language2, ...: to apply to the listed languages. Either way overwrites any previous argv set for those languages, but Also Sections can be used to supply a series of argvs.

The Argv Section's content is stripped of newlines and sent as the argument vector to all the subsequent programs from Code Sections for languages it applies to.

Argv:
    argv sent to all languages
Argv for Python, JavaScript:
    argv specifically sent to Python and Javascript

For argv to work the $argv placeholder must be placed properly into the command of the language.

---

Stdin Section

Almost exactly like Argv Sections but for stdin.

A Stdin Section can either start Stdin: to apply to all languages, or Stdin for Language1, Language2, ...: to apply to the listed languages. Either way overwrites any previous stdin set for those languages, but Also Sections can be used to supply series of stdins.

The Stdin Section's content is stripped of trailing newlines except one and sent as the standard input stream to all the subsequent programs from Code Sections for languages it applies to.

Stdin:
    stdin sent to all languages
Stdin for Python, JavaScript:
    stdin specifically sent to Python and Javascript

When a program expects stdin but there is no Stdin Section to give it, the stdin can be typed into the console normally.

---

Also Section

An Also Section starts with Also: (with no language list) and is a way to add a series of argvs or stdins to run, or to avoid repeating a Code Section header. It must not be the first section in the file because it needs to attach to the Code, Stdin, or Argv Section above it.

When below an Argv Section or Stdin Section, an Also Section adds an additional input to the list of argvs or stdins to run when applicable Code Sections are encountered.

For example, the final Python program here is run 6 times for all the combinations of argvs and stdins that apply to it (1A 1B 2A 2B 3A 3B):

Argv: 1
Also: 2
Also: 3

Stdin: A
Also:  B

Python:
    import sys
    print(sys.argv[1] + input())

This is the real power of the Also Section -- giving multiple argvs and stdins to a program without repeating code. Another example with output.

When below a Code Section, an Also Section is simply shorthand for repeating the Code Section's header.

For example, here, Also: behaves exactly the same as Python, Python 2: would:

Python, Python 2:
    print(123)
Also:
    print(456)
Also:
    print(789)

---

Disabling Sections

Putting ! at the very start of any section header will disable that section and any Also Sections attached to it.

!Python:
    # this is disabled
Also:
    # this is effectively disabled too

---

Hardcoded Settings

A settings JSON may be placed, indented, before the first section in a .many file. It is only used if a custom setting JSON is not otherwise provided as an argument, and only for the .many file it is in.

    {
        "show_time": true,
        "show_command": true
    }
Python:
    print('The time and command will now be shown.')

---

Exit Command

Exit. at the very start of a line by itself (possibly with trailing whitespace) will stop RunMany as if the file ended there.

Exit.
% nothing from here on will be run

---

Settings JSON

The settings JSON defines what languages RunMany can run and how it will run them. It also defines how the RunMany output will be formatted.

As mentioned, default_settings.json holds the default values for all settings which are automatically used if not otherwise present in a provided or hardcoded JSON.

Most settings are simple flags or values that can be set in the base settings JSON object. See List of Settings below.

The setting to add a custom language is the "languages" key which maps to an array of JSON objects we'll call language objects. Each language object must have a "name" string to identify it and a "command" string to run it (see command format). However, objects in "languages" with a matching "name" in the "default_languages" array will automatically inherit its other values, such as "command" and "ext". Most settings that can be set in the base settings JSON object are also inherited by the language objects and can be overridden.

For example, a settings JSON of

{
    "languages": [
        {"name": "Rust", "timeout": 5.0 }
    ],
    "show_code": true
}

will make Rust programs have a 5 second time limit rather than the default of 10, and "command" does not need to be present because Rust is already in the default "default_languages". The JSON also makes all languages show their code in the RunMany output due to "show_code": true in the base object.

You should never have to set "default_languages" in your custom settings JSON (though technically you can). Only set "languages".

List of Settings

All settings described and whether or not they they can be overridden in a language object in the "languages" array:

JSON Key	Type	Default	Overridable	Description
"timeout"	float	10.0	yes	The time limit of each program in seconds.
"stderr"	string	"nzec"	yes	"always" or true to always combine program stderr streams with stdout. "never" or false to always hide program stderr streams. "nzec" or null to only show stderr streams when programs have non-zero exit codes.
"ext"	string	""	yes	The file extension of a language including the dot. Best to always define in the language object.
"spacing"	int	1	yes	The number of blank lines to add after each run. Note that trailing newlines are not stripped from stdouts.
"show_time"	bool	false	yes	Whether the execution time of each program is shown.
"show_command"	bool	false	yes	Whether the command used to run each program is shown. Useful for debugging command setup for new languages.
"show_code"	bool	false	yes	Whether the source code of the program is shown.
"show_argv"	bool	true	yes	Whether the argv for the program is shown (when present and non-empty).
"show_stdin"	bool	true	yes	Whether the stdin for the program is shown (when present and not all blank lines).
"show_output"	bool	true	yes	Whether the output for the program is shown. This includes the stdout, and, depending on the "stderr" setting, the stderr.
"show_errors"	bool	true	no	Whether RunMany errors like !!!| RunMany Error: ... |!!! are sent to stderr or silenced.
"show_runs"	bool	true	no	Whether the list of runs is shown. This is usually the bulk of the output.
"show_stats"	bool	true	no	Whether the success and failure counts are shown after everything has run.
"show_equal"	bool	true	no	Whether the matching stdouts are compared and grouped after everything has run.

Command Format

The "command" key of a language object in the "languages" array defines the terminal command that is run to execute the language.

Placeholders like $file and $dir are used in a command to refer to the temporary file RunMany creates for the code of each program it runs, or the directory that file is stored in.

Placeholder	Portion of .../dir/file.ext
$rawdir	.../dir
$dir	".../dir"
$rawfile	.../dir/file.ext
$file	".../dir/file.ext"
$rawbranch	.../dir/file
$branch	".../dir/file"
$name	file.ext
$stem	file
$ext	.ext
$sep	/ (OS specific)
$argv	n/a - the argv is inserted here

Note that some placeholders are "quoted" and some are not. Some operating systems like Windows may have spaces in the path to temporary files so correct quoting is important.

If $ is not present anywhere in the command string, $file $argv is appended to it. For example, the command python is implicitly python $file $argv.

Check default_settings.json for some examples of commands.

About

I was driven to make RunMany by my desire to learn more programming languages combined with my annoyance that whenever I tried I would invariably have to make a whole new project for that language, or even switch IDEs.

The obvious limitation of RunMany and the .many file format is that syntax highlighting and tooling like IntelliSense doesn't work. Making a VSCode extension that can syntax highlight .many files is definitely on my radar.