OptionParser, FDoc and a built-in debugger

Debugger

I’ve been adding a bunch of new features to Fancy recently. The most exciting to me right now probably is the built-in debugger that comes with Fancy. It’s based on Rubinius’ built-in command-line debugger but obviously allows for Fancy-specific options and debugging support.

I started working on this after talking to Brian at Euruko 2012 in Amsterdam about Rubinius, ideas for Nikita (which he talked about in his talk) and tool support on top of Rubinius in general.

So if you want to debug some Fancy code, you can start up the command-line debugger like this:

$ fancy -debug <source_file>

This will launch you directly into the debugger before starting execution of the program. If you don’t pass a source file to execute along, it will simply start debugging Fancy’s REPL, ifancy, which always gets started when you don’t pass a source file to the fancy executable.

From the debugger prompt you can now specify breakpoints by class and method name, just as you’d do with Ruby and Rubinius’ debugger. See the official documentation page for Rubinius’ command-line debugger for general help on how to use it.

The main difference is that you can now set breakpoints on Fancy classes & methods, evaluate Fancy code right from within the debugger (and based on the environment you’re debugging) etc. It’s not perfect but it gets the job done. I do want to write a nicer, graphical debugger some time for Fancy using the available APIs Rubinius provides and that are used in the reference command-line debugger. Maybe once Nikita is ready and working, hooking it up with Fancy should be pretty straight forward.

The necessary changes to get the debugger working with Fancy are actually quite simple and short. The whole implementation is only 66 lines of Fancy code and is in Fancy’s repository at lib/rbx/debugger.fy.

Apart from starting up the debugger explicitly beforehand, you can also just set a breakpoint in your code explicitly and then run your code normally, like so:

require: "rbx/debugger"
def my_method {
  # do something
  # Pause execution and start up the debugger at this point:
  Rubinius Debugger start
  # do some more
}

For more information on available commands type help in the debugger prompt.

OptionParser

Fancy now also comes with a built-in OptionParser class that deals with your standard command-line option parsing needs. It’s basically inspired by Ruby’s optparse. It automatically provides a --help option using the information you provided when setting up your command-line options.

Here’s an example:

# Save this to options.fy
require: "option_parser"

o = OptionParser new: @{
  banner: "My crazy server options:"
  with: "-port [port]" doc: "Set the listening port" do: |port| {
    @port = port
  }
  with: "--auto-update" doc: "Auto update settings" do: {
    # do something really smart
  }
}

# you can pass any Array in here, but most people will just pass in ARGV:
o parse: ARGV

This will automatically provide the following --help option output:

$ fancy options.fy --help
My crazy server options:

  --auto-update  Auto update settings
  --help         Display this information
  -port [port]   Set the listening port

Options are sorted alphabetically in ascending order.

FDoc

FDoc has been a part of Fancy for quite some time now (~1.75 years) and generates the JSON based output for the API documentation page for Fancy available at: api.fancy-lang.org. Initially started and written by Victor Borja back in 2010, it never really was finished up to what he intended to do. And I also never really fully got into how it all worked until recently when I decided to start cleaning things up a bit and making it useful outside of just generating documentation for Fancy’s standard library itself.

I’m happy to say that as of now FDoc can be used to generate documentation pages similar to api.fancy-lang.org for any Fancy based project. It will even provide those nice GitHub links to method definitions, if you pass along the github repository user/reponame combination. I also fixed some bugs that I found and now when you click on the little octocat on the right side of a method documentation section, it’ll jump to GitHub and highlight the complete code of the method you were looking at before. It’s quite nice if you want to see what the actual implementation of a method looks like.

Run fdoc --help to see all available options.

What’s next?

I’ve been working on a bunch of other stuff that makes day-to-day development with Fancy easier and more fun. There’s Fake, a simple Rake like automation tool. I’ve started work on FPR, Fancy’s package registry (still in the making), that will allow searching for and adding of new Fancy packages available on GitHub. And of course a bunch of libraries I added or other people have contributed to the community. It’s still quite small and growing, but as the language matures, I’m sure more people will find interest in the language and want to help out.

I for myself am committed to this either way. :)

More updates coming soon.

Published

Tags

• debugging 1
• documentation 1
• tooling 1