Setting up a Gosu project

I thought I'd post a few quick entries about how I setup a really simple Gosu program that does a one-way push from our installation of Jira to our AgileZen board. It wasn't something complicated to build, but it really does a lot with only a little bit of (albeit messy) code. This program demonstrates some of the power of the Property-file and the XML type-loaders, as well as gives a basic template for how to start building your own Gosu utility programs.

Let me start with the basics of getting setup.  I started off by creating a development directory structure.  Down in a safe subdir for doing some work, I created a basic project structure much like you'd see in the java world.

It consists of a bin dir, that has my 'Gosu program' file that I'll use later as the executable entry point for my program.  I've also got a lib dir for my java jar files that I need, and a src dir that has my az and xsd packages.   That's really it, project structure-wise. 

Gosu programs (.gsp files) are the basic launch mechanism for a program.  To edit this, I bring up a cmd-line, and launch gosu with the -g option to open the built-in Gosu editor:

>gosu.cmd -g Jira2AgileZen.gsp

I'll skip the screenshot of the Gosu editor for now, but from later screenshots you can see that the Gosu Editor has basic context-highlighting, as well as 'intellisense' to help my get my method names and arguments right, some handy shortcuts like Ctrl-T to tell me what the type of any variable or expression is being evaluated as, Ctrl-N to load any .gst (Gosu template) .gs (Gosu class) or .gsx (Gosu enhancement).  The editor also provides familiar yellow and red underlining and scroll-bar notifications to tell me where I've got problems in my code.

Okay, back to my basic .gsp program.   It starts off with these 2 lines:

     #!/usr/bin/env gosu
  classpath "../src/,../lib/"

That first line, people coming from Unix or Linux, or a perl background might recognize as a hint to the OS on where to find the executable to run this program with.  It doesn't do any harm when I'm running it on Windows, but it helps when I'm running this from a crontab on one of the Linux boxes at work. If you don't need it, you can just omit that line.

The next line sets up my classpath.  Note that the syntax is different from a java classpath, as Gosu uses the comma separator between entries.  Much like a java classpath, I don't need to specify wildcards to include all the files in my ../src/ and ../lib/ directories.  

Next I have a bunch of 'uses' statements.  These are just like Java includes, and in the case of the first one I'm showing in my screenshot here, it's importing a java class.  I can also have uses statements for gosu classes.  Note that the Java package naming standards apply. 

Then I have instantiate a variable for my AZUtil class that I've created over in ../src/az/AZUtil.gs.   That Gosu class file has a bunch of utility functions to make my code ever-so-slightly more readable.  

And the last line uses a nice feature that is built into Gosu.  It's a Java property-file typeloader.   The Property file in my ../src/az dir is simply a set of name-value pairs that get loaded up at start-time into a set of Gosu types that I can access with intellisense type-ahead completion in the basic Gosu editor.  So the file AgileZen.properties simply has a few rows with my name-value pairs that I want to be able to modify without changing my program.  It's a dead-simple way to change the program behavior and not having to hard-code things like environment variables, usernames, etc.  into my Gosu program.

Okay, next up I'll delve into some of the XML parsing and XML generation, as well as Web Service calls for a REST service. If you are interested in seeing the source, it's available on github at https://github.com/prexer/Jira2AgileZen