RobotLocomotion/drake — pull request #300 by rdeits (2014-08-15 16:37:34+00:00)
Title: First pass at using Matlab packages for the examples

Note: this pull request is not ready for merge, but I thought this would be a good format for discussing the changes anyway.

Matlab has support for "packages" which create namespaces much like packages in Java or Python. The advantage of these packages is that they make it easy to be very clear about which particular class, script, or function you mean to call (for example, I probably have 5 different files called "rotmat.m" floating around in my Matlab path, and I have no way to explicitly choose to use one or the other within my code). You can read more about what they do here: http://www.mathworks.com/help/matlab/matlab_oop/scoping-classes-with-packages.html

Andres and I have been using these for a few sub-projects lately, and they've made it a bit easier to organize lots of Matlab files. So, as an experiment, I'm testing them out for the "examples" folder. So far, I've converted the Acrobot, Airplane2D, and Atlas examples to package format, and I figured this would be a good place to stop and see if this is a good idea to continue with. You can check out this pull request and see what changes were required for yourself. They're all pretty superficial, and I was able to get rid of all of our in-function path manipulation, which is always messy and can have unfortunate side-effects. So, there's an obvious benefit in that we can get rid of all of the `oldpath = addpath('..');` code.

Honestly, I'm not sure if packages are something we actually want to deal with. Normally, you call a matlab function by adding its folder to your path or changing your current directory to that folder and then calling it by its filename:

cd myfolder
myfunc();

If, instead, you have a package (denoted by a folder starting with '+'), then you can refer to the function by its name within the package:

mypackage.myfunc();

or you can import the function and call it directly:

import mypackage.myfunc;
myfunc();

and you can import multiple functions:

import mypackage.*;
myfunc1();
myfunc2();

But there's a problem with all this, which I hadn't realized before: if your function is inside a package, then you *cannot* call it by just changing your current directory to that folder and you *cannot* add its folder to your path. You must always either import the package or call the function by its full name, including the package. That's really stupid, and I think it will confuse a lot of Matlab users, who would normally just `cd` into the examples/Atlas folder and try to run an example. Instead, those users would have to be trained to run something like:

examples.Atlas.runAtlasWalking();

or:

import examples.Atlas.*;
runAtlasWalking();

Namespaces are still [one honking great idea](https://www.python.org/doc/humor/#the-zen-of-python), but the Matlab implementation leaves a lot to be desired. I'm not sure if this is a switch worth making for us.