JMRI: The Python/Jython language
Python is a widely used scripting language that's available on many types of computers. A Java-based variant, called Jython, has been integrated with JMRI to make it easy to control a model railroad from the command line of a computer. For our purposes, the two languages are completely the same.If like me you prefer to read off paper, there are lots of books available on Python. Perhaps one of the best for beginners is "Learning Python" published by O'Reilly. It contains more than you really need to know, though.
The jython.org site has some introductory information, though their tutorial spends too much time on the engineering details at the beginning. You might want to skip to the part about the language itself.
Non-programmers might want to start with some of the resources for them listed on the python website.
If you are interested in the underlying technicalities of the language, IBM Developerworks has two good articles here and here. They also have a nice tutorial here, although they require you to register with your email address to access it.
Looking at the examples in the "jython" directory in the JMRI distribution will also be of value. See the examples page for links to these sample scripts.
How do Jython and Python differ?
For the purposes of writing JMRI scripts, they don't differ very much. Most of the differences involve what happens in somewhat contrived error cases. There are also some restrictions on what you can do with the computer's configuration information, etc, in Jython, but these are not things a JMRI script is likely to need.
Some additional information on the differences is available here.
IMPORTANT INFORMATION ABOUT PROGRAM FORMATTING: INDENTATION MATTERS
For example, this is a syntax error:
a = 15 print a b = 21because those statements, though logically grouped at the same level in the program, aren't indented the same. This sounds like a pain at first, but you rapidly get used to it. Then it makes things like the following pretty easy to read, without having to worry about where the { and } go:
if ( now == -1 ) : done = 1 else : done = 0 print doneIf you do get a message about "Syntax error", look at the indicated line number to see if your indentation isn't lined up.
Is JMRI's support for Python complete?
JMRI scripting uses Jython, a Java-implemented form of the Python language. The basic language is pretty complete, but not all of the Python libraries are available. Some "import" statements that you might read in a book might not work because of missing libraries.Support is improving all the time, though, and you might want to try a more modern version of Jython than the one that JMRI distributes. To do that, install Jython on you computer, then add a python.properties file in your user files directory or preferences directory that sets the python configuration variables, e.g. on Windows:
python.path = C:\\jython2.7.0\\Lib\\site\-packages python.startup =
Note that the double-back-slashes are necessary. They'll appear as single-back-slashes in the final value, which you can check with the "Context" item from the main JMRI Help menu. On Mac use something like:
python.path = /Users/username/jython2.7.0/Lib/site-packages python.startup =or where-ever you've installed the new Jython. Linux is similar.