(\
\\
))
//
.-. // .-.
/ \-((=-/ \ /~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\ \\ / / Hey there! I'm Ralph, your |
$ ralph # Magic... `( ____))_ )` < personal alias apprentice. |
.-' // '-. \ How can I serve you today? |
/ (( \ \~~~~~~~~~~~~~~~~~~~~~~~~~~~+
| ! |
\ /
\ |___| /
_) \ / (_
(((---' '---)))
Ralph helps you create Bash aliases that can be called with
sudo
, have parameters, and print aesthetically-pleasing error messages. Ralph takes the work out of writing complex Bash aliases and provides parameter restrictions and default parameter values out-of-the-box.
Disclaimer: these instructions are a bit confusing, at the moment. It may be easier to take a look at the example blueprints.
A blueprint is an outline of the alias being designed. Let's take a look at the blueprint for the digitalocean
alias shown in the images above.
{
"blueprint": "digitalocean {*user?} {~server?}",
The first part of the blueprint, digitalocean
, is the name of the command you want to generate.
Alias parameters are defined after the first part of the blueprint. In this case, the parameters are described by {*user?}
and {~server?}
. Let's take a closer look at these two parameters.
{*user?}
- the opening brace (
{
) → defines a parameter - the asterisk (
*
) → any value is acceptable (not restricted) - the parameter name (
user
) → a parameter nameduser
- the question mark (
?
) → optional value, default will be used if no argument specified - the closing brace (
}
) → closes the parameter definition
- the opening brace (
{~server?}
- the opening brace (
{
) → defines a parameter - the tilde (
~
) → certain values are acceptable (restricted) - the parameter name (
server
) → a parameter namedserver
- the question mark (
?
) → optional value, default will be used if no argument specified - the closing brace (
}
) → closes the parameter definition
- the opening brace (
"command": "ssh {user}@{server}",
This is where you define what command is executed when you call your alias.
You can use any parameters defined in the blueprint
above in your command by enclosing the parameter name in braces, as seen in the example above.
"arguments": {
"user": {
"values": {
"default": "root"
}
},
Since user
is an optional parameter (has a question mark, ?
, in the blueprint declaration), a default
value is required. In the event that no user
is specified, the default
value will be passed in its place.
"server": {
"values": {
"default": "198.199.97.172",
"website": "198.199.97.172",
"git": "91.876.54.321"
},
Keep in mind that server
, like user
, is also an optional paramter, so a default
value is required.
In addition, server
is a restricted parameter, which only allows certain, explicitly defined values to be passed. In this case, two values are defined; meaning, only these two values are acceptable parameters.
digitalocean website
and digitalocean git
are acceptable; however, digitalocean invalid
would print a generic error. This error can also be explcitly defined, as outlined below.
"errors": {
"invalid": "I've never heard of {server}."
}
Define an invalid
error that will be printed if the parameter is restricted and the value provided is not acceptable.
Define an missing
error that will be printed if the paramter is not optional and a value is not provided.
Similar to the command
, parameters can be used by enclosing the parameter name in braces, as seen in the example above.
}
}
}
Ensure your blueprint contains valid JSON!
After following the simple installation instructions, just run ralph
and Ralph will take care of everything else for you.
Just call them! For example, with the above example: $ digitalocean
.
In addition, you can call them with sudo
, unlike classic Bash aliases: $ sudo digitalocean
.
Installation is super-simple: no finicky package managers or dependencies (other than Python); just pure drag-and-drop.
After downloading ralph
, simply copy it over to your $PATH
and you're good to go.
$ wget https://github.com/qw3rtman/ralph/releases/download/v0.1.0/ralph
$ chmod +x ralph
$ mv ralph /usr/local/bin
If you don't have wget
on your system, you can download ralph
from the releases page and follow the above steps from the second one onward.
Now just run ralph
once and Ralph will take care of setting up your ~/.ralph
directory with all the default settings.
All configuration for ralph
are found in ~/.ralph/config.json
. Here, you can tell Ralph where to search for blueprint JSON files and where to place alias files after they are generated.
The major limitation with ralph
is inherent in optional parameters.
In the above example (digitalocean
), suppose you want to utilize the default value of user
(the first paramter) by leaving it blank, ralph
will just assume the first parameter is what the second parameter was intended to be.
$ digitalocean website
Here, I intended for the user
parameter to default to the default
value; however, the user
parameter would be website
and the server
parameter would be blank, resulting in it default to the default
value.
While I intended for the above command to result in:
$ ssh root@198.199.97.172
It would actually result in:
$ ssh website@198.199.97.172
Contributions are always welcome.
Find something interesting in the TODO below, fork our code, create a new branch, and send us a pull request.
There are only two rules: avoid code smells and abide by the syntax-formatting of the existing code.