unix •

A lightweight, extensible foundry library for shell scripting.

What?

unix is an extensible wrapper for common unix shell commands. It provides a minimal api for executing expressive shell commands from inside Solidity using foundry's fii.

Installation

forge install abigger87/unix

Usage

NOTE: You must enable ffi in order to use this library. You can either pass the --ffi flag to any forge commands you run (e.g. forge script Script --ffi), or you can add ffi = true to your foundry.toml file.

NOTE: unix assumes you are running on a UNIX based machine with bash, tail, sed, tr, curl and cast installed.

1. Add this import to your script or test:

import {Unix} from "unix/Unix.sol";

2. Add this directive inside of your Contract:

using Unix for *;

3. Run your shell commands. This can be done in two ways:

a) Using strong typing (recommended):

// Echo "Hello World"
(uint256 status, bytes memory data) = Unix.echo().stdout("Hello World").run();

// Pipe file contents to another file
// NOTE: Commands can be instantiated from a text string using `Command.from(<YOUR_STRING>)` _(see grep command below)_
(uint256 status, bytes memory data) = Unix.cat().file("README.md").pipe(Command.from("grep \"Hello\")).run();

b) Using raw string commands.

// Cat a file
(uint256 status, bytes memory data) = "cat README.md".run();
// string(data) == <contents of README.md>

// Echo a string
(uint256 status, bytes memory data) = "echo Hello World".run();
// string(data) == "Hello World"

// Print the working directory
(uint256 status, bytes memory data) = "pwd".run();
// string(data) == <working directory>

We have provided extensive examples in scripts and further completeness is demonstrated in tests.

To run scripts, simply prefix the script name with forge s like so: forge s <script_name>. For example, to run the echo script, run: forge s echo.

Contributing

NOTE: This library is built using Foundry. To learn more about foundry and its usage, please refer to foundry book.

All contributions are welcome! We want to make contributing to this project as easy and transparent as possible, whether it's:

• Reporting a bug
• Discussing the current state of the code
• Submitting a fix
• Proposing new features
• Becoming a maintainer

We use GitHub issues to track public bugs. Report a bug by opening a new issue; it's that easy!

To run tests, install and update modules with forge update and run forge test to run all tests!

Safety

This is experimental software and is provided on an "as is" and "as available" basis.

We do not give any warranties and will not be liable for any loss incurred through any use of this codebase.

Acknowledgements

• Shannon (SOON™)
• Surl
• Solenv