1 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Strict//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns=
"http://www.w3.org/1999/xhtml"
4 lang=
"en" xml:
lang=
"en">
6 <title>The L3 language and interface
</title>
7 <meta http-equiv=
"Content-Type" content=
"text/html;charset=iso-8859-1"/>
8 <meta name=
"generator" content=
"Org-mode"/>
9 <meta name=
"generated" content=
"2008/04/07 12:15:27"/>
10 <meta name=
"author" content=
"Michael Hohn"/>
11 <link rel=stylesheet
href=
"l3style.css" type=
"text/css" media=
"screen">
12 <link rel=stylesheet
href=
"l3style-print.css" type=
"text/css" media=
"print">
14 <h1 class=
"title">The L3 language and interface
</h1>
19 <img src=
"l3logo.png" border=
"0" alt=
"L3 Logo"/>
20 <div id=
"table-of-contents">
21 <h2>Table of Contents
</h2>
23 <li><a href=
"#sec-1">1 Overview
</a></li>
24 <li><a href=
"#sec-2">2 Examples
</a>
26 <li><a href=
"#sec-3">2.1 Hello world
</a></li>
27 <li><a href=
"#sec-4">2.2 Statistics via RPy
</a></li>
28 <li><a href=
"#sec-5">2.3 Graphics and web data via matplotlib
</a></li>
29 <li><a href=
"#sec-6">2.4 Numerical convergence
</a></li>
32 <li><a href=
"#sec-7">3 Status: developer
</a></li>
33 <li><a href=
"#sec-8">4 Documentation
</a></li>
34 <li><a href=
"#sec-9">5 Installation
</a>
36 <li><a href=
"#sec-10">5.1 Using system libraries
</a></li>
37 <li><a href=
"#sec-15">5.2 Self-contained installation
</a></li>
40 <li><a href=
"#sec-16">6 Licenses
</a></li>
41 <li><a href=
"#sec-17">7 Developer download
</a></li>
42 <li><a href=
"#sec-18">8 Developer tools
</a>
44 <li><a href=
"#sec-19">8.1 Language manipulation tools
</a></li>
47 <li><a href=
"#sec-20">9 Author / Contact info
</a></li>
51 <a href=
"http://sourceforge.net"><img src=
"http://sflogo.sourceforge.net/sflogo.php?group_id=214585&type=2" width=
"125" height=
"37" border=
"0" alt=
"SourceForge.net Logo" /></a>
55 L3 is a Python-like language with convenient interaction features and a
59 <div class=
"outline-2">
60 <h2 id=
"sec-1">1 Overview
</h2>
62 <p>l3lang(
1) is a persistent, interpreted language designed to make
63 interacting with scripts
<i>and the data they produce
</i> convenient. It
64 does this by keeping track of
<i>all
</i> computed values (reducing file
65 clutter), providing nested namespaces and functions (avoiding name
66 clashes), and giving point-and-click access to the computed values
67 <i>through the script itself
</i> (avoiding the filesystem detour).
70 It is primarily used through l3gui(
1), a worksheet-style interface.
71 Long-running scripts can be executed without the interface, and the
72 results loaded later for interaction.
75 To avoid the need to learn yet another language, L3 is compatible with
76 a subset of
<a href=
"http://www.python.org">Python
</a> and can use any Python library, including
77 Python C/C++ extensions. In particular, the
<a href=
"http://www.macro-em.org/sparxwiki">sparx
</a> tools (image
78 processing) and
<a href=
"http://www.numpy.org">NumPy
</a> (numerical linear
79 algebra) are known to work. The
<a href=
"http://rpy.sourceforge.net/">RPy
</a> (statistical computing via
<a href=
"http://www.r-project.org/">R
</a>)
80 package also works, but extra care must be taken to make sessions
85 In l3gui, every part of a script is an object and its value(s) can be
86 examined via mouse menus, or reinserted into the gui for use in other
88 This mechanism includes nested loops and function definitions; all
89 values computed in a loop or function can be inspected later.
92 Scripts and code fragments can be assembled as structures,
93 providing graphical script construction for problems with few steps.
97 <div class=
"outline-2">
98 <h2 id=
"sec-2">2 Examples
</h2>
100 <p>The introduction is somewhat bland, so here are some examples to
101 illustrate why you may want to use L3. They are all included with the
104 <div class=
"outline-3">
105 <h3 id=
"sec-3">2.1 Hello world
</h3>
107 <p>The standard example, with twists. See
<a href=
"hello.html">hello, world!
</a>
110 <div class=
"outline-3">
111 <h3 id=
"sec-4">2.2 Statistics via RPy
</h3>
113 <p>This example is the
<a href=
"http://rpy.sourceforge.net/rpy_demo.html">the rpy demo
</a> with minor modifications to run in
114 L3. A nice example of worksheet convenience. See the
<a href=
"rpydemo.html">L3 rpy demo.
</a>
117 <div class=
"outline-3">
118 <h3 id=
"sec-5">2.3 Graphics and web data via matplotlib
</h3>
120 <p>Using the
<a href=
"http://matplotlib.sf.net">matplotlib
</a> library, this
<a href=
"demo-matplotlib.html">demo
</a> loads, graphs and
121 manipulates some financial data.
124 <div class=
"outline-3">
125 <h3 id=
"sec-6">2.4 Numerical convergence
</h3>
127 <p>Implement a simple iteration to compute
<code>sqrt(x)
</code>, and examine
128 intermediate results.
129 See the
<a href=
"sqrt.html">sqrt demo.
</a>
136 <div class=
"outline-2">
137 <h2 id=
"sec-7">3 Status: developer
</h2>
141 The l3 language is functional with some small command-line
142 interface adjustments still needed.
145 The l3 gui is also usable, but still contains menu entries and cruft
146 more useful for developers than users.
149 Documentation is very rudimentary and gaps will be filled over the
150 first few months of
2008.
154 <div class=
"outline-2">
155 <h2 id=
"sec-8">4 Documentation
</h2>
160 <a href=
"l3gui.html">l3gui
</a> <a href=
"l3gui.pdf">(pdf)
</a> — graphical environment for interacting with l3
164 The primary l3 interface. Explains the use of the
165 interface, and shows some simple examples.
169 <a href=
"l3.html">l3
</a> <a href=
"l3.pdf">(pdf)
</a>— interpret l3 programs
172 The command-line interface to L3. Used to start long-running
173 jobs in the background or to get an interactive toplevel.
174 Computed results are kept in both cases for later examination.
179 <a href=
"l3lang.html">l3lang
</a> <a href=
"l3lang.pdf">(pdf)
</a> — the l3 language.
182 The l3 language itself. This is documentation for l3
183 script writing and tailoring existing Python scripts for direct use
191 <div class=
"outline-2">
192 <h2 id=
"sec-9">5 Installation
</h2>
194 <p>The raw files are available from the sourceforge
<a href=
"http://sourceforge.net/projects/l3lang">project
</a> page, but
195 read the following before installing.
198 l3lang and l3gui are separate packages, with different prerequisites.
201 l3lang only requires Python (
2.4 or newer) and is therefore trivial
205 l3gui requires l3lang, Python, pygtk (
2.4 or newer), libgnomecanvas,
206 and the canvas part of the gnome-python binding.
207 In recent linux distributions, these are available via the package
208 handling system; follow the
<a href=
"#install-system-libs">system
</a> installation steps.
211 For older or customized systems, use the self-contained
<a href=
"#alternate-installation">alternate installation
</a> method.
214 <a name=
"install-system-libs"> </a>
216 <div class=
"outline-3">
217 <h3 id=
"sec-10">5.1 Using system libraries
</h3>
221 <div class=
"outline-4">
222 <h4 id=
"sec-11">5.1.1 Prerequisites
</h4>
224 <p>Newer releases of linux and FreeBSD make the prequisites available via
225 simple commands. First install these prerequisites, then install L3.
233 yum install gnome-python2-canvas
242 apt-get install python-gnomecanvas
250 <div class=
"outline-4">
251 <h4 id=
"sec-12">5.1.2 Download L3
</h4>
253 <p>To install l3 proper, download
<a href=
"http://downloads.sourceforge.net/l3lang/l3np/l3lang-0.3.1.tar.gz">l3lang-
0.3.1.tar.gz
</a> and
<a href=
"http://downloads.sourceforge.net/l3lang/l3gui-0.3.1.tar.gz">l3gui-
0.3.1.tar.gz
</a>, extract
254 them, and run setup.py. The download steps using the shell are:
257 wget http://downloads.sourceforge.net/l3lang/l3lang-
0.3.1.tar.gz
258 wget http://downloads.sourceforge.net/l3lang/l3gui-
0.3.1.tar.gz
259 tar zxf l3lang-
0.3.1.tar.gz
260 tar zxf l3gui-
0.3.1.tar.gz
266 <div class=
"outline-4">
267 <h4 id=
"sec-13">5.1.3 Install L3
</h4>
269 <p>Installation can be to system directories, a local directory, or l3
270 can be run from the distribution directory without installation.
271 Choose
<b>one
</b> of the following.
274 <li>System installation
<br/>
275 System installation is done via
278 python setup.py install --record INSTALLED-FILES
280 python setup.py install --record INSTALLED-FILES
282 but requires root access.
285 <li>Installation to prefix
<br/>
286 Installation to a local directory is supported; the minimal
287 shell setup for bash/ksh for using a local directory
288 <code>$HOME/linux-local
</code> with Python
2.4 is:
291 export MYPREFIX=$HOME/linux-local
292 export PATH=$MYPREFIX/bin:$PATH
293 export PYTHONPATH=$MYPREFIX/lib/python${PYVERSION}/site-packages:$PYTHONPATH
294 export MANPATH=$MYPREFIX/man:$MYPREFIX/share/man:$MANPATH
298 followed by installation via
301 python setup.py install --prefix=$MYPREFIX --record INSTALLED-FILES
303 python setup.py install --prefix=$MYPREFIX --record INSTALLED-FILES
307 <a name=
"use–without–installation"> </a>
309 <li>Use without installation
<br/>
310 The minimalistic adjustments are to ignore the installation step and only set
311 the PATH, PYTHONPATH, and MANPATH:
313 export PYTHONPATH=`pwd`/l3gui:`pwd`/l3lang:$PYTHONPATH
314 export PATH=`pwd`/l3gui/bin:`pwd`/l3lang/bin:$PATH
315 export MANPATH=`pwd`/l3gui/doc/man:`pwd`/l3lang/doc/man:$MANPATH
317 This requires removing the version number:
319 mv l3lang-
0.3.1 l3lang
321 chmod a+x l3lang/bin/* l3gui/bin/*
328 <div class=
"outline-4">
329 <h4 id=
"sec-14">5.1.4 Quick test
</h4>
331 <p>Once installed, a quick installation check can be done by reading the
332 documentation and running the toplevel:
344 <a name=
"alternate-installation"> </a>
348 <div class=
"outline-3">
349 <h3 id=
"sec-15">5.2 Self-contained installation
</h3>
351 <p>An installer based on
<a href=
"http://www.gnome.org/projects/garnome">GARNOME
</a> (itself based on the
<a href=
"http://lnx-bbc.com/">linux-bbc
</a> gar build
352 setup) is available. This provides a local environment for using /
353 incorporating other packages outside the system's package handler
354 (rpm/dpkg/pkg_add), which is particularly useful for
357 older linux/UNIX versions lacking the gtk/gnome canvas;
360 a self-contained installation to a local directory, including
361 environment-setting scripts and other niceties;
364 multiple independent development trees.
368 <p>This installer is used for the
<a href=
"http://www.macro-em.org/sparxwiki/">sparx
</a> project that l3 is part of and
369 contains rules for many more packages, but
370 installation of the L3 subset is simple.
373 Installation from source can be done as follows.
380 mkdir /your/installer/path
381 cd /your/installer/path
389 svn co svn://cci.lbl.gov/sparx-installer/trunk \
394 If you do not have subversion, and don't mind reinstalling everything
395 occasionally, you can instead use this:
399 wget http://cci.lbl.gov/~hohn/sparx-installer.tar.gz
400 tar zxvf sparx-installer.tar.gz
404 If you don't have wget, try curl instead:
408 curl http://cci.lbl.gov/~hohn/sparx-installer.tar.gz -o sparx-installer.tar.gz
415 ./configure /your/sparxroot
419 The last step (./configure) will print a summary. If there are any
420 errors, your system is missing the listed prerequisite(s).
423 The install is done via
430 When run successfully, this takes between
1.5 and
2.5 hours,
431 depending on the machine used.
439 <div class=
"outline-2">
440 <h2 id=
"sec-16">6 Licenses
</h2>
444 PLY
1.3.1 – LGPL
447 L3 uses version
1.3.1 of
<a href=
"http://www.dabeaz.com/ply/">PLY
</a>, a yacc-like parser generator for Python.
448 Ply is included in the L3 source tree for convenience, but is released
449 under the GNU Lesser General Public License as published by the Free
450 Software Foundation; either version
2.1 of the License, or (at your
451 option) any later version.
458 L3 itself is released under the following license.
461 Copyright (c)
2006, The Regents of the University of California,
462 through Lawrence Berkeley National Laboratory. All rights
466 Redistribution and use in source and binary forms, with or without
467 modification, are permitted provided that the following conditions are
471 (
1) Redistributions of source code must retain the above copyright
472 notice, this list of conditions and the following disclaimer.
475 (
2) Redistributions in binary form must reproduce the above copyright
476 notice, this list of conditions and the following disclaimer in
477 the documentation and/or other materials provided with the
481 (
3) Neither the name of the University of California, Lawrence
482 Berkeley National Laboratory, U.S. Dept. of Energy nor the names
483 of its contributors may be used to endorse or promote products
484 derived from this software without specific prior written
488 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
489 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
490 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
491 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
492 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
493 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
494 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
495 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
496 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
497 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
498 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
501 You are under no obligation whatsoever to provide any bug fixes,
502 patches, or upgrades to the features, functionality or performance of
503 the source code (
"Enhancements") to anyone; however, if you choose to
504 make your Enhancements available either publicly, or directly to
505 Lawrence Berkeley National Laboratory, without imposing a separate
506 written license agreement for such Enhancements, then you hereby grant
507 the following license: a non-exclusive, royalty-free perpetual license
508 to install, use, modify, prepare derivative works, incorporate into
509 other computer software, distribute, and sublicense such enhancements
510 or derivative works thereof, in binary and source code form.
518 <div class=
"outline-2">
519 <h2 id=
"sec-17">7 Developer download
</h2>
521 <p>Development is done using
<a href=
"http://git.or.cz/">git
</a> so anyone can have their own local
522 development branches. The web interface is at
<a href=
"http://repo.or.cz/w/l3full.git">repo.or.cz
</a>, and you can
523 get the whole repository including l3doc, -lang, and -gui via
525 git-clone git://repo.or.cz/l3full.git l3full
529 The working directories can be directly used with appropriate
530 settings, via minimalistic adjustments:
533 export PYTHONPATH=`pwd`:$PYTHONPATH
534 export PATH=`pwd`/l3gui/bin:`pwd`/l3lang/bin:$PATH
535 export MANPATH=`pwd`/l3gui/doc/man:`pwd`/l3lang/doc/man:$MANPATH
543 <div class=
"outline-2">
544 <h2 id=
"sec-18">8 Developer tools
</h2>
546 <p>Several parts of
<code>l3lang
</code> can be used as libraries for other
550 <div class=
"outline-3">
551 <h3 id=
"sec-19">8.1 Language manipulation tools
</h3>
553 <p>L3 parser / pattern matcher / pretty printer
556 The
<code>l3lang.reader
</code> module implements the l3 parser, currently using
557 the Python
<code>tokenize
</code> module and a
<a href=
"http://www.dabeaz.com/ply">PLY
</a> grammar to parse input text and
562 The
<code>l3lang.pretty
</code> module is a box-based pretty-printer providing
563 horizontal (H) vertical (V), and horizontal-or-vertical (HOV) boxes.
564 It is a transliteration from the
<a href=
"http://citeseer.ist.psu.edu/301975.html">ocaml version
</a> of Wadler's pretty
568 <code>l3lang.ast
</code> provides AST manipulation tools, including a simple
572 <code>l3lang.view
</code> provides tools for printing the AST. Two functions of
573 general interest are
<code>get_infix_string()
</code> which returns a
574 pretty-printed representation of an AST,
575 and
<code>print_info()
</code> which produces a prefix dump of the AST.
579 As example, the full read / print cycle starts from
583 tree = reader.parse('''
596 print tree.get_infix_string(
40)
604 print_(a);loop((a +
1))
609 print tree.get_infix_string(
10)
611 tries to squeeze more:
630 <div class=
"outline-2">
631 <h2 id=
"sec-20">9 Author / Contact info
</h2>
640 <div id=
"postamble"><p class=
"author"> Author: Michael Hohn
641 <a href=
"mailto:mhhohn at users dot sourceforge.net"><mhhohn at users dot sourceforge.net
></a>
643 <p class=
"date"> Date:
2008/
04/
07 12:
15:
27</p>