Blog

As you all probably know, code-immersion is hosted on a service called GitHub. This, contrary to potential expectations, is not simply a funny-sounding name for yet another web service. Rather, it's a funny-sounding name with some level of reason for yet another web service. The name comes from the distributed version control system (DVCS) the site is rooted in, called git. If you haven't done much work with programming, you may not know what a version control system is; essentially, it's a place to keep all the code so that it's convenient for any number of programmers to grab and play with, without breaking anything permanently. It keeps track of changes and history and makes it easy to get, play with, and update code.

You can read about git at its own site, or ask me about it (in comments or by email or in person); the point of this post is really to say that, should you be interested, code-immersion is hosted in a git repository; if you have git, you can get it (clone, in git terminology) from git://github.com/ianmcorvidae/code-immersion.git and play with it in the usual ways (other than pushing back to github - to do that, talk to me or read up on how github itself works!).

The three main parts of the system are server.ss, daemon.ss, and client.ss; other files are either conceptually "above" this, making the software easier to use, or "below" this, providing functionality which these three major files use.

• server.ss defines the server, which listens for input. It can deal with input of a few varieties:

1. Registration: If sent a proper sort of message (this would be by a daemon), the server will add a connection to a specific daemon to its list of locations to dispatch text and code to.
2. Text and code to be dispatched: From a client, the server can receive text and code to dispatch out to the list of daemons which it has accumulated.

• daemon.ss defines the daemon, which listens for input of different sorts.

1. The daemon registers with a server (generally, configured by way of config.ss). After this, it receives input from the server when it dispatches text and code. The daemon puts this text and code into a datastore.
2. It also listens for input from clients; these constitute requests for text and code sent by others, which the daemon can then fetch from its datastore and send out. Alongside this the daemon also listens for requests for administrative things, such as reregistering with the server.

• client.ss does everything which a user actually uses to interact. Primarily, this consists of convenience functions which send things to the server and daemon and do various things with the response. The most-used level of these functions is documented in the (help) function of client.ss itself; these are all the functions for viewing and running text and code, listing users, reregistering, and so forth. There also exist lower-level functions which these build upon:

1. At the root is a (send-to) function.
2. On top of this are built (send-to-server) and (send-to-daemon)
3. On top of these are built (send-code), (send-message), (request-code), and (request-message).
4. On top of the request functions are built (display-message), (display-code), (evaluate-code), and (evaluate-list).
5. Finally, on top of these are built most of the functions defined in (help).
6. (run), (users), and (reregister) are notable in that they are built on lower-level functions; (run) is built on (request-code) rather than (evaluate-code) and (evaluate-list), while (users) and (reregister) are built on (send-to-daemon), there being no intermediate functions relating to their purpose.

Note that some of these functions aren't actually used at the top level; these might be useful for tweaking or extension of the system, however, so they are left in. Note that the top level of functions does not have hyphens; lower levels all do. This helps distinguish among the levels.

Below these three, there lie several files.

• config-example.ss is an example and template for config.ss, which is the file the three above files and several of the low-level files read in for basic options: the user's name, the locations of the server and daemon and the ports they use, the type of datastore, and the way to print things like text and code.
• datastore.ss defines different sorts of datastores. Right now, it only defines a hashtable datastore and has an aborted attempt at a list datastore -- but, it could easily be extended to other types of datastore, like the list datastore or persistent forms such as a text file or an SQL database. These would then be enabled by way of the configuration file.
• utilities.ss has a few functions which are shared among the three main files. It defines the listening-and-verifying loop which is at the core of both the server and the daemon, provides a data-verification function for things which are sent through the system (which the aforementioned loop uses), something which formats any valid message in a better-looking way (using the configuration parameter I mentioned above), and finally something which prints the source of the entire package (which is used by some functions which return that source, a requirement of AGPL compliance).

runserver.ss, runclient.ss, and project.ss are all negligible; they are ways of calling the three main files which don't require as much futzing-around with configuration files nor actual explicit starting of procedures. The starts of the first two create a config.ss and then start the server or daemon; the third just uses (require ...) to import the definitions from client.ss for use. As always: if you have questions, comments, or really anything at all, put it in the comments section below.

This post will go through each of the files of the code-immersion package and describe their function within the package. Files are in no particular order, but hopefully hopefully minimal things will rely on stuff described in files later in the list.

• COPYING and README: These should be the most transparent: COPYING is the license for code-immersion (it’s licensed under AGPLv3; for more information see the Free Software Foundation site http://www.fsf.org/licensing/licenses/agpl-3.0.html). README is the horrible underfunded help file I created, which needs improvement (that is, I need to write a real manual… someday).
• config-example.ss and config.ss: The first of these files is an example configuration file. The latter is the actual configuration file. This determines some universal things like one’s name, the location of the server and daemon, ports, and more low-level things. Almost everything else relies on the configuration, understandably.
• utilities.ss: This has some basic definitions which aren’t really configuration parameters, but which shouldn’t be defined in multiple places either. Stuff in here is used by all of server.ss, daemon.ss, and client.ss.
• datastore.ss: This defines the data-storage system(s). Currently, only the daemon actually uses this, but it’s something which could easily be useful for other programs, so I decided to separate it out. At the writing of this, the only type of datastore is a hashtable datastore (and an aborted attempt at a list datastore), but this could be extended (and probably should be).
• server.ss: Here’s the first file that has the real guts of the software. This is where everything that actually makes the server work resides. In fact, this is only four functions specific to this file (it uses utilities.ss and config.ss as well): register-client (which makes sure that a client (daemon, really) gets added to the list of places to send code and text), get-output-port-list (an internal function used by…), dispatch (which actually sends code and text out to daemons), and server (which is the server, which rolls all of this together and makes it useful).
• daemon.ss: Here lies the first half of what you-the-user know as the client. The daemon is the section of the client which registers with the server, receives code from it, and which stores things for the other half of the client to use, providing ways to access this data.
• client.ss: The other half of the client. This provides all the functions by which one sends text and code to the server and by which one retrieves text and code from the daemon (and additional functions to evaluate code after it’s retrieved).
• runclient.ss and runserver.ss: The first two of the convenience programs for actually using the software. runserver.ss runs the server without requiring any futzing-about with configuration files or explicitly starting anything. runclient.ss runs the daemon in a similar way, but asks for information for the configuration file which individual users might want to provide.
• project.ss: The final convenience file, this doesn’t really do anything; it’s just a stub of a file which uses a (require …) form to allow someone opening and running it to use all the functions provided by client.ss. This is where end-users who don’t know much of anything actually write code and use the software.

Questions/comments/concerns should go in the comments section below!