There is an interactive Python console available from inside Gnumeric. This is a good place to explore things, and if the console is expanded, will be a nice place for scripting. In the meantime, what I have called "Spellbooks" below are much more useful, but are fixed plugins as of Gnumeric startup. So right now I putter in the console as I develop plugin literal in the form of spellbooks. After 1.2.0, Gnumeric will be working on its scripting API, so the two approaches may merge. Or not.
You can run a Python interpreter from inside Gnumeric, but you have to turn it on. To do this you simply uncomment a line in python-loader/plugins.xml. Normally, that file lives in /usr/lib/gnumeric/$version/plugins/python-loader/, or perhaps /usr/local/lib... on Red Hat. I used to suggest making a local but you should probably make a local copy, but that was pain for little gain. So:
gnumeric --version to make sure you get the right version name for the following. (You'll have to do this for every new version of Gnumeric!).
cd ~/.gnumeric/ $version /plugins/
Uncomment the five lines starting with ui-console-menu service near the bottom (remove the "<!--" and "-->" tags around the <service...> and </service> tags.
Save the file.
Start gnumeric (same version).
Select from the Tools the Python console.
At the top there is a drop-down menu Execute in. Right now your only choice will be Default. After you evaluate functions from other plugins, those environments will become available too (JK says this is called lazy loading). But I'll assume you are using Default. (The only real difference is that you have to import Gnumeric first, and you can't see your plugin functions.)
(Note: older releases required you to type print dir() instead of just dir(). Fixed in cvs 16 June 2003, and certainly in 1.1.20 and higher.
Let's start by taking a look at the environment.
>>> import 1Gnumeric >>> dir() ['Gnumeric', '__builtins__', '__doc__', '__name__'] >>> dir(Gnumeric) ['Boolean', 'CellPos', 'FALSE', 'GnumericError', 'GnumericErrorDIV0', 'GnumericErrorNA', 'GnumericErrorNAME', 'GnumericErrorNULL', 'GnumericErrorNUM', 'GnumericErrorRECALC', 'GnumericErrorREF', 'GnumericErrorVALUE', 'MStyle', 'Range', 'TRUE', '__doc__', '__name__', 2'functions', 'plugin_info', 'workbook_new', 'workbooks']
'Gnumeric' is a module that exists only within Gnumeric, and which defines the Gnumeric Python API.
Gnumeric.functions is the list of all the Gnumeric functions you would see in the function browser. You cannot yet do dir(Gnumeric.functions) but maybe someone will bind that soon.
RangeRef is not listed. That seems to limit us, though later in the tutorial we'll see how to use regular functions to get inside RangeRefs.
So do some exploring. First, let's poke around to figure out how to use CellPos.
# I wonder how to use CellPos (I've glanced at the source, but...) >>> dir(Gnumeric.CellPos) # shows nothing useful >>> Gnumeric.CellPos() TypeError: CellPos() takes exactly 2 arguments (0 given) >>> Gnumeric.CellPos("a1","a2") TypeError: an integer is required. # Right. >>> a=Gnumeric.CellPos(1,2) # It worked! >>> a <CellPos object at 0x106b6eb8> # Yeah, I know... >>> dir(a) ['get_tuple'] >>> a.get_tuple() (1,2) # Cool. That's (col,row) >>> str(a) # Super cool. 'B3' # JK hasn't implemented this for tuples yet
Similarly, we can explore Gnumeric.Range:
>>> r = Gnumeric.Range((1,2),(3,4)) TypeError: Range() argument 1 must be CellPos, not tuple >>> r = Gnumeric.Range(a,a) >>> r <Range object at 0x1071d888> >>> dir(r) ['get_tuple'] >>> r.get_tuple() (3, 7, 3, 7)
If you evaluate in the context of a plugin (rather than in Default), then dir(Gnumeric.plugin_info) will reveal some simple informational functions you can call for the local plugin(s).
Note: obviously I don't really know what I'm doing, or I wouldn't be poking around like this.
Jon K. Hellan writes, "Here are some more things you can do from the console:"
# Get a workbook >>> wb=Gnumeric.workbooks() >>> wb <Workbook object at 0x862a490> >>> dir(wb) >>> ['gui_add', 'sheet_add', 'sheets'] # Get a sheet >>> s=wb.sheets() >>> s <Sheet object at 0x863e8d0> >>> dir(s) ['cell_fetch', 'get_extent', 'get_name_unquoted', 'rename', 'style_apply_range', 'style_get', 'style_set_pos', 'style_set_range'] # Get a cell. s.cell_fetch(0,0) and s[0,0] are synonyms. First # coordinate is columns, i.e. s[1,0] is B1. >>> c=s[0,0] >>> c <Cell object at 0x863d810> >>> dir(c) ['get_entered_text', 'get_mstyle', 'get_rendered_text', 'get_value', 'get_value_as_string', 'set_text'] # Change the cell - it changes in the grid >>> c.set_text('foo') # Retrieve the cell - both ways. >>> c.get_value() foo >>> s.cell_fetch(0,0).get_value() foo
Very, very nice. Note, after setting a value, it won't show up until that cell is redrawn. That will happen automatically with plugin functions, but in the console, you may have to click on the cell.