i spent weeks of my life learning rust and my reward was this talking raccoon

by the spiders (2022-05-29)

i decided in april that i wanted to learn rust. my motivations were mainly that i want to write a static site generator for this website which meshes with the way i prefer to write websites (generally, by paw, but occasionally wanting some light automation).

but a static site generator seemed so intimidating as a first project. surely there is something more easy i could try instead! i looked around the proverbial room and the idea struck me: i could write a clone of the classic ascii art generating program cowsay, with toki pona theming. i call the project kijetesantakaluotokieni (which translates to english as "raccoon or mustelid, please say this". we will also refer to it by its shorter name of "kijesay" in this post).

i started out thinking "a cowsay is just a slightly more complicated hello world! how hard could it be?"

as it turns out the project quickly took over my life. there is a lot going on under the surface of a seemingly simple piece of software like cowsay, which we had to replicate while writing kijesay.

you have to do word wrapping, which entails dealing with the fact that string length is not the same as characters, and it also entails splitting strings at grapheme boundaries (shout out to voca). you also need to create a format for your ascii art which allows your program to know where the eyes, tongue, and thought lines are, so it can dynamically customize them. you have to take and interpret commandline arguments and handle environment variables (shout out to clap). you need to support file input and define a file format so that users can create their own art.

and we took the complexity a step further by not just implementing every single one of cowsay's options, but also introducing ansii color and other formatting, and allowing even more customization than cowsay had (alongside color, kijesay supports changing the speech line and speech bubble border to anything you want, and you can give critters a little object to sit next to them).

the fact that we implemented all of the classic cowsay flags means that it is compatible with programs which know how to interface with cowsay. as an example, our partner set the kijesay binary to be xer $ANSIBLE_COW_PATH:

we learned a lot going through this project. we went from not knowing rust to having built a working clone of cowsay in a month and change. we now have a pretty workable knowledge of how rust works, at least enough to make our little toys. we did all of this through voice coding, without using a keyboard, because of our disabling wrist and hand injuries from rsi. we learned that using git is a good idea; both for ensuring you have a backup, and also to act as a journal documenting your efforts overtime.

we also learned to ask for help. be that pair programming with a friend, or asking your experienced partner to explain compiler errors to you, or reading the rust book, or the more abstract kind of help of turning to a library instead of trying to do something difficult by yourself. and we learned that it is crucial to take breaks. there was a stretch of about two weeks during which we wrote no code at all, and if we hadn't taken that break, we probably would have burnt out super hard.

writing the documentation was a huge challenge, because we wanted to write it all in toki pona. we rely on accessibility dictation software called talon to type things, and talon does not have support for toki pona. we created a workaround where we defined the command "nimi [word]" and it draws on a list of toki pona words to find the one we said, insert it, and add a space after. but it is not very accurate; it often misheard the word because talon is not calibrated for toki pona phonemics. and of course this method entails the huge inconvenience of essentially having to type things word by word, and using a two syllable command before every single word you have the type. we often resorted to just spelling out the word we were trying to say. certain words like "ni" were basically impossible for talon to understand. in the end though, we did write our documentation, and we are very proud of it.

we also created a software license in toki pona, "lawa kepeken pi ken mute", "very permissive usage rules". the terms of it are roughly similar to the mit license, but with a caveat that if an author wishes to have their name updated or deleted in the software or the license information you are redistributing, you must update their name according to their wishes, at least in all future distributions. this is in some respects a "anti-deadname" clause, but everyone benefits from the ability to shed an old name if it no longer fits them, not even just for gender reasons. we are sure the idea of a software license written only in toki pona is terrifying to lawyers, and that's the point.

by the way, (and we mention this in the documentation), while the tool itself has a software license, any ascii art generated by this program is functionally public domain (with the exception of art using "mani-majuna", because that art is not ours to dedicate to the public domain). you can do whatever you want with pictures you make with it, you don't have to credit me (although if you do, that would be nice!).

if you are curious but do not speak toki pona, here is a very loose unofficial translation of the license. do not confuse this as being an equivalent license in english or use it to check that you are complying; it is not polished or intended to replace the license in any way, and we deliberately made it somewhat inaccurate to discourage use of it as a replacement for the actual license. the toki pona version is the only authoritative version of the license.

very permissive usage rules:

information about the creators: kijetesantakaluotokieni tool was made by kulupu lintukamaki. mani-majuna picture and cowsay was made by Tony Monroe

usage rules: your permissions: you can use this tool, you can multiply this tool, you can change this tool, you can look inside of this tool, you can give this tool to other people, you can exchange this tool for money or other things, you can use this tool in other tools

but you must do this: you have to give this document alongside the tool. you must not delete the creator information from this document. if the creator changes their name or wants it deleted, you must correct their name in this document, according to their request

if bad things come from using this tool: the creator does not have to give you money. the creator does not have to fix the tool. the creator does not have to fix the bad thing

ante la, we made a lot of ascii art for this project. might it have gotten a bit out of hand?

nah. there's no way.

anyways, we are glad to be done with making this thing. it took a lot of work, but the end result is something that we feel very proud of. if you would like to install this fabulous program on your personal compupper, you can get it from crates.io.

cargo install kijetesantakaluotokieni

enjoy! <3