8 releases (4 breaking)
0.5.0 | Sep 6, 2024 |
---|---|
0.4.0 | Sep 1, 2024 |
0.3.2 | Aug 23, 2024 |
0.2.0 | Aug 8, 2024 |
0.1.1 | Aug 2, 2024 |
#33 in Compression
725 downloads per month
68KB
1.5K
SLoC
shell-toy
A cowsay | fortune
implementation in Rust.
THIS IS STILL A WIP (Pardon the glitches, those are from the asciinema recording)
Installation
Currently, pre-built binaries are not provided since the project is in a state I don't consider to be "finished".
For now the best way is to use Cargo:
cargo install shell-toy
This will install shell-toy to your local path as sh-toy
. You can then put it in whatever terminal startup script you want.
Cargo Features & Environment Flags
There are some compile-time features that enable shell-toy to perform certain things such as using an internal copy of fortunes embedded in the executable. This can be customized based on what you want. More details are below:
Feature | Description |
---|---|
inline-fortune |
Enables inlining fortunes in the compiled `sh-toy |
` executable. See Compiling with Inline Things for more details | |
inline-off-fortune |
Also inlines Offensive fortunes. These are still blocked behind the -o flag |
inline-cowsay |
Enables inlining cowsay files in the compiles sh-toy executable. . See Compiling with Inline Things for more details |
There are also some environment variables that the build script does existence checks on which overrides build-script behavior. Unless specified, the build script will only check if the variable exists and not the value. Remove the variable instead of setting it to 0 in these cases to disable the variable's behavior.
Env Variable | Description |
---|---|
USE_DEFAULT_RESOURCES |
Will ignore COW_PATH , FORTUNE_FILE , and FORTUNE_PATH variables if they exist and instead use resources extracted from the archives defined in BuildConfig.toml . This is not required if the aforementioned variables are undefined. |
FORCE_DOWNLOAD |
Will redownload resource archives even if they exist. This has no effect if "default resources" are not being used. |
COW_PATH |
Value is used by build script. Indicates where to find the cow files to inline in the executable if the inline-cowsay feature is enabled. |
FORTUNE_FILE FORTUNE_PATH |
Value is used by build script. Indicates where to find the cow files to inline in the executable if the inline-fortune feature is enabled. Use the FILE variant if all fortunes are in a single file and there is no need to differentiate fortunes as offensive or not. |
Compiling with Inline Things
The build script will look for the following IN THIS ORDER when it comes to using the fortunes:
- If the
FORTUNE_FILE
environment variable is specified, the build script will only use the contents of that file. - If the
FORTUNE_PATH
environment variable is specified, it will embed the fortunes in that directory and subdirectory as a single file.- Offensive fortunes that are in a subdirectory
off
are processed separately and only embedded if theinline-off
feature is enabled. So if you haveFORTUNE_PATH=~/.config/fortunes
, place offensive fortunes in~/.config/fortunes/off
- Offensive fortunes that are in a subdirectory
- The build script will pull use the fortunes in the archive and internal archive path specified in
BuildConfig.toml
.
The build script will look for the following IN THIS ORDER when it comes to using the cowsay files:
- If the
COW_PATH
environment variable is specified, it will use the cow files specified by the environment variables. - The build script will pull use the fortunes in the archive and internal archive path specified in
BuildConfig.toml
.
Cow files are stored in a "map" which will support the explicit choice of choosing an embedded cow.
NOTE: using an inline feature will remove command-line/environment variable options to look at an override path for the specific type of thing (i.e. using inline-cowsay
will remove the ability to use a COW_PATH
environment variable). This is an explicit choice to simplify the binary
Usage
Help is available by running with the --help
flag
$ sh-toy.exe --help
Usage: sh-toy.exe [<message>] [-c <cow-file>] [--cow-path <cow-path>] [-o <include-offensive>] [-b <bubble>]
various program options
Positional Arguments:
message
Options:
-c, --cow-file path to a direct cowfile
--cow-path path to a folder containing multiple cows we should search.
-o, --include-offensive
whether to include offensive fortunes
-b, --bubble the type of bubble to create. Options are "think", "round",
and "cowsay"
--help display usage information
NOTE: Windows/Non-Linux Support
If you are on a Linux Platform which has the cowsay
and fortune
packages available and installed on the system, shell-toy will automatically pull from the default installation directories. Otherwise, it requires some variables or command line arguments.
COWPATH
orCOW_PATH
: Folder containingcowsay
cowsFORTUNE_FILE
: Singular%
delimited file for fortunes, prioritized over thePATH
counterpartFORTUNEPATH
orFORTUNE_PATH
: Folder containing fortunes. Offensive fortunes should be placed in a child drirectory calledoff
similar to howfortune
does it.
Legal Stuff
shell-toy
is licensed under the MIT License.
By default, the build script for shell-toy
uses resources from the following open-source projects. There is no code linkage with these projects, only the resource files are used with certain conditional compilation flags.
This project uses modified portions of code from the following projects (this is documented in the source code where it occurs)
- charasay - MIT License
Dependencies
~2.2–3.5MB
~61K SLoC