Rust

 I'm going to learn Rust. I mean, I mostly already know it, but I want to have a clear goal to strive for, so here goes:

• Gain an understanding of lifetimes and the borrow checker
  

• Support open source projects I care about
  

• Write at least 1 open source project in 6 months. I have a list:

  1. Postgres Logical Replication Validator -- we have one (written by me) at work, but it's in Python. Convert to rust and publish
  2. postgres-exporter -- export query statistics from pg dbs
  3. repmgr flapping-foo -- when repmgr starts flapping, lower the requirements for failover successively, ish

  Biggest hurdle is probably finding the time. I have some at work, so that's good. Now I just need to figure out where to find the data I need.
  

Bounty and Villain generator (ish)

The weaknesses in my generators are becoming apparent

A sample of the Bounty and Villain generator for Drier Deserts, Hotter Suns was posted in the OSR discord, and I figured I'd give it a whirl in the old generator. It highlighted a lot of issues; mostly formatting at this point. Solve formatting, and you can solve anything else I think.

Ignoring the dice roll (since we're rolling "behind the scenes"), it's clear that a single row will have issues portraying this information. Like, I'd prefer to have the output be something like this:

Dwarfish
Swift 1
Tough 8
Bounty 4k

But that's not possible unless I split it into subtables -- so Dwarfish and Brawny would be in a table, there'd be a table for "Swift" and one for "Tough" and one for "Bounty." That said, it's fairly clear that the bounties are tied to the word; lower values of Swift and Tough means lower bounties. So, the "Word" could be split from the Swift/Tough part and be its own table, I guess.

Further issues appear when we add in the specialties:

 1-7 is easy, we just copy and paste the line 7 times to achieve that weighting. But, again, we'd like to format the result like so

Gun Specialist
Guns 4

Bounty 2k

Which, again, we can't. Yet. Anyway, here's the result of it.

As you can see, it's... okay, but lacking. I will prioritize formatting after I'm done with the sign-up functionality. I think the largest gain is to be had there. It would also be nice to have a function to sum up the bounties across the results, but that's ... soooo far away.

Magical Tome generator

In order to test what I've made, I'll make small generators for a while and see how they pan out. I've already found a bug, and I'm not sure how to solve it yet. It's to do with newlines, and I just hate how textarea (the HTML entity) is so bad. Each small step (fix) will eventually build into something pretty nice, I think, so they're worth taking.

Here are some magical tomes for your troubles.

Stealth release: Generators

I'm releasing Generators even though they're not quite finished

There's not much more to say, really. Right now, the only syntax that's allowed (and works!) is the table id syntax: {{id}}. More features are planned, but I'm also sick and tired of this application so...

Here's an example of a generator (and also an excuse for me to try it out on my own application!). It looks like this:

{{11}} and {{10}} {{9}}, from {{3}}.

{{11}} is a table of male names from, ca, 13th century London. {{10}} is likewise, but female names. {{9}} is a huge (~1.8k) list of surnames, also somewhat accurate to the 13th century. {{3}} is a list of wards in London, again taken from historical sources.

And here's the embedded object, with 5 entries just to show that it works:

And I think that's pretty neat, tbh. There's a lot of work to be done, still, but it's something that can be used now, immediately. And there's some value in that, too.

I've also added error tracking. I hope that I'll catch anything before the server burns to the ground. I don't think it will, but you never know.

A generator of generators!?

Generators in the OSR sphere are largely JavaScript-based. It's easy to see why -- JS is immediately accessible, it lets you create dynamic web pages (or snippets for web pages), and it's fucking everywhere. But, as with all great things, there are downsides to the JS generators we've grown to know and love.

They're cumbersome. Like, so, so, so cumbersome. I'm not gonna name names or link you to any of them, but ... yeah. Some of them require you to host your text files elsewhere. Others require you to use extremely specific syntax but offer no validation of them ("test extensively" is not a validation). Others still offer hosting but you can't edit your own generators after having them hosted. Many offer you a blob of javascript you can add to your blog and get a sample output from.

My immediate goal was "I want dynamic table results", rather than "I need to fix everything" or something like that. I wanted to be able to write "2d6 orcs advance slowly down the side of the ravine" and have the output be "3 orcs advance slowly down the side of the ravine"; I figured that was a good place to start. You could make a JS page that just scanned the text for dice rolls and replaced them.

I've still not gotten anywhere near that. I made something else instead. I made a fucking generator. Quelle surprise, I guess, since the title is "A generator of generators!?" and I'm talking about ... well, yeah.

This tool, though, I had a mission statement for. It's a bit undefined around the edges, but overall it looks something like this:

Cassie's Generator Tool

• The syntax should be clear and concise

• Hosting for both the generator and the tables (lists) should be a solved problem for the user

• Users should be able to edit their own tables if they need to

• Users should be able to delete their own tables and generators, if they want to 

• You should be able to use generators or tables someone else has made

• It should offer embedding, no unsightly JS blob

• If the user wants to, they should be able to download all their generators and tables

Here's a first sketch of the syntax:

A table result: {{table}}
A generator result: ||generator||
Dice notation: >1d6<, >1d6+2<

I'm still not sure about the dice notation, but I think it's important to have the difference between what should be rolled and what is information for the reader:
"The weapon does 1d6 damage" should just say "The weapon does 1d6 damage" in the output, whereas "The next >1d4< days" should say "The next 2 days" (plural "days" is gonna be a problem. Hm.)

I've not implemented everything yet. In fact, I've only solved the boring parts. But the good parts are coming. Here's what I made yesterday:

Now, that "{{11}}" says nothing, I know. I'll think of something. Eventually, there'll be helper functions for writing generator entries (like, you'd write {{ and get a search window to find the table you want a result from), but for now there's nothing like that.

The way the code's written, a generator is simply a very thin wrapper around a parser and a transformer, so using generators within other generators should be pretty easy. A few issues loom on the horizon, though. If I become as popular as Facebook, I can't host everything for free, and there might be some resource issues along with that popularity. I might have to move the platform to kubernetes eventually, just for that horizontal scaling. And also because I want to learn it.

Today and tomorrow I'll set up the embed thing, and then I think I might even link to the thing for public consumption.

Any fool can write code that a computer can understand

Good programmers write code that humans can understand.

Martin Fowler

Generators are dope. While I'm working on a tool that will create generators for you, in the meantime I can write a quick guide on how to create your own generator in JavaScript. Bonus: you can also call yourself a programmer when you're done.

Today, I wrote https://place-and-region-generator.netlify.app/. It is, as the URL says, a generator for place and region names. It took me maybe half an hour because it's really quick to write ugly code like I did, and it's also a really simple program. I'm gonna teach you how to write it, too. Instead of place names, let's go with dwarven names. I want to generate dwarven names. How do I go about that?

Step 1: Node & NPX

Since I work as a web dev in my daily life, my computer already has all the dependencies I need to create projects (react projects, in this case). Here's a super short guide to how to get node and NPX on your machine:

We need nodejs. Let's not care so much about what it is,  we can dig into that some other day. Install it (installation varies between different operating systems), and then check that it worked with something like this in the terminal (this is in an ubuntu container):

On a mac, it can look like this:

Great. We're almost half-way. We also need either NPM or Yarn, two package managers that are used for javascript projects. Don't mind the technical details, for now. NPM comes with node, so we'll go with that.

The last part of step 1 is to make sure that npx is installed (it should come with the latest versions of npm):

Step 2: React & Previewing Stuff

The next command we need to run is this: "npx create-react-app dwarven_names"

Where "dwarven_names" is the name of our project/generator. This will create a new React app with the name "dwarven_names". It will create this in a folder named "dwarven_names" like the text says:

Let's do what it says: cd (change directory) into dwarven_names and run "npm start":

And if you now navigate to http://localhost:3000/ you will see your app running. It doesn't look like much, right now:

But hey, you did that! Awesome. Let's rip everything out and create something of our own instead.

Step 3: Creating a basic generator

Now we're touching on actual programming, but I'll try and write it so you can follow along and just replace things with what you, yourself, need. Feel free to reach out to me on discord, I'm Azaz#1947 there, or comment here and I'll help as best I can.

Alright, to edit code it's usually easier to do so in a code editor. But you can edit code in notepad.

Let's open the file "App.js", it's located in the "src" folder inside our "dwarven_names" folder. It looks like this:

Great. We don't need some of this junk, but I'll go through it nonetheless:

The first three lines are dependency imports. We fetch "React" from a package aptly named "react", we fetch a logo (it's the rotating atom thing), and we import some css, too.

After that, on line 5, we declare a function named "App", and inside our function we return some HTML... ish. It's HTML but with some extras. In HTML, you write "class", but you can't do that in JavaScript, so you instead write "className". We'll rip out most of the stuff inside this. Delete until it looks like this:

If you save that and look in the browser, you'll see we've successfully removed some cruft. You's a programmer!

We'll add a title, and create some Dwarf names. In Zonk's generator (which I borrowed for this tutorial), a Dwarven name comes from an appropriately dwarven base, such as "Dragon" or "Stone", combined with a suffix, something dwarven like "arm", "killer" (I guess these are WHFRP dwarves?), "shield" and similar. We'll create two arrays to hold these. An array is basically a list, but the syntax is important. Here's how it looks in JavaScript:



Not terribly difficult to understand. Here's the syntax, in its base form: const arrayName = [value1, value2, value3]

Values can be a lot of things, but we're working with text (or "strings" as the fancy name is).

It doesn't really matter where in the file we place these arrays, but imports should always be at the top, so we'll just tuck them in under that for now.

The second to last thing we need to do (ish) is to get a random item from both arrays onto our page. Here's how that's done:

The [0] part is "give me the item at position 0 from the array named 'base'". Let's see how it looks:

You know what? That looks okay. Now we just need to make it "random" rather than always being the first item in both arrays. The secret is to use a function. Here's how that looks:

And here's how it's used:

I realize now that I forgot to tell you what the {} deal in the code is, on line 14. It's telling React "run this function and insert the value returned from that function here".

And for the "randomElement" function we wrote, what we're doing is we're giving that function an array ("base" or "suffix") and then we're asking it to select a random item from that array and return it to us. It's a very fancy "modern" JavaScript syntax. So when we're using the function, we're saying "give me a value from 'base' and combine it with a value from 'suffix'"

Anyway, we're almost done. We want more than one dwarf name, though, so we'll do that with a fancy loop, like so:

There's a lot going on here. We're declaring a new array ("names") on line 10. On line 11 to 13 we're looping (going through the same code a specific amount of times, here it's 10) over the same piece of code 10 times and saving the result of that code in the new array we created.

array.push() adds an item to an array. randomElement(base) + randomElement(suffix) combines the result of the two randomElements into one (not all languages can do it like this, but JavaScript can).

the "names.map()" thing is just a shorthand way of saying "modify each element in the array like this". Here we're modifying them to create HTML paragraph tags. map() returns a new array, so we're not chaning the names array on line 10.

The "key" part is because React needs to know something unique about every item in the array, otherwise it complains a lot. Basically.

And here's how the results look:

There'll be a lot of repetition here because we only have three names of each kind to select from. More names = more combinations.

We've successfully created a generator. Right now you can use it on your own computer, which is pretty nifty, but we can also host it online for others to use. The last thing we need (can) to do in this step is clean up some junk that we don't need.

We don't want logo.svg, so remove that. Our CSS file can also be trimmed down to this:

the rest of the stuff in it is basically just "I want to create a rotating logo", and we don't have that.

Don't worry too much about the code; at the end of this guide I will show you all the files. We're basically done with it already.

Step 4: Version Control

Oh no, that sounds hard!

It is... kind of. I'm sorry to say, but this will be the hardest step to explain. Create-react-app, that we used to start our project with, has given us a .gitignore file, which is good because then we don't have to worry about that. Version control is basically like save points, but it's graphs and you can do lots of cool shit with it. I will not teach you anything about that. I will point out how we get this project onto our VC platform of choice.

I should probably have mentioned: YOU NEED TO INSTALL GIT ON YOUR MACHINE FOR ALL THIS TO WORK. It's not terribly hard, here's a guide: https://www.atlassian.com/git/tutorials/install-git

We have a few choices. Github is, ostensibly, the largest, most well-known of the platforms. Sign-up is easy (it is for most of these guys tbh). BUT they host ICE and so they can get fucked. Pick whatever. I picked GitLab, but the process is similar for all the platforms (you can also use Bitbucket, but stick with one of these three: Github, GitLab, Bitbucket, it will make it easier in the next step).

Create a new project on your platform of choice:

Note that I'm leaving the "Initialize repository with a README" checkbox unchecked.

Gitlab gives us instructions on how to proceed.

All that stuff is terminal-based. There are visual git clients available. I will not use one, but you can probably google for it. GitKraken is popular, and Fork is also a good one (if you're on Mac). Anyway, we'll follow the "Git global setup" first, then we want to do "Push an existing folder" because our project is already existing

If we follow the GitLab guide, everything should work just fine. (I sidestepped it a bit because I have several git accounts. If you want to specify a git account for a specific git repository, just omit the --global flag and the changes are local.) Here's the last few lines for me:

A whole lot of gibberish. It might make more sense to you later unless you already know git but then why are you reading this?

And this is how it looks like on Gitlab:

We are so nearly there. Lemme just hit on one point real quick: "git add ." means "stage everything that's changed in the folders you're tracking". "git commit" means "save all changes you have staged under this commit message" (it will prompt you for a message, or you can do "git commit -m 'your message here'" instead). If you end up in vim, the command to exit is "hit escape a few times, then :, then type q! and enter" and the command to exit and save is "hit escape a few times, then :, then wq and enter". That is, the command to start writing commands is :

For more on git, I recommend googling for guides. It's powerful and amazing.

Step 5: Get this thing online so help me

Let's get this app (you can use this word now, you're a PROGRAMMER) online! We'll use Netlify, because it's the easiest option. You can use your newly created Gitlab account to sign up on Netlify, so that's neat but they also offer the regular Google, Facebook, etc, etc. Once signed up, read their small guide/flash cards then hit that "New site from Git" button. Under "Continuous Deployment" ("CD" for us cool kids in the biz) select your poison of choice (GitLab for me). We need to authorize Netlify to access our GitLab resources, so I just hit okay because I'm wild like that. Find your newly created repository, and select it:

So the cool thing is, now that I've selected my "dwarven_name_generator" repo, Netlify is smart enough to know what tools I've used to create my application with. I cheated and used yarn, so I'm sorry about that but it will say "npm run build" instead of "yarn build" on this screen if you used npm:

All those settings look okay, so I just hit "deploy site" and I'm basically done. Because look at that, it's already deploying. I've got a new URL for my project; it's always randomized to start with, but poke around in the Netlify settings and you can change it to something else if you want to. I'm cool with the "modest-heisenberg-a2c78d" URL, because I figure I'm not going to push this application very much.

 

After a while, it switches from "Site deploy in progress" to "Last published at" and a link to our cool, new app. And here it is, in all its glory: https://modest-heisenberg-a2c78d.netlify.app/

Alright. Not too hard, right? YOU DID THAT. Well, I DID THAT but you could also do that if you follow along!

And the best part about Netlify is that if you ever update your master branch in git and push those changes to your remote repository (Gitlab, for me),  Netlify will spot those changes and deploy them automatically.

And that's pretty neat.

Step 6: ???

Step 7: Profit

Now that we know just how easy it is to make a generator, I hope you can see that it wouldn't be terribly hard to create a more advanced generator. It's basically just "pick a random option from this array, then a random option from this array, and then from this" and so on. It is easy. You'll run into problems -- you can google the answers, because the more you do this, the more you learn the "language" of programming, which in turn makes it easier to google for more answers.

Step 8: Collaboration

Oh, also, I made the Dwarven Name Generator public on GitLab: https://gitlab.com/cassie_/dwarven_name_generator -- so you can create pull requests that add code or names or suffixes or just whatever to it if you want to. But you'll have to read up on that yourself because this is getting very long. You can also inspect all the code for the project over there, so that's also neat. Especially Zonk should probably create a pull request because it's basically their idea, just chopped into a very small piece.

And if you have any questions, just hit me up either here or in Discord. Now go forth, my friends, and create! I expect great things from you!