Skip to content
Julian Gonggrijp edited this page Aug 15, 2017 · 21 revisions

This page outlines the state of the Red Spider Project at the time of the last update (see above). Check out the network graph for a complete visual summary of all recent commits and the issue list for a complete overview of all unresolved issues.

Table of Contents

Community and infrastructure

Since the start of the project, about 18 people have contributed in one way or another. At least twice that many people have expressed interest, for example by forking the project or by posting to our forum thread. During busy periods, like now, five or more people may be actively contributing at the same time.

Apart from code, project members have created and maintained documentation (including this wiki), artwork, i.e. our logo and three candidates for an ASCII art mascot, and the IRC channel. The forum thread is also still available as a communication channel.

Our infrastructure partly consists of GitHub and partly of our own code. GitHub provides the source code management, the issue tracker and the wiki. Our own programs (in particular setup.py, rsshell and rshelp) take care of configuration, installation, online documentation and of course the Red Spider enviroment itself.

There is still enough room for improvement in our documentation and infrastructure.

User programs

These programs are directly available for use when you get started:

setup.py

Main article: setup.py

For an installation guide, see Getting started.

This is the installation script, which creates a few additional folders within the project root, copies some files and makes some additions to the user configuration. These steps enable the operation of rsshell (see below). Together, setup.py and rsshell make up most of the infrastructure of the project.

Currently setup.py can only "install" interpreted scripts because there hasn't been a need yet for installing compiled languages. Big changes are planned which should make the installation procedure a lot more general (see section "Plans" below).

rsshell

Main article: rsshell

Initially known as "the first command", this shell wrapper creates a suitable environment for other Red Spider software to operate in. Inside rsshell you can run any installed Red Spider command by just typing its name. The environment that rsshell creates ensures that the programs can find all their stuff even if your working directory happens to be at the other end of the filesystem. In other words, this is your portal into the "Red Spider world".

rsshell itself can always be run regardless of your working directory, thanks to setup.py.

rshelp

Without arguments, this command gives you a list of available commands. This list is also shown when you start rsshell. With an argument it will look for corresponding documentation, first in /doc (see Project directory overview) and then in an internal list of commands that can print their own documentation. So you can do the following:

rshelp rshelp      # explains rshelp, taken from /doc
rshelp xkcd-fetch  # explains xkcd-fetch, produced by running xkcd-fetch -h

You can document anything you want by placing a file about it in /doc, not just commands. So for example if you place a file named beer.txt in /doc, rshelp beer will reproduce what you've written about beer.

xkcd-fetch

As the name suggests, this command fetches xkcd comics with their metadata from the web and caches them on your hard drive. It can also print the metadata for a given comic in your terminal. Note that the program will wait for input (and may hence seem to run forever if you don't enter anything) unless you pass the -n flag. Run xkcd-fetch -h for a short manual.

xkcd-fetch is also work in progress; see the milestone "Overhaul xkcd-fetch".

xkcd-search

This command uses the cache from xkcd-fetch to search for xkcd comics that match a given regular expression (it does not download new data). The numbers of the comics that match the search expression are printed on stdout.

json-parse

This is a tool for quickly inspecting JSON data from the command line. It's a bit technical but can be very useful. Run rshelp json-parse for an explanation.

level_up

Calculates your RPG-style "level" in a programming language based on the number of lines of code you've written. When you first start using it, choose a directory where you'll keep track of your progress and run level_up -i <directory>. After that, every time you add code to the directory you can just run level_up. The program will display a popup if you moved a level up.

Testing is provided in test/level_up and a short usage message is shown if you run level_up -h.

summon

A very simple command for "summoning" files, which wraps the OS' builtin command for opening files from the command line in their default associated program. You can give it any number of paths and URLs and it will launch all of them.

fortune

A fun command that displays random quotes from the xkcd IRC channel. It manages an offline cache for when you have no internet connection. Run with the -h option for a quick manual.

godel

Applies Gödel numbering to translate numbers into formulas and vice versa. Call without arguments for an explanation.

random-number

This program returns a random number that was determined with a fair dice roll, like in comic 221. There's not much to explain about this command.

Geico

An insurance savings calculator directly inspired by http://xkcd.com/42. Run rshelp Geico for an explanation or just run the program to see what it does.

randomtext

A Markov chain random text generator. It takes a text file and a number, and takes as many words from the file (randomly) as the number specifies. Those words are joined into sentences in a clever way (this is the Markov chain part), and the end result looks surprisingly natural! For an example try randomtext work/xkcd-fetch/comic-data.txt 128.

phpBBthreadfetch

This program can scrape the contents of any thread at any phpBB forum you want. The resulting output contains the post number, author, date and body of all posts in the thread. Great if you want to analyze a forum game at the xkcd forums!

myentity

Replaces HTML entity codes (you know, those famous codes such as &amp;) in a text by their normal ASCII counterparts (& in this case).

geohash

Generates a geohash based on the Munroe Algorithm.

Libraries

Thanks to rsshell, our runtime libraries can reside in lib/ while clients need not specify the path. So if you use one of these libraries you can just import or link it by name.

xkcd-fetch (Python 2)

This library lets you import all comic database management functionality from the eponymous command. Because of the hyphen in the name you have to import it with a line like xf = __import__('xkcd-fetch') (the line is broken into pieces because of formatting issues but you can copy-paste it). For documentation of what's in there you can read the code in src/xkcd-fetch.py, or read src/xkcd-search.py for example usage.

level_up (Python 2, 3)

You can use this library to build a game on top of the level_up RPG (or to cheat). Read src/level_up.py for fairly well-written documentation.

myentity (Python 2)

Use the entity-replacing capabilities of the program with the same name in your own program. Documented with rshelp myentity.

Work in progress

The following commands were pushed to GitHub but haven't been merged into master yet:

advshell

An adventure shell, letting you explore the file system as if you were playing a text adventure.
Related issue: #37.

advbrowser

Also an adventure game, but browsing the web instead.
Branch: zed0/advbrowser.
Related issue: #36.

randomascii

An ASCII art generator that takes a random image from a given directory.
Branch: ovvy/rascii.
Help request: #49.

xkcd-windows-wallpaper

Changes the wallpaper to an xkcd comic of your choosing under Windows.

The first challenge is to add instructions so that other people can build the application using just the source from GitHub. The next challenge is to have it automatically installed by setup.py (only on Windows). In addition it would be nice if the app could rely on the database of xkcd-fetch (see above). The final challenge is to make it work on Mac OS X and Linux as well.

Branch: BRNMan/master.
Help request: #50.

spider-life

The "Game of Spiders", a Conway's Game of Life clone that offers two species (colors) instead of one and that lets you pick from several universe topologies. See this post and this post for more information.
Branch: xen-0/game-of-spiders.
Related issue: #24.
Pull request: #77.

git-creto

A convenience command for hackers that automatically deals with the boilerplate needed to start a new topic branch. This command is still in its infancy.
Request issue: #35.
Branch: JonETMeans/creto.
Pull request: #42.
Help request: #51.

raptors

A humorous text game where you are challenged to survive the raptor apocalypse.
It's backed by a wiki, so that anyone can contribute to the story. See here.
Branch: WesleyAC/raptors.
Issue: #70.

asciivideo

As the name suggests, this command plays videos to your terminal using ASCII grayscale!
Branch: WesleyAC/asciivideo.
Pull request: #76.

rsp-tutorial

A welcome tutorial for new users and hackers, which should ultimately guide you through most of the possibilities of the project. Right now it's little more than a menu.
Branch: mrhmouse/rsp-tutorial.

Plans and ideas

Several participants have expressed intentions to work on various aspects of the project. The list below is not meant to be exhaustive.

  • Develop a proper build system based on CMake, in order to use it as a backend for setup.py. See issue #33 and the associated milestone, as well as issue #24.
  • Improve the way setup.py works. sleepingdrone has submitted a patch that improves yes/no dialogs, which has already been merged (#68), while WesleyAC (#71) and firerogue (eaa8fb3f77) are still working on general improvements.

See also