Part 0: Ruby Basics

I'm not a programmer, but I want to use Squib. Can you make it easy for non-programmers?

If you want to use Squib, then you want to automate the graphics generation of a tabletop game in a data-driven way. You want to be able to change your mind about icons, illustrations, stats, and graphic design - then rebuild your game with a just a few keystrokes. Essentially, you want to give a list of instructions to a computer, and have it execute your bidding.

If you want those things, then I have news for you. I think you are a programmer. And maybe Squib will finally be your excuse to learn some coding.

Squib is a Ruby library. To learn Squib, you will need to learn Ruby. There is no getting around that fact. Don't fight it, embrace it.

Fortunately, Squib doesn't really require tons of Ruby-fu to get going. You can really just start from the examples and go from there. And I've done my best to keep to Ruby's own philosophy that programming in it should be a delight, not a chore.

Doubly fortunately, Ruby is wonderfully rich in features and expressive in its syntax. Ruby has a vibrant, friendly community (much like board game geeks!). Ruby is the language of choice for many new programmers, including many universities. On the flip side, Ruby is "industrial strength", so it really can do just about anything you need it to. Plus, resources for learning how code are ubiquitous on the Internet.

In this article, we'll go over some topics that you will undoubtedly want to pick up if you're new to programming or just new to Ruby.

What You DON'T Need To Know about Ruby for Squib

Let's get a few things out of the way. When you are out there searching the interwebs for solutions to your problems, you will not need to learn anything about the following things:

• Rails. Ruby on Rails is a heavyweight framework for web development (awesome in its own way, but not relevant to learning Ruby). Squib is about scripting, and will never be a web app.
• Object-Oriented Programming. While OO is very important for developing long-term, scalable applications, some of the philosophy around "Everything in Ruby is an object" can be confusing to newcomers. It's not super-important to grasp this concept for Squib. This means material about classes, modules, mixins, attributes, etc. are not really necessary for Squib scripts. (Contributing to Squib, that's another matter.)
• Metaprogramming. Such a cool thing in Ruby... don't worry about it for Squib.

What You Need to Know about Ruby for Squib

I won't give you an introduction to Ruby - other people do that quite nicely (see Resources at the bottom of this article). Instead, as you go through learning Ruby, you should pay special attention to the following:

• Comments
• Variables
• require
• What do and end mean
• Arrays, particularly since most of Squib's arguments are usually Arrays
• Strings and symbols
• String interpolation
• Hashes are important, especially for Excel or CSV importing
• Editing Yaml. Yaml is not Ruby per se, but it's a data format common in the Ruby community and Squib uses it in a couple of places (e.g. layouts and the configuration file)

If you are looking for some advanced Ruby-fu, these are useful to brush up on:

• Enumerable - everything you can do with iterating over an Array, for example
• map - convert one Array to another
• zip - combine two arrays in parallel
• inject - process one Enumerable and build up something else

Other Important Programming Things

These are things that aren't specific to the Ruby language itself, but are essential if you're new to programming.

Find a good text editor

The text editor is a programmer's most sacred tool. It's where we live, and it's the tool we're most passionate (and dogmatic) about. My personal favorite editors are SublimeText and Atom. There are a bajillion others. The main things you'll need for Squib are:

• Line numbers. When you get an error, you'll need to know where to go.
• Monospace fonts. Keeping everything lined up is important, especially in keeping indentation.
• Syntax highlighting. You can catch all kinds of basic syntax mistakes with syntax highlighting. My personal favorite syntax highlighting theme is Monokai.
• Manage a directory of files. Not all text editors support this, but Sublime and Atom are particularly good for this (e.g. Ctrl+P can open anything!). Squib is more than just the deck.rb - you've got layout files, a config file, your instructions, a build file, and a bunch of other stuff. Your editor should be able to pull those up for you in a few keystrokes so you don't have to go all the way over to your mouse.

There are a ton of other things that these editors will do for you. If you're just starting out, don't worry so much about customizing your editor just yet. Work with it for a while and get used to the defaults. After 30+ hours in the editor, only then should you consider installing plugins and customizing options to fit your preferences.

Command line basics.

The way that most Ruby programming is done is through the command line. Depending on your operating system, you'll have a few options.

• On Macs, you've got the Terminal, which is essentially a Unix shell in Bash (Bourne-Again SHell). This has an amazing amount of customization possible with a long history in the Linux/Unix/BSD world.
• On Windows, there's the Command Prompt (Windows Key, cmd). It's a little janky, but it'll do. I've developed Squib primarily in Windows using the Command Prompt.

The command line is where you initiate your commands. For example:

$ gem install squib
$ gem up squib
$ bundle install
$ ruby deck.rb
$ rake
$ cd c:\work\my-cool-game

This might seem arcane at first, but the command line is the single most powerful and expressive tool in computing... if you know how to harness it.

Edit-Run-Check.

To me, the most important word in all of software development is incremental. When you're climbing up a mountain by yourself, do you wait to put in anchors until you reach the summit? No!! You anchor yourself along the way frequently so that when you fall, it's not very far.

In programming, you need to be running your code often. Very often. In an expressive language like Ruby, you should be running your code every 60-90 seconds (seriously). Why? Because if you make a mistake, then you know that you made it in the last 60-90 seconds, and your problem is that much easier to solve. Solving one bug might take two minutes, but solving three bugs will take 20 (empirical studies have actually backed this up).

How much code can you write in 60-90 seconds? Maybe 1-5 lines, for fast typists. Think of it this way: the longer you go without running your code, the more debt you're accruing because it will take longer to fix all the bugs you haven't fixed yet.

That means your code should be stable very often. You'll pick up little tricks here and there. For example, whenever you type a (, you should immediately type a ) afterward and edit in the middle (some text editors even do this for you). Likewise, after every do you should type end (that's a Ruby thing). Tricks like that are all about reducing what you have to remember so that you can keep your code stable.

With Squib, you'll be doing one other thing: checking your output. Make sure you have some specific cards or output to check constantly to make sure the card is coming out the way you want. The Squib method save_png (or ones like it) should be one of the first methods you write when you make a new deck.

So, just to recap: your edit-run-check cycle should be very short. As a result, you'll have lots of windows open when working with Squib. You'll have a text editor to edit your source code, your spreadsheet (if you're working with one), a command line prompt, and a preview of your image files. (And now you understand more about why computer geeks have multiple monitors!)

Plan to Fail

If you get to a point where you can't possibly figure out what's going on that means one thing.

You're human.

Everyone runs into bugs they can't fix. Everyone. Take a break. Put it down. Talk about it out loud. And then, of course, you can always Get Help.

Ruby Learning Resources

Here are some of my favorite resources for getting started with Ruby. A lot of them assume you are also new to programming in general. They do cover material that isn't very relevant to Squib, but that's okay - learning is never wasted, only squandered.

CodeSchool's TryRuby. This is one of my favorites. It's pretty basic but it walks you through the exercises interactively and through challenges.

RubyMonk.com. An interactive explanation through Ruby. Gets a bit philosophical, but hey, what else would you expect from a monk??

Ruby's Own Website: Getting Started This will take you through the basics of programming in Ruby. It works mostly from the Interactive Ruby shell irb, which is pretty helpful for seeing how things work and what Ruby syntax looks like.

Why's Poignant Guide to Ruby No list of Ruby resources is complete without a reference to this, well, poignant guide to Ruby. Enjoy.