↑ Index — Part two: A very basic Hoon program →
I think this would be a good candidate for our examples repo.
-- Curtis Yarvin
Welcome to Urbit By Doing, a dysfunctional programmer's guide to making things in Hoon! In this installment of the series (of which I can't guarantee there'll be more), we'll be writing a talkbot; a chatbot for Urbit's talk.
This first part will explain the style and purpose of the series, and walk you through the setup we'll need to start work on our talkbot. By the end of all these parts you'll have a talkbot that can join and leave talk stations, respond to certain phrases, and even retrieve useful information on GitHub links posted by users!
For those of you who just want to take a look at ~talkbot's source code, you can find its repository here.
I'm just a mediocre programmer who has never written a programming tutorial before. This talkbot is the first real thing I made in Hoon, and I'm sure it's far from perfect. Of course, first steps are all about getting things working rather than perfect, so that's perfectly fine. If you, the reader, happen to be a Hoon expert (or just better versed in it than I am) and see something wrong, don't hesitate to shoot me an email!
The same goes if something I tried explaining isn't clear enough to you, but the great minds in the ~dozbud/urbit-meta talk station may bring you a swifter and more accurate response.
As you might have assumed from the verbosity of the opening and preface alone, this series is going to consist of (very) long-form posts walking you through the creation of a talkbot from the ground up. While I will be explaining everything I do line-by-line, some prior knowledge on Hoon is very much recommended (and knowledge of "regular" programming is a must).
If you prefer learning top-down like me, take a look at the Quickstart docs. If you'd rather learn bottom-up, the Hoon docs may be better. Try to at least skim both of them, just so you've seen all the concepts. I can also heartily recommend doing the exercises provided in the aforementioned docs, fumbling your way through those can teach you a lot.
To summarize: This series will be a verbose tutorial on building a talkbot with Hoon. Prior knowledge is recommended (a basic understanding of Hoon's syntax goes a very long way), but it's okay if things are still a bit vague to you; I'll be explaining everything as we go.
Urbit, still being in alpha, isn't without its fair share of bugs and issues. And even without those, it is often still worthwhile setting up a separate ship on which you can tinker with the (initially) strange and unfamiliar code that will construct your talkbot.
In the ship hierarchy, comets are way at the bottom. They don't even have a parent! That makes them cheap (free) and thus disposable, the perfect kind of identity for any bots that want to take part in the Urbit network. Let's create one like so (assuming you've already installed Urbit):
bin/urbit -c mytalkbot
You can name it anything you want, it doesn't have to be mytalkbot, but a directory with that name will be created to store the contents of your comet. Let that run for a bit (it may take a little while), and then move on to the important step of mounting your ship's home directory. Run the following command from dojo:
|mount %
Now you can access all its files in mytalkbot/home. Great!
Aside: % in the context of dojo is similar to a unix .: the current directory.
One more important thing we'll need is a station (talk chat channel) for our talkbot to play around in while it's still finding its bearings. We don't want our tests to clog up any active stations, so let's create our own! Switch to the talk prompt with ctrl+X and run:
;create channel %sandbox 'Just a sandbox channel.'
Its name (sandbox) and description don't really matter. Go wild, or don't. If you used sandbox as the name, the glyph > will be assigned to it, causing the talk prompt to look annoyingly similar to dojo's. To fix this, run the following (in talk):
;bind - %sandbox
Of course you can use any other valid glyph in place of -. Again, go wild!
Aside: though talk's UI isn't a Hoon context, it uses the same conventions. % in Hoon signifies a constant value. In this case, a symbol constant. (We'll get to that in a future part!)
Last but certainly not least, get yourself an editor. It doesn't really matter if you're using Notepad or Eclipse, but there isn't a lot of Hoon support for most editors yet. Syntax highlighting for Vim, Emacs and Sublime Text is included in Urbit's extras folder, and there exist Atom packages for syntax highlighting and documentation integration as well. Very useful!
That was some smooth and easy sailing, I hope! Next time, we'll begin with a very basic start to our talkbot: an application that takes input and prints it. Baby steps!