atom

Shell scripting that will knock your socks off.

NOTE: Click the image above for a video demonstration.

About the Author

I'm a freshman in college bored in quarantine, and looking for any work. If you enjoy my projects, consider supporting me by buying me a coffee!

Why write a shell?

As I see it, there are two sides of a shell. The interactive side, and the scripting side. Creating a good shell means balancing these two modes well. If you make a language too well suited to scripting, then file navigation, and other interactive features will suffer. On the other hand, if you make a language too well suited for interactive commands (like bash), then scripting becomes very difficult.

Atom tries to strike a better balance between the two modes than bash, and, in my opinion, does so rather successfully. It does seem to be more well suited to scripting instead of interactive programming, but I don't really mind the sacrifice all that much.

Atom's design goals are:

1. Shell scripting must be powerful enough to function as a traditional high level language.
2. At the same time, there must not be a lot of syntactic sugar for writing interactive commands.
3. Incorrect code should be rejected. There should be no attempt to understand the user's incorrect code (see JavaScript). Bad code is bad code.
4. Declarative and functional programming first, imperative last.

I would say these goals serve atom very well.

To show Atom's scripting capabilities, I wrote an entire card game using it!

The CPU is actually much better than I am, and has beaten me with twice or thrice my score multiple times. It doesn't cheat at all, it only ranks its cards by synergy, encourages picking up cards that synergize well with its best cards, and discarding its worst cards.

If you want to try all of my custom macros, and to have my splash screen, use my .atom-prelude file in your home directory and experiment away! To play my card game specifically, run rummy@play'.

Usage

Atom is drastically different than any other shell, both with its outward syntax and internal functionality.

For example, atom supports traditional tables, lists, strings, ints, floats, bools, etc. like this drastically better and more professional shell that I should have just started using to begin with (but there's no fun in that. "Not invented here syndrome" really does have a hold on me doesn't it?).

But atom also takes direct inspiration from languages like lisp by including symbols as first class types, and by implementing iterative constructs like for and while loops as values, not operations on values.

Additionally, it adds lambdas (which can capture their environment), and macros (which can change their parent environment).

Interactive Syntax

While this syntax will work in all of your scripts as valid statements, my intent is for this to be mainly used for interactive programming.

Generally, executing programs (and functions too) in atom and in bash is only different by one character.

Bash:

$ g++ main.cpp -o main

Atom:

$ g++' main.cpp -o main

You might be thinking that writing a quote after every program name is not so ergonomic, but it actually isn't half bad. I find now that when I use bash, I can't seem to type any commands without it accidentally.

The reason I chose the ' character is because it is the most readily available character that isn't used in any symbols (besides the semicolon) that is also not accessed with the shift key. The command g++' main.cpp -o main really is just one extra keystroke.

Not that much of a sacrifice for scripting power bestowed by the gods.

Aliases

You might find that you have defined a symbol g++ with a non-callable value (not a macro or a function), like 5.

If this is the case, simply wrap the symbol g++ in quotes, and then run it like so: "g++"' main.cpp -o main.

This also means that you can make aliases rather simply by defining a symbol with a string or a path.

This snippet defines ls as an alias for the lsd program:

ls := "lsd";
ls'

Scripting Syntax

Again, scripting syntax is really just syntax encouraged for scripting. All syntax you see on this README will work anywhere.

To start off simple, let's define a variable.

x := 5;

Wow! We've changed our environment! This means that whenever the symbol x is evaluated, it becomes 5 instead!

Now let's define something else.

WEEKDAYS := [
	"Sunday",
	"Monday",
	"Tuesday",
	"Wednesday",
	"Thursday",
	"Friday",
	"Saturday"
];

grades := {
    "adam": 50,
    "literally everyone else": 100
};

Bravo! Now the symbol WEEKDAYS is bound to a list containing all the weekdays' names, and the symbol grades is bound to a table containing grades for students!

Now let's try to do some fun stuff with lambdas.

min := \x,y -> x < y? x : y;
max := fn(x, y) -> x > y? x : y;

# You can put brackets around the lambda body for multiple statements
return-five :=   () -> { print("returning 5"); 5 };
return-six  := fn() -> 6;

increment := x -> x + 1;
decrement := fn(x) -> x - 1;

As you can see, we can use the \... -> or fn(...) -> syntactic sugar to create lambda functions with multiple arguments, () -> to create a lambda that takes no arguments, or just a symbol and an arrow to create a lambda that takes a single argument. How handy!

You can also use the fn keyword to define functions without assigning them.

fn is-leapyear(year) {
	if year % 4 = 0 and year % 100 != 0 {
		true
	} else if year % 100 = 0 and year % 400 = 0 {
		true
	} else {
		false
	}
};

fn days-in-month(month, year) {
	month = 2? 28 + to-int(is-leapyear(year)) : 31 - (((month - 1) % 7) % 2)
};

fn day-of-week(m, d, y) {
	t := [0, 3, 2, 5, 0, 3, 5, 1, 4, 6, 2, 4];

    # Notice that semicolons go on the end of if statements too
	if m < 3 { y := y - 1 };
    
    # The last expression in a function is the value that is returned
	(((y + to-int(y / 4)) - to-int(y / 100)) + to-int(y / 400) + t[m - 1] + d) % 7
};

Please note the semicolon at the end of every expression. It is required for everything except for the last value of a block!

You can also define macros in a similar manner with the macro keyword:

# We write `; nil` at the end of the macro so that
# the macro returns nil, instead of the new CWD value.
root := macro() -> { CWD := ROOT; nil };

macro quit() {
	print("Goodbye!👋");
	sleep(0.4);
	exit();
};

Isn't this nice???

Functions vs. Macros

Functions and macros look very similar, and perform almost identical tasks, but they have drastically different implications.

To explain it simply, a function creates its own local scope, with local variables that are dropped when the function returns. Macros, however, use the current scope that the macro is called in as its scope.

Variables that would have been overwritten by the macro's parameters, are saved. Take the following code for example:

x := 5;
y := nil;
macro test(x) { y := x };

print(x, y);
test("x is still 5, but y is not nil");
print(x, y);

Macros let you read and write global state, while (user defined) functions have no side effects on the global state of the program.

Builtin functions are a different beast entirely, though...

Builtin Functions vs. Functions

Builtin functions are a bit of a misnomer. They're half macro, half function, and a little bit of something else not quite quantifiable. How do they work? The world may never know.

The reason they're so mystical is because they can change the scope they were called in (like macros), they have the option to not evaluate their arguments (unlike macros), and they can take varying numbers of arguments.. For example, take the cd builtin function. Not only does it not evaluate its arguments (calling cd with Desktop doesn't evaluate the symbol Desktop), it modifies the CWD variable in the current scope. How weird is that?

$ home'
$ cd' Desktop

Additionally, builtin functions like echo, print, and to-str can take varying numbers of arguments.

$ print("x is equal to", x := 5, "and y is equal to", y := 6)

Although these features of builtin functions are cool and bizarre, they really aren't used in many instances. Functions like print and cd are exceptions to the rule, and you can expect most functions to behave exactly as regular user defined functions without any bizarre catches.

Modules

Atom has an extensive list of builtin libraries (for a shell written in a week or so, that is). Here's a list of builtin modules.

Modules (which is just a fancy name for tables intended to function as libraries), can be accessed with the @member operator or the ["member"] operators.

Example usage:

shuffled-deck := rand@shuffle(cards@deck@all);
echo(shuffled-deck[0]);

These are all intended to make scripting extremely ergonomic. With builtin libraries for a wide variety of tasks, making scripts will be incredibly easy.

We bring the blocks, you bring the glue.

Constants and Builtin Functions

These constants and builtin functions are intended to be used extremely often in scripting and in the interactive prompt, so they are all included in the global scope.

They can all be overwritten, if you wish. I would be careful about using macros to assign to these values! Be absolutely sure that your code won't break something before you run it!

Installation

To install, you must download Rust from here.

Development Build

# Download the repo and install from source
git clone https://github.com/adam-mcdaniel/atom
cd atom
cargo install -f --path .

Releases

To get the current release build, install from crates.io.

# Also works for updating atomsh
cargo install -f atomsh

After Install

# Just run the atom executable!
atom