Where was I? In the previous Babystep, I started working out some rough ideas for a version of the old school Star Trader game written in Parrot PIR. I made a quick description and sketched up a list of the features that would need to be created. One of those features was an interactive shell to be used in developing and hacking on that Space Trade game. I wrote a simple shell that could be extended, making it easier to expand the capabilities of the shell in the future - or even use the shell in some completely unforeseen future application.
I like that shell, but it is not perfect. Programming languages like Parrot support namespaces, which you can think of as dictionaries that the language uses to look up variables and subroutines. My problem with the shell today revolves around the fact that every subroutine used in defining or extending the shell exists in the global namespace. They are available everywhere - in every line of code for the SpaceTrade game and anything that uses it. This may not be a huge problem by itself, because right now there are only a few subroutines. The number of subroutines will grow as the project evolves, however. This will have a couple of different effects.
- Subroutine names will be harder to remember, because the global namespace is one big bucket. I like to put related subroutines into little boxes so that I can focus on shell behavior when I’m looking at shell code, and game behavior when I’m looking at game code.
- Subroutine names could get rather contorted. What happens if I make Space Trade available, and against all odds it becomes a runaway success? Five, maybe even ten people download it and play it. It is likely that at least one of those people will want to write their own shell for the game. They will have to come up with some odd names for their shell code, such as
register_awesome_commands
, because I have selfishly used all the good names for my own shell.
Namespaces
Namespaces provide a way to insulate the parts of a computer program from each other. The subroutines and variables defined in one namespace will not interfere with the subroutines and variables in another. This means that I can have my register_default_commands
subroutine for my own shell, and you can have a register_default_commands
subroutine in your own shell, and they never need to know about each other. It does mean you must take extra steps if you want to use the subroutine from my package in your own code, or I must somehow provide a means to push the subroutines that I consider appropriate into your namespace. That is what Test::More does. Defining something like that is an exercise in careful judgment and reasonable coding. In other words, we will not be doing that with SpaceTrade any time soon.
I will try to focus on the most important elements of Parrot Namespaces rather than get carried away with all of the little details.
Organizing the Namespaces
Even though the SpaceTrade game has very little code right now, I want to put a little thought into organizing my namespaces before I create them. The first layer is easy: all of the code supporting the SpaceTrade game will go in the “SpaceTrade” namespace.
Parrot supports nested namespaces, so “SpaceTrade” can contain any number of namespaces. I’m sure there will be many contained namespaces for game setup and play, but I will only specify the one I am working on today: “SpaceTrade::Shell.”
- SpaceTrade: Code for the SpaceTrade Game
- SpaceTrade::Shell: A simple interactive shell for SpaceTrade
The names do not mean anything to Parrot. It does not force a particular way of organizing your namespaces. Nested namespaces are a convenience so that we know two chunks of code are somewhat related.
The .namespace
Directive
The .namespace
directive is used to tell Parrot that the following code belongs in a particular namespace. Its argument is a hash index specifying the name.
Use a complex key to indicate a nested namespace.
All of the code after the .namespace
directive gets filed in the namespace associated with the key you handed to it. This lasts until you declare a new namespace.
It’s time to try it out in spacetrade.pir
. All of the code written so far is for the shell, so I can probably get away with putting my .namespace
directive at the top of the file.
Why do I say “SpaceTrade::Shell” rather than ['SpaceTrade';'Shell']
when talking about my namespace in this article? That is mainly because I am lazy. My fingers do not enjoy typing out all the characters to say ['SpaceTrace';'Shell']
, so I want to use a shorthand. “SpaceTrade::Shell” mimics a convention used by some Parrot programmers when talking about namespaces. It is a convention derived from the way that namespaces - or “packages” - are declared in Perl, which is another language of choice for many Parrot developers. I will switch to another convention if I see one that is both widely used and easy to type.
Back to SpaceTrade. I run setup.pir test
out of curiosity.
The tests pass, which is kind of cool. But why do they pass, if I have defined a namespace in spacetrade.pir
? The tests should complain about missing subroutines if they are in a different namespace, right?
Yes, that is right. However, the .include
directive effectively dumps the code from your included file right where you put the directive. The tests exist in the ['SpaceTrade';'Shell']
namespace because we never indicated that we were moving onto a new one.
That might even be okay for these tests. After all, they are just telling me that the shell subroutines work, not that namespace handling works. The SpaceTrade namespaces are going to get more cluttered as time goes on, though. I am going to be more explicit in the namespace handling for my tests in order to prepare for that clutter.
The Default Namespace
To specify that you are going back to the default namespace, hand an empty key to the .namespace
directive.
I understand the idea here. The default namespace is no namespace at all, so it gets an empty key. Let’s put that line in 01-shell-metacommands.pir
.
What happens if I run the tests now?
This is the error I was expecting to see initially, so I am happy. I suppose I could have put that .namespace [ ]
directive at the end of spacetrade.pir
- Parrot does not have any rules about where to end one namespace and start another - but I feel like that would have broken the way .include
behaves. I will probably learn a better way to handle these little namespace issues eventually.
Now I have library code tucked into a namespace and test code that doesn’t know about the shell subroutines. A quick look at 07-writing-subroutines/ shows how to get those shell subroutines into our current namespace. The get_global
opcode allows us to grab a variable from another namespace. We used it in to grab the chomp
subroutine from the String::Utils namespace. Let’s use get_global
to make the tested subroutines available.
As we can see, that’s almost good enough.
Up until now we have been using subroutine names when registering commands, but that is not going to work anymore. SpaceTrade no longer knows exactly where it should look for the subroutines with those names. Instead of names, let’s try using the subroutines themselves.
register_command
doesn’t look a lot different. The names have changed to show what is going on, but we are still just building a Hash of commands and relying on evaluate_command
to sort out any problems.
Naturally, that means evaluate_command
is where the changes become obvious.
We do a few simple checks when somebody tries to evaluate a command.
- Do we have an entry for the command?
- Is there something actually at the entry?
- Is the thing stored for the command look like something we can treat as a subroutine?
That’s what the does
check handles, incidentally. Right now we only know about subroutines, but later on we may get into strange creations that aren’t subroutines but can be invoked as if they were. From what the folks on IRC #parrot
tell me, you would ask command_sub
if it is invokable. All I know is that it worked and that I like the folks on #parrot
very much.
We should make one more change before heading over to the tests. register_default_commands
needs to adjust to the new way of registering commands.
If you don’t explicitly hand a namespace to get_global
, it will use whatever namespace it’s called from. In this case, that is the SpaceTrade::Shell namespace.
We have to change the tests themselves now. There is actually only one test that needs to be changed. Look in 01-shell-metacommands.t
for the line that registers the :dude
command.
Instead of handing a string, create a PMC to hold the say_dude
subroutine and had that to register_command
.
Once again, we’re using get_global
to grab from the current namespace, which is the default namespace now.
All right, the tests should run okay.
It is possible to set and get truly global variables with get_root_global
and set_root_global
, but I do not recommend it. What happens if you decide that the global my_config
should be an Array instead of a Hash? Every piece of code that uses a global variable must be updated.
The same problem exists with package globals, even though it may be on a smaller scale. There’s a solution - or at least a way to make the problem even smaller. Whenever I see data and several subroutines that need to work on that data, I start to see objects.
Backlinks
Added to vault 2024-01-15. Updated on 2024-07-10