Scriptlike

Scriptlike is a utility library to help you write script-like programs in the D Programming Language.

Officially supported compiler versions are shown in .travis.yml.

Links:

• How to Use Scriptlike in Scripts
• API Reference
• Changelog
• DUB Package
• Small article explaining the original motivations behind scriptlike

Sections

Features

• Automatic Phobos Import
• User Input Prompts
• String Interpolation
• Filepaths
• Try/As Filesystem Operations
• Script-Style Shell Commands
• Command Echoing
• Dry Run Assistance
• Fail

Disambiguating write and write

Features

Automatic Phobos Import

For most typical Phobos modules. Unless you don't want to. Who needs rows and rows of standard lib imports for a mere script?

import scriptlike;
//import scriptlike.only; // In case you don't want Phobos auto-imported
void main() {
    writeln("Works!");
}

See: scriptlike, scriptlike.only, scriptlike.std

User Input Prompts

Easy prompting for and verifying command-line user input with the interact module:

auto name = userInput!string("Please enter your name");
auto age = userInput!int("And your age");

if(userInput!bool("Do you want to continue?"))
{
	string outputFolder = pathLocation("Where you do want to place the output?");
	auto color = menu!string("What color would you like to use?", ["Blue", "Green"]);
}

auto num = require!(int, "a > 0 && a <= 10")("Enter a number from 1 to 10");

pause(); // Prompt "Press Enter to continue...";
pause("Hit Enter again, dood!!");

See: userInput, pathLocation, menu, require, pause

String Interpolation

Variable (and expression) expansion inside strings:

// Output: The number 21 doubled is 42!
int num = 21;
writeln( mixin(interp!"The number ${num} doubled is ${num * 2}!") );

// Output: Empty braces output nothing.
writeln( mixin(interp!"Empty ${}braces ${}output nothing.") );

// Output: Multiple params: John Doe.
auto first = "John", last = "Doe";
writeln( mixin(interp!`Multiple params: ${first, " ", last}.`) );

See: interp

Filepaths

Simple, reliable, cross-platform. No more worrying about slashes, paths-with-spaces, buildPath, normalizing, or getting paths mixed up with ordinary strings:

// This is AUTOMATICALLY kept normalized (via std.path.buildNormalizedPath)
auto dir = Path("foo/bar");
dir ~= "subdir"; // Append a subdirectory

// No worries about trailing slashes!
assert(Path("foo/bar") == Path("foo/bar/"));
assert(Path("foo/bar/") == Path("foo/bar//"));


// No worries about forward/backslashes!
assert(dir == Path("foo/bar/subdir"));
assert(dir == Path("foo\\bar\\subdir"));

// No worries about spaces!
auto file = dir.up ~ "different subdir\\Filename with spaces.txt";
assert(file == Path("foo/bar/different subdir/Filename with spaces.txt"));
writeln(file); // Path.toString() always properly escapes for current platform!
writeln(file.toRawString()); // Don't escape!

// Even file extentions are type-safe!
Ext ext = file.extension;
auto anotherFile = Path("path/to/file") ~ ext;
assert(anotherFile.baseName == Path("file.txt"));

// std.path and std.file are wrapped to offer Path/Ext support
assert(dirName(anotherFile) == Path("path/to"));
copy(anotherFile, Path("target/path/new file.txt"));

See: Path, Path.toString, Path.toRawString, Path.up, Ext, dirName, copy, buildNormalizedPath

Try/As Filesystem Operations

Less pedantic, when you don't care if there's nothing to do:

// Just MAKE SURE this exists! If it's already there, then GREAT!
tryMkdir("somedir");
assertThrown( mkdir("somedir") ); // Exception: Already exists!
tryMkdir("somedir"); // Works fine!

// Just MAKE SURE this is gone! If it's already gone, then GREAT!
tryRmdir("somedir");
assertThrown( rmdir("somedir") ); // Exception: Already gone!
tryRmdir("somedir"); // Works fine!

// Just MAKE SURE it doesn't exist. Don't bother me if it doesn't!
tryRemove("file");

// Copy if it exists, otherwise don't worry about it.
tryCopy("file", "file-copy");

// Is this a directory? If it doesn't even exist,
// then it's obviously NOT a directory.
assertThrown( isDir("foo/bar") ); // Exception: Doesn't exist!
if(existsAsDir("foo/bar")) // Works fine!
	{/+ ...do stuff... +/}

// Bonus! Single function to delete files OR directories!
writeFile("file.txt", "abc");
tryMkdirRecurse("foo/bar/dir");
writeFile("foo/bar/dir/file.txt", "123");
// Delete with the same function!
removePath("file.txt"); // Calls 'remove'
removePath("foo");      // Calls 'rmdirRecurse'
tryRemovePath("file.txt"); // Also comes in try flavor!
tryRemovePath("foo");

See: tryMkdir, mkdir, tryMkdirRecurse, mkdir, tryRmdir, rmdir, tryRemove, tryCopy, existsAsDir, removePath, tryRemovePath, writeFile and more...

Script-Style Shell Commands

Invoke a command script-style: synchronously with forwarded stdout/in/err from any working directory. Or capture the output instead. Automatically throw on non-zero status code if you want.

One simple call, run, to run a shell command script-style (ie, synchronously with forwarded stdout/in/err) from any working directory, and automatically throw if it fails. Or runCollect to capture the output instead of displaying it. Or tryRun/tryRunCollect if you want to receive the status code instead of automatically throwing on non-zero.

run("dmd --help"); // Display DMD help screen
pause(); // Wait for user to hit Enter

// Automatically throws ErrorLevelException(1, "dmd --bad-flag")
assertThrown!ErrorLevelException( run("dmd --bad-flag") );

// Automatically throws ErrorLevelException(-1, "this-cmd-does-not-exist")
assertThrown!ErrorLevelException( run("this-cmd-does-not-exist") );

// Don't bail on error
int statusCode = tryRun("dmd --bad-flag");

// Collect output instead of showing it
string dmdHelp = runCollect("dmd --help");
auto isDMD_2_068_1 = dmdHelp.canFind("D Compiler v2.068.1");

// Don't bail on error
auto result = tryRunCollect("dmd --help");
if(result.status == 0 && result.output.canFind("D Compiler v2.068.1"))
	writeln("Found DMD v2.068.1!");

// Use any working directory:
auto myProjectDir = Path("my/proj/dir");
auto mainFile = Path("src/main.d");
myProjectDir.run(text("dmd ", mainFile, " -O")); // mainFile is properly escaped!

// Verify it actually IS running from a different working directory:
version(Posix)        enum pwd = "pwd";
else version(Windows) enum pwd = "cd";
else static assert(0);
auto output = myProjectDir.runCollect(pwd);
auto expected = getcwd() ~ myProjectDir;
assert( Path(output.strip()) == expected );

See: run, tryRun, runCollect, tryRunCollect, pause, Path, getcwd, ErrorLevelException, assertThrown, canFind, text, strip

Command Echoing

Optionally enable automatic command echoing (including shell commands, changing/creating directories and deleting/copying/moving/linking/renaming both directories and files) by setting one simple flag: bool scriptlikeEcho

Echoing can be customized via scriptlikeCustomEcho.

/++
Output:
--------
run: echo Hello > file.txt
mkdirRecurse: some/new/dir
copy: file.txt -> 'some/new/dir/target name.txt'
Gonna run foo() now...
foo: i = 42
--------
+/

scriptlikeEcho = true; // Enable automatic echoing

run("echo Hello > file.txt");

auto newDir = Path("some/new/dir");
mkdirRecurse(newDir.toRawString()); // Even works with non-Path overloads
copy("file.txt", newDir ~ "target name.txt");

void foo(int i = 42) {
	yapFunc("i = ", i); // Evaluated lazily
}

// yap and yapFunc ONLY output when echoing is enabled
yap("Gonna run foo() now...");
foo();

See: scriptlikeEcho, yap, yapFunc, run, Path, Path.toRawString, mkdirRecurse, copy

Dry Run Assistance

Scriptlike can help you create a dry-run mode, by automatically echoing (even if scriptlikeEcho is disabled) and disabling all functions that launch external commands or modify the filesystem. Just enable the scriptlikeDryRun flag.

Note, if you choose to use this, you still must ensure your program logic behaves sanely in dry-run mode.

scriptlikeDryRun = true;

// When dry-run is enabled, this echoes but doesn't actually copy or invoke DMD.
copy("original.d", "app.d");
run("dmd app.d -ofbin/app");

// Works fine in dry-run, since it doesn't modify the filesystem.
bool isItThere = exists("another-file");

if(!scriptlikeDryRun)
{
	// This won't work right if we're running in dry-run mode,
	// since it'll be out-of-date, if it even exists at all.
	auto source = read("app.d");
}

See: scriptlikeDryRun, copy, run, exists, read

Fail

Single function to bail out with an error message, exception-safe.

/++
Example:
--------
$ test
test: ERROR: Need two args, not 0!
$ test abc 123
test: ERROR: First arg must be 'foobar', not 'abc'!
--------
+/

import scriptlike;

void main(string[] args) {
	helper(args);
}

// Throws a Fail exception on bad args:
void helper(string[] args) {
	// Like std.exception.enforce, but bails with no ugly stack trace,
	// and if uncaught, outputs the program name and "ERROR: "
	failEnforce(args.length == 3, "Need two args, not ", args.length-1, "!");

	if(args[1] != "foobar")
		fail("First arg must be 'foobar', not '", args[1], "'!");
}

See: fail, failEnforce, Fail

Disambiguating write and write

Since they're both imported by default, you may get symbol conflict errors when trying to use scriptlike.file.wrappers.write (which wraps std.file.write) or std.stdio.write. And unfortunately, DMD issue #11847 currently makes it impossible to use a qualified name lookup for scriptlike.file.wrappers.write.

Here's how to easily avoid symbol conflict errors with Scriptlike and write:

// Save file
write("filename.txt", "content");  // Error: Symbols conflict!
// Change line above to...
writeFile("filename.txt", "content"); // Convenience alias included in scriptlike

// Output to stdout with no newline
write("Hello ", "world");  // Error: Symbols conflict!
// Change line above to...
std.stdio.write("Hello ", "world");
// or...
stdout.write("Hello ", "world");

See: scriptlike.file.wrappers.writeFile, scriptlike.file.wrappers.readFile, scriptlike.file.wrappers.write, std.file.write, std.stdio.write