ipy_leo: doc improvements

IPython/Extensions/ipy_leo.py

@@ -1,409 +1,409 b''
 """ ILeo - Leo plugin for IPython
 
    
 """
 import IPython.ipapi
 import IPython.genutils
 import IPython.generics
 from IPython.hooks import CommandChainDispatcher
 import re
 import UserDict
 from IPython.ipapi import TryNext 
 
 ip = IPython.ipapi.get()
 leo = ip.user_ns['leox']
 c,g = leo.c, leo.g
 
 # will probably be overwritten by user, but handy for experimentation early on
 ip.user_ns['c'] = c
 ip.user_ns['g'] = g
 
 
 from IPython.external.simplegeneric import generic 
 import pprint
 
 def es(s):    
     g.es(s, tabName = 'IPython')
     pass
 
 @generic
 def format_for_leo(obj):
     """ Convert obj to string representiation (for editing in Leo)"""
     return pprint.pformat(obj)
 
 @format_for_leo.when_type(list)
 def format_list(obj):
     return "\n".join(str(s) for s in obj)
 
 attribute_re = re.compile('^[a-zA-Z_][a-zA-Z0-9_]*$')
 def valid_attribute(s):
     return attribute_re.match(s)    
 
 def all_cells():
     d = {}
     for p in c.allNodes_iter():
         h = p.headString()
         if h.startswith('@a '):
             d[h.lstrip('@a ').strip()] = p.parent().copy()
         elif not valid_attribute(h):
             continue 
         d[h] = p.copy()
     return d    
     
 
 
 def eval_node(n):
     body = n.b    
     if not body.startswith('@cl'):
         # plain python repr node, just eval it
         return ip.ev(n.b)
     # @cl nodes deserve special treatment - first eval the first line (minus cl), then use it to call the rest of body
     first, rest = body.split('\n',1)
     tup = first.split(None, 1)
     # @cl alone SPECIAL USE-> dump var to user_ns
     if len(tup) == 1:
         val = ip.ev(rest)
         ip.user_ns[n.h] = val
         es("%s = %s" % (n.h, repr(val)[:20]  )) 
         return val
 
     cl, hd = tup 
 
     xformer = ip.ev(hd.strip())
     es('Transform w/ %s' % repr(xformer))
     return xformer(rest, n)
 
 class LeoNode(object, UserDict.DictMixin):
     """ Node in Leo outline
     
     Most important attributes (getters/setters available:
      .v     - evaluate node, can also be alligned 
      .b, .h - body string, headline string
      .l     - value as string list
     
     Also supports iteration, 
     
     setitem / getitem (indexing):  
      wb.foo['key'] = 12
      assert wb.foo['key'].v == 12
     
     Note the asymmetry on setitem and getitem! Also other
     dict methods are available. 
     
     .ipush() - run push-to-ipython
     
     """
     def __init__(self,p):
         self.p = p.copy()
 
     def __get_h(self): return self.p.headString()
     def __set_h(self,val):
         print "set head",val
         c.beginUpdate() 
         try:
             c.setHeadString(self.p,val)
         finally:
             c.endUpdate()
         
     h = property( __get_h, __set_h, doc = "Node headline string")  
 
     def __get_b(self): return self.p.bodyString()
     def __set_b(self,val):
         print "set body",val
         c.beginUpdate()
         try: 
             c.setBodyString(self.p, val)
         finally:
             c.endUpdate()
     
     b = property(__get_b, __set_b, doc = "Nody body string")
     
     def __set_val(self, val):        
         self.b = format_for_leo(val)
         
     v = property(lambda self: eval_node(self), __set_val, doc = "Node evaluated value")
     
     def __set_l(self,val):
         self.b = '\n'.join(val )
     l = property(lambda self : IPython.genutils.SList(self.b.splitlines()), 
                  __set_l, doc = "Node value as string list")
     
     def __iter__(self):
         """ Iterate through nodes direct children """
         
         return (LeoNode(p) for p in self.p.children_iter())
 
     def __children(self):
         d = {}
         for child in self:
             head = child.h
             tup = head.split(None,1)
             if len(tup) > 1 and tup[0] == '@k':
                 d[tup[1]] = child
                 continue
             
             if not valid_attribute(head):
                 d[head] = child
                 continue
         return d
     def keys(self):
         d = self.__children()
         return d.keys()
     def __getitem__(self, key):
         """ wb.foo['Some stuff'] Return a child node with headline 'Some stuff'
         
         If key is a valid python name (e.g. 'foo'), look for headline '@k foo' as well
         """  
         key = str(key)
         d = self.__children()
         return d[key]
     def __setitem__(self, key, val):
         """ You can do wb.foo['My Stuff'] = 12 to create children 
         
         This will create 'My Stuff' as a child of foo (if it does not exist), and 
         do .v = 12 assignment.
         
         Exception:
         
         wb.foo['bar'] = 12
         
         will create a child with headline '@k bar', because bar is a valid python name
         and we don't want to crowd the WorkBook namespace with (possibly numerous) entries
         """
         key = str(key)
         d = self.__children()
         if key in d:
             d[key].v = val
             return
         
         if not valid_attribute(key):
             head = key
         else:
             head = '@k ' + key
         p = c.createLastChildNode(self.p, head, '')
         LeoNode(p).v = val
     def __delitem__(self,key):
         pass
     def ipush(self):
         """ Does push-to-ipython on the node """
         push_from_leo(self)
     def go(self):
         """ Set node as current node (to quickly see it in Outline) """
         c.beginUpdate()
         try:
             c.setCurrentPosition(self.p)
         finally:
             c.endUpdate()  
         
     def __get_uA(self):
         p = self.p
         # Create the uA if necessary.
         if not hasattr(p.v.t,'unknownAttributes'):
             p.v.t.unknownAttributes = {}        
         
         d = p.v.t.unknownAttributes.setdefault('ipython', {})
         return d        
-    uA = property(__get_uA, doc = "Access persistent unknownAttributes of node'")
+    uA = property(__get_uA, doc = "Access persistent unknownAttributes of node")
         
 
 class LeoWorkbook:
     """ class for 'advanced' node access 
     
     Has attributes for all "discoverable" nodes. Node is discoverable if it 
     either
     
     - has a valid python name (Foo, bar_12)
     - is a parent of an anchor node (if it has a child '@a foo', it is visible as foo)
     
     """
     def __getattr__(self, key):
         if key.startswith('_') or key == 'trait_names' or not valid_attribute(key):
             raise AttributeError
         cells = all_cells()
         p = cells.get(key, None)
         if p is None:
             p = add_var(key)
 
         return LeoNode(p)
 
     def __str__(self):
         return "<LeoWorkbook>"
     def __setattr__(self,key, val):
         raise AttributeError("Direct assignment to workbook denied, try wb.%s.v = %s" % (key,val))
         
     __repr__ = __str__
     
     def __iter__(self):
         """ Iterate all (even non-exposed) nodes """
         cells = all_cells()
         return (LeoNode(p) for p in c.allNodes_iter())
     
 ip.user_ns['wb'] = LeoWorkbook()
 
 
 
 @IPython.generics.complete_object.when_type(LeoWorkbook)
 def workbook_complete(obj, prev):
     return all_cells().keys()
     
 
 def add_var(varname):
     c.beginUpdate()
     try:
         p2 = g.findNodeAnywhere(c,varname)
         if p2:
             return
 
         rootpos = g.findNodeAnywhere(c,'@ipy-results')
         if not rootpos:
             rootpos = c.currentPosition() 
         p2 = rootpos.insertAsLastChild()
         c.setHeadString(p2,varname)
         return p2
     finally:
         c.endUpdate()
 
 def add_file(self,fname):
     p2 = c.currentPosition().insertAfter()
 
 push_from_leo = CommandChainDispatcher()
 
 def expose_ileo_push(f, prio = 0):
     push_from_leo.add(f, prio)
 
 def push_ipython_script(node):
     """ Execute the node body in IPython, as if it was entered in interactive prompt """
     c.beginUpdate()
     try:
         ohist = ip.IP.output_hist 
         hstart = len(ip.IP.input_hist)
         script = g.getScript(c,node.p,useSelectedText=False,forcePythonSentinels=False,useSentinels=False)
         
         script = g.splitLines(script + '\n')
         
         ip.runlines(script)
         
         has_output = False
         for idx in range(hstart,len(ip.IP.input_hist)):
             val = ohist.get(idx,None)
             if val is None:
                 continue
             has_output = True
             inp = ip.IP.input_hist[idx]
             if inp.strip():
                 es('In: %s' % (inp[:40], ))
                 
             es('<%d> %s' % (idx, pprint.pformat(ohist[idx],width = 40)))
         
         if not has_output:
             es('ipy run: %s (%d LL)' %( node.h,len(script)))
     finally:
         c.endUpdate()
 
 # this should be the LAST one that will be executed, and it will never raise TryNext
 expose_ileo_push(push_ipython_script, 1000)
     
 def eval_body(body):
     try:
         val = ip.ev(body)
     except:
         # just use stringlist if it's not completely legal python expression
         val = IPython.genutils.SList(body.splitlines())
     return val 
     
 def push_plain_python(node):
     if not node.h.endswith('P'):
         raise TryNext
     script = g.getScript(c,node.p,useSelectedText=False,forcePythonSentinels=False,useSentinels=False)
     lines = script.count('\n')
     try:
         exec script in ip.user_ns
     except:
         print " -- Exception in script:\n"+script + "\n --"
         raise
     es('ipy plain: %s (%d LL)' % (node.h,lines))
     
 expose_ileo_push(push_plain_python, 100)
 
 def push_cl_node(node):
     """ If node starts with @cl, eval it
     
     The result is put to root @ipy-results node
     """
     if not node.b.startswith('@cl'):
         raise TryNext
         
     p2 = g.findNodeAnywhere(c,'@ipy-results')
     val = node.v
     if p2:
         es("=> @ipy-results")
         LeoNode(p2).v = val
     es(val)
 
 expose_ileo_push(push_cl_node,100)
 
 def push_position_from_leo(p):
     push_from_leo(LeoNode(p))   
     
 ip.user_ns['leox'].push = push_position_from_leo    
     
 def leo_f(self,s):
     """ open file(s) in Leo
     
     Takes an mglob pattern, e.g. '%leo *.cpp' or %leo 'rec:*.cpp'  
     """
     import os
     from IPython.external import mglob
     
     files = mglob.expand(s)
     c.beginUpdate()
     try:
         for fname in files:
             p = g.findNodeAnywhere(c,'@auto ' + fname)
             if not p:
                 p = c.currentPosition().insertAfter()
             
             p.setHeadString('@auto ' + fname)
             if os.path.isfile(fname):
                 c.setBodyString(p,open(fname).read())
             c.selectPosition(p)
     finally:
         c.endUpdate()
 
 ip.expose_magic('leo',leo_f)
 
 def leoref_f(self,s):
     """ Quick reference for ILeo """
     import textwrap
     print textwrap.dedent("""\
     %leo file - open file in leo
     wb.foo.v  - eval node foo (i.e. headstring is 'foo' or '@ipy foo')
     wb.foo.v = 12 - assign to body of node foo
     wb.foo.b - read or write the body of node foo
     wb.foo.l - body of node foo as string list
     
     for el in wb.foo:
       print el.v
        
     """
     )
 ip.expose_magic('leoref',leoref_f)
 
 def show_welcome():
     print "------------------"
     print "Welcome to Leo-enabled IPython session!"
     print "Try %leoref for quick reference."
     import IPython.platutils
     IPython.platutils.set_term_title('ILeo')
     IPython.platutils.freeze_term_title()
 
 def run_leo_startup_node():
     p = g.findNodeAnywhere(c,'@ipy-startup')
     if p:
         print "Running @ipy-startup nodes"
         for n in LeoNode(p):
             push_from_leo(n)
 
 run_leo_startup_node()
 show_welcome()
 

doc/examples/leo_bridge_demo.leo

@@ -1,409 +1,508 b''
 <?xml version="1.0" encoding="utf-8"?>
 <?xml-stylesheet ekr_test?>
 <leo_file>
 <leo_header file_format="2" tnodes="0" max_tnode_index="0" clone_windows="0"/>
-<globals body_outline_ratio="0.5">
-	<global_window_position top="261" left="404" height="621" width="1280"/>
+<globals body_outline_ratio="0.307814992026">
+	<global_window_position top="140" left="145" height="627" width="1280"/>
 	<global_log_window_position top="0" left="0" height="0" width="0"/>
 </globals>
 <preferences/>
 <find_panel_settings/>
 <vnodes>
+<v t="vivainio.20080222193236" a="E"><vh>Documentation</vh>
+<v t="vivainio.20080223121915" a="E" tnodeList="vivainio.20080223121915,vivainio.20080222193236.1,vivainio.20080223133858,vivainio.20080223133922,vivainio.20080223133947,vivainio.20080223134018,vivainio.20080223134100,vivainio.20080223134118,vivainio.20080223134433,vivainio.20080223142207,vivainio.20080223134136"><vh>@nosent ileointro.txt</vh>
+<v t="vivainio.20080222193236.1" a="E"><vh>Documentation</vh>
+<v t="vivainio.20080223133858"><vh>Introduction</vh></v>
+<v t="vivainio.20080223133922"><vh>Installation</vh></v>
+<v t="vivainio.20080223133947"><vh>Accessing IPython from Leo</vh></v>
+<v t="vivainio.20080223134018" a="TV"><vh>Accessing Leo nodes from IPython</vh></v>
+<v t="vivainio.20080223134100"><vh>Cl definitions</vh></v>
+<v t="vivainio.20080223134118"><vh>Special node types</vh></v>
+<v t="vivainio.20080223134433"><vh>Custom push</vh></v>
+<v t="vivainio.20080223142207" a="E"><vh>Code snippets</vh></v>
+<v t="vivainio.20080223134136"><vh>Acknowledgements and history</vh></v>
+</v>
+</v>
+</v>
 <v t="vivainio.20080218184525"><vh>@chapters</vh></v>
-<v t="vivainio.20080223133721" a="E"><vh>@settings</vh>
+<v t="vivainio.20080223133721"><vh>@settings</vh>
 <v t="vivainio.20080223133721.1"><vh>@enabled-plugins</vh></v>
 </v>
 <v t="vivainio.20080218184540" a="E"><vh>@ipy-startup</vh>
 <v t="vivainio.20080218184613.1"><vh>b</vh></v>
-<v t="vivainio.20080218200031" a="E"><vh>Some classes P</vh>
+<v t="vivainio.20080218200031"><vh>Some classes P</vh>
 <v t="vivainio.20080218190816"><vh>File-like access</vh></v>
 <v t="vivainio.20080218200106"><vh>csv data</vh></v>
 <v t="vivainio.20080219225120"><vh>String list</vh></v>
 <v t="vivainio.20080219230342"><vh>slist to leo</vh></v>
 </v>
 </v>
 <v t="vivainio.20080218195413"><vh>Class tests</vh>
 <v t="vivainio.20080218200509"><vh>csvr</vh></v>
 <v t="vivainio.20080218191007"><vh>tempfile</vh></v>
 <v t="vivainio.20080218195413.1"><vh>rfile</vh></v>
 <v t="vivainio.20080219225804"><vh>strlist</vh></v>
 </v>
 <v t="vivainio.20080218201219"><vh>Direct variables</vh>
 <v t="vivainio.20080222201226"><vh>NewHeadline</vh></v>
 <v t="vivainio.20080218201219.2"><vh>bar</vh></v>
 </v>
-<v t="vivainio.20080222193236" a="E"><vh>Docs</vh>
-<v t="vivainio.20080223121915" a="E" tnodeList="vivainio.20080223121915,vivainio.20080222193236.1,vivainio.20080223133858,vivainio.20080223133922,vivainio.20080223133947,vivainio.20080223134018,vivainio.20080223134100,vivainio.20080223134118,vivainio.20080223134433,vivainio.20080223134136"><vh>@nosent ileointro.txt</vh>
-<v t="vivainio.20080222193236.1" a="E"><vh>Quick intro</vh>
-<v t="vivainio.20080223133858"><vh>Introduction</vh></v>
-<v t="vivainio.20080223133922"><vh>Installation</vh></v>
-<v t="vivainio.20080223133947"><vh>Accessing IPython from Leo</vh></v>
-<v t="vivainio.20080223134018"><vh>Accessing Leo nodes from IPython</vh></v>
-<v t="vivainio.20080223134100"><vh>Cl definitions</vh></v>
-<v t="vivainio.20080223134118"><vh>Special node types</vh></v>
-<v t="vivainio.20080223134433" a="TV"><vh>Custom push</vh></v>
-<v t="vivainio.20080223134136"><vh>Acknowledgements and history</vh></v>
+<v t="vivainio.20080222202211"><vh>test stuff</vh></v>
+<v t="vivainio.20080223142403" a="E"><vh>@ipy-results</vh>
+<v t="vivainio.20080223142403.1"><vh>foo</vh></v>
+<v t="vivainio.20080223152600" a="E"><vh>baz</vh>
+<v t="vivainio.20080223174603"><vh>@k hello</vh></v>
 </v>
 </v>
+<v t="vivainio.20080222202211.1"><vh>spam</vh>
+<v t="vivainio.20080223180139"><vh>foo bar</vh></v>
 </v>
-<v t="vivainio.20080222202211"><vh>test stuff</vh></v>
-<v t="vivainio.20080222202211.1"><vh>spam</vh></v>
 <v t="vivainio.20080222202211.2"><vh>NewHeadline</vh></v>
 </vnodes>
 <tnodes>
 <t tx="vivainio.20080218184525">?</t>
 <t tx="vivainio.20080218184540">?Direct children of this node will be pushed at ipython bridge startup
 
 This node itself will *not* be pushed</t>
 <t tx="vivainio.20080218184613.1">print "world"</t>
 <t tx="vivainio.20080218190816">def rfile(body,n):
     """ @cl rfile 
 
     produces a StringIO (file like obj of the rest of the body) """
 
     import StringIO
     return StringIO.StringIO(body)
 
 def tmpfile(body,n):
     """ @cl tmpfile
 
     Produces a temporary file, with node body as contents
 
     """
     import tempfile
     h, fname = tempfile.mkstemp()
     f = open(fname,'w')
     f.write(body)
     f.close()
     return fname
 </t>
 <t tx="vivainio.20080218191007">@cl tmpfile
 
 Hello</t>
 <t tx="vivainio.20080218195413">?</t>
 <t tx="vivainio.20080218195413.1">@cl rfile
 These
 lines
 should 
 be
 readable </t>
 <t tx="vivainio.20080218200031">@others</t>
 <t tx="vivainio.20080218200106">def csvdata(body,n):
     import csv
     d = csv.Sniffer().sniff(body)
     reader = csv.reader(body.splitlines(), dialect = d)
     return reader</t>
 <t tx="vivainio.20080218200509">@cl csvdata
 
 a,b,b
 1,2,2</t>
 <t tx="vivainio.20080218201219"></t>
 <t tx="vivainio.20080218201219.2">@cl
 "hello world"</t>
 <t tx="vivainio.20080219225120">import IPython.genutils
 def slist(body,n):
     return IPython.genutils.SList(body.splitlines())
 </t>
 <t tx="vivainio.20080219225804">@cl slist
 hello
 world
 on
 many
 lines
 </t>
 <t tx="vivainio.20080219230342">import ipy_leo
 @ipy_leo.format_for_leo.when_type(IPython.genutils.SList)
 def format_slist(obj):
     return "@cl slist\n" + obj.n
 </t>
-<t tx="vivainio.20080222193236"></t>
+<t tx="vivainio.20080222193236">?</t>
 <t tx="vivainio.20080222193236.1">@wrap
 @nocolor</t>
 <t tx="vivainio.20080222201226">1+2
 print "hello"
 3+4
 
 def f(x):
     return x.upper()
 
 f('hello world')</t>
 <t tx="vivainio.20080222202211"></t>
-<t tx="vivainio.20080222202211.1">@cl rfile
+<t tx="vivainio.20080222202211.1" ipython="7d71005506636f6f7264737101284b0c4bde747102732e">@cl rfile
 hello
 world
 and whatever</t>
 <t tx="vivainio.20080222202211.2"></t>
 <t tx="vivainio.20080223121915">@others
 </t>
 <t tx="vivainio.20080223133721"></t>
 <t tx="vivainio.20080223133721.1">ipython.py</t>
 <t tx="vivainio.20080223133858">
 Introduction
 ============
 
 The purpose of ILeo, or leo-ipython bridge, is being a two-way communication
 channel between Leo and IPython. The level of integration is much deeper than
 conventional integration in IDEs; most notably, you are able to store *data* in
 Leo nodes, in addition to mere program code. The possibilities of this are
 endless, and this degree of integration has not been seen previously in the python
 world.
 
 IPython users are accustomed to using things like %edit to produce non-trivial
 functions/classes (i.e. something that they don't want to enter directly on the
 interactive prompt, but creating a proper script/module involves too much
 overhead). In ILeo, this task consists just going to the Leo window, creating a node
 and writing the code there, and pressing alt+I (push-to-ipython).
 
 Obviously, you can save the Leo document as usual - this is a great advantage
 of ILeo over using %edit, you can save your experimental scripts all at one
 time, without having to organize them into script/module files (before you
 really want to, of course!)
 </t>
 <t tx="vivainio.20080223133922">
 Installation
 ============
 
 You need at least Leo 4.4.7, and the development version of IPython (ILeo
 will be incorporated to IPython 0.8.3).
 
 You can get IPython from Launchpad by installing bzr and doing
 
 bzr branch lp:ipython
 
 and running "setup.py install".
 
 You need to enable the 'ipython.py' plugin in Leo: 
 
 - Help -&gt; Open LeoSettings.leo
 
 - Edit @settings--&gt;Plugins--&gt;@enabled-plugins, add/uncomment 'ipython.py'
 
+- Alternatively, you can add @settings--&gt;@enabled-plugins with body ipython.py to your leo document.
+
 - Restart Leo. Be sure that you have the console window open (start leo.py from console, or double-click leo.py on windows)
 
 - Press alt+5 OR alt-x start-ipython to launch IPython in the console that
 started leo. You can start entering IPython commands normally, and Leo will keep
 running at the same time.
 </t>
 <t tx="vivainio.20080223133947">
 Accessing IPython from Leo
 ==========================
 
 IPython code
 ------------
 
 Just enter IPython commands on a Leo node and press alt-I to execute
-push-to-ipython to execute the script in IPython. 'commands' is interpreted
-loosely here - you can enter function and class definitions, in addition to the
-things you would usually enter at IPython prompt - calculations, system commands etc.
+push-to-ipython in order to execute the script in IPython. 'commands' is
+interpreted loosely here - you can enter function and class definitions, in
+addition to the things you would usually enter at IPython prompt - calculations,
+system commands etc.
 
 Everything that would be legal to enter on IPython prompt is legal to execute
 from ILeo.
 
 Results will be shows in Leo log window for convenience, in addition to the console.
 
 Suppose that a node had the following contents:
 {{{
 1+2
 print "hello"
 3+4
 
 def f(x):
     return x.upper()
 
 f('hello world')
 }}}
 
-If you press alt+I on that done, you will see the following in Leo log window (IPython tab):
+If you press alt+I on that node, you will see the following in Leo log window (IPython tab):
 
 {{{
 In: 1+2
 &lt;2&gt; 3
 In: 3+4
 &lt;4&gt; 7
 In: f('hello world')
 &lt;6&gt; 'HELLO WORLD'
 }}}
 
-(numbers like &lt;6&gt; mean IPython output history indices).
+(numbers like &lt;6&gt; mean IPython output history indices; the actual object can be
+referenced with _6 as usual in IPython).
 
 
 Plain Python code
 -----------------
 
 If the headline of the node ends with capital P, alt-I will not run the code
 through IPython translation mechanism but use the direct python 'exec' statement
 (in IPython user namespace) to execute the code. It wont be shown in IPython
 history, and sometimes it is safer (and more efficient) to execute things as
 plain Python statements. Large class definitions are good candidates for P
 nodes.
 </t>
 <t tx="vivainio.20080223134018">
 Accessing Leo nodes from IPython
 ================================
 
 The real fun starts when you start entering text to leo nodes, and are using
 that as data (input/output) for your IPython work.
 
 Accessing Leo nodes happens through the variable 'wb' (short for "WorkBook")
 that exist in the IPython user namespace. Nodes that are directly accessible are
 the ones that have simple names which could also be Python variable names;
 'foo_1' will be accessible directly from IPython, whereas 'my scripts' will not.
 If you want to access a node with arbitrary headline, add a child node '@a foo'
 (@a stands for 'anchor'). Then, the parent of '@a foo' is accessible through
 'wb.foo'.
 
 You can see what nodes are accessible be entering (in IPython) wb.&lt;TAB&gt;. Example:
 
 [C:leo/src]|12&gt; wb.
 wb.b           wb.tempfile    wb.rfile       wb.NewHeadline
 wb.bar         wb.Docs        wb.strlist     wb.csvr    
+[C:leo/src]|12&gt; wb.tempfile
+           &lt;12&gt; &lt;ipy_leo.LeoNode object at 0x044B6D90&gt;
+
+So here, we meet the 'LeoNode' class that is your key to manipulating Leo
+content from IPython!
+
+LeoNode
+-------
 
 Suppose that we had a node with headline 'spam' and body: 
 
 ['12',2222+32]
 
 we can access it from IPython (or from scripts entered into other Leo nodes!) by doing:
 
 C:leo/src]|19&gt; wb.spam.v
           &lt;19&gt; ['12', 2254]
 
 'v' attribute stands for 'value', which means the node contents will be run
 through 'eval' and everything you would be able to enter into IPython prompt
 will be converted to objects. This mechanism can be extended far beyond direct
 evaluation (see '@cl definitions').
 
 'v' attribute also has a setter, i.e. you can do:
 
 wb.spam.v = "mystring"
 
 Which will result in the node 'spam' having the following text:
 
 'mystring'
 
 What assignment to 'v' does can be configured through generic functions
-(simplegeneric module, will be explained later).
+('simplegeneric' module, will be explained later).
+
+Besides v, you can set the body text directly through 
+
+wb.spam.b = "some\nstring", 
+
+headline by 
+
+wb.spam.h = 'new_headline' 
 
-Besides v, you can set the body text directly through wb.spam.b =
-"some\nstring", headline by wb.spam.h = 'new_headline' (obviously you must
-access the node through wb.new_headline from that point onwards), and access the
-contents as string list (IPython SList) through 'wb.spam.l'.
+(obviously you must access the node through wb.new_headline from that point
+onwards), and access the contents as string list (IPython SList) through
+'wb.spam.l'.
 
 If you do 'wb.foo.v = 12' when node named 'foo' does not exist, the node titled
 'foo' will be automatically created and assigned body 12.
+
+LeoNode also supports go() that focuses the node in the Leo window, ipush that
+simulates pressing alt+I on the node.
+
+You can access unknownAttributes by .uA property dictionary. Unknown attributes
+allow you to store arbitrary (pickleable) python objects in the Leo nodes;
+the attributes are stored when you save the .leo document, and recreated when
+you open the document again. Example::
+
+    [C:leo/src]|12&gt; wb.spam.uA['coords'] = (12,222)
+    [C:leo/src]|13&gt; wb.spam.uA
+               &lt;13&gt; {'coords': (12, 222)}    
+
+Accessing children with iteration and dict notation
+---------------------------------------------------
+
+Sometimes, you may want to treat a node as a 'database', where the nodes
+children represent elements in the database. You can create a new child node for
+node 'spam', with headline 'foo bar' like this:
+
+    wb.spam['foo bar'] = "Hello"
+
+And assign a new value for it by doing 
+
+    wb.spam['foo bar'].v = "Hello again"
+
+Note how you can't use .v when you first create the node - i.e. the node needs
+to be initialized by simple assignment, that will be interpreted as assignment
+to '.v'. This is a conscious design choice.
+
+If you try to do wb.spam['bar'] = 'Hello', ILeo will assign '@k bar' as the
+headline for the child instead, because 'bar' is a legal python name (and as
+such would be incorporated in the workbook namespace). This is done to avoid
+crowding the workbook namespace with extraneous items. The item will still be
+accessible as wb.spam['bar']
+
+LeoNodes are iterable, so to see the headlines of all the children of 'spam' do:
+
+    for n in wb.spam:
+        print n.h
 </t>
 <t tx="vivainio.20080223134100">
 @cl definitions
 ===============
 
 If the first line in the body text is of the form '@cl sometext', IPython will
-will evaluate 'sometext' and call the result with the rest of the body when you
-do 'wb.foo.v'. An example is in place here. Suppose that we have defined a class
-(I use the term class in a non-python sense here)
+evaluate 'sometext' and call the result with the rest of the body when you do
+'wb.foo.v'. An example is in place here. Suppose that we have defined a class (I
+use the term class in a non-python sense here)
 
 {{{
-def rfile(body,n):
+def rfile(body,node):
     """ @cl rfile 
 
     produces a StringIO (file like obj) of the rest of the body """
 
     import StringIO
     return StringIO.StringIO(body)
 }}}
 
-Now, let's say you node 'spam' with text
+(note that node is ignored here - but it could be used to access headline,
+children etc.),
+
+Now, let's say you have node 'spam' with text
 
 {{{
 @cl rfile
 hello
 world
 and whatever
 }}}
 
-Now, on IPython, we can do this:
+Now, in IPython, we can do this:
 
 {{{    
 [C:leo/src]|22&gt; f = wb.spam.v
 [C:leo/src]|23&gt; f
            &lt;23&gt; &lt;StringIO.StringIO instance at 0x04E7E490&gt;
 [C:leo/src]|24&gt; f.readline()
            &lt;24&gt; u'hello\n'
 [C:leo/src]|25&gt; f.readline()
            &lt;25&gt; u'world\n'
 [C:leo/src]|26&gt; f.readline()
            &lt;26&gt; u'and whatever'
 [C:leo/src]|27&gt; f.readline()
            &lt;27&gt; u''    
 }}} 
 
-You should declare new @cl types to make ILeo as convenient your problem domain as possible. For example, a "@cl etree" could return the elementtree object for xml content, or 
+You should declare new @cl types to make ILeo as convenient your problem domain
+as possible. For example, a "@cl etree" could return the elementtree object for
+xml content.
 </t>
 <t tx="vivainio.20080223134118">
 Special node types
 ==================
 
 @ipy-startup
 ------------
 
 If this node exist, the *direct children* of this will be pushed to IPython when
 ILeo is started (you press alt+5). Use it to push your own @cl definitions etc.
 The contents of of the node itself will be ignored.
 
 @ipy-results
 ------------
 
 When you create a new node (wb.foo.v = 'stuff'), the node foo will be created as
 a child of this node. If @ipy-results does not exist, the new node will be created after the currently selected node.
 
 @a nodes
 --------
 
 You can attach these as children of existing nodes to provide a way to access
 nodes with arbitrary headlines, or to provide aliases to other nodes. If
 multiple @a nodes are attached as children of a node, all the names can be used
 to access the same object.
 </t>
 <t tx="vivainio.20080223134136">
 Acknowledgements &amp; History
 ==========================
 
 This idea got started when I (Ville) saw this post by Edward Ream (the author of
 Leo) on IPython developer mailing list:
 
     http://lists.ipython.scipy.org/pipermail/ipython-dev/2008-January/003551.html
 
 I was using FreeMind as mind mapping software, and so I had an immediate use
 case for Leo (which, incidentally, is superior to FreeMind as mind mapper). The
 wheels started rolling, I got obsessed with the power of this concept
 (everything clicked together), and Edwards excitement paralleled mine.
 Everything was mind-bogglingly easy/trivial, something that is typical of all
 revolutionary technologies (think Python here).
 
 The discussion that "built" ILeo is here:
     http://sourceforge.net/forum/forum.php?thread_id=1911662&amp;forum_id=10226    
 
 ?</t>
 <t tx="vivainio.20080223134433">
 Declaring custom push-to-ipython handlers
 =========================================
 
 Sometimes, you might want to configure what alt+I on a node does. You can do
 that by creating your own push function and expose it using
 ipy_leo.expose_ileo_push(f, priority). The function should check whether the
-node should by handled by it and raise IPython.ipapi.TryNext if it will not do
-the handling.
+node should by handled by the function and raise IPython.ipapi.TryNext if it
+will not do the handling, giving the next function in the chain a chance to see
+whether it should handle the push.
 
-This would print an uppercase version of node body if the node headline ends
-with U (yes, this is completely useless!)
+This example would print an uppercase version of node body if the node headline ends
+with U (yes, this is completely useless!):
 
+{{{
 def push_upcase(node):
     if not node.h.endswith('U'):
         raise TryNext
     print node.b.upper()
 
-expose_ileo_push(push_upcase, 12)
+ipy_leo.expose_ileo_push(push_upcase, 12)
+}}}
 
 (the priority should be between 0-100 - typically, you don't need to care about
-it and can omit the argument altogether)
+it and can usually omit the argument altogether)
+</t>
+<t tx="vivainio.20080223142207">
+Example code snippets
+=====================
+
+Get list of all headlines of all the nodes in leo:
+
+    [node.h for node in wb]
+
+Create node with headline 'baz', empty body:
+    wb.baz
+
+Create 10 child nodes for baz, where i is headline and 'Hello ' + i is body:       
+
+    for i in range(10):
+        wb.baz[i] = 'Hello %d' % i
+
+
 </t>
+<t tx="vivainio.20080223142403"></t>
+<t tx="vivainio.20080223142403.1">12</t>
+<t tx="vivainio.20080223152600"></t>
+<t tx="vivainio.20080223174603"></t>
+<t tx="vivainio.20080223180139">'hello again'</t>
 </tnodes>
 </leo_file>