Prepare to release 0.5

CHANGELOG

@@ -1,3 +1,8 @@
+0.5   6 March 2011
+      Added GTK, wxWidget sample editors
+      Added Lexer and Parser classes
+      Improved the documenation
+
 0.4   30 December 2010
       Added data files
       Use -m in bin/arithmetic

Makefile

@@ -2,7 +2,7 @@
 # Publish to web page src directory
 #
 
-VERSION = 0.4
+VERSION = 0.5
 PW_PATH=~/pw/src/python/arithmetic
 RST2HTML = rst2html
 

index.rst

@@ -3,8 +3,9 @@ arithmetic
 
 *arithmetic* is a Python module that allows mixing arithmetic
 operations and text.
-A sample Tk-based editor that uses the module is provided as
-a starting point.
+Tk, GTK and wxWidgets based sample editors that use the module
+are provided as a starting point.  A plugin for Zim and a patch for PyRoom
+editors.
 Tutorial documents are included, they will quickly show
 all the features of arithmetic.
 It is licensed under the Gnu GPL license version 2 or later.
@@ -16,6 +17,8 @@ It is licensed under the Gnu GPL license version 2 or later.
 =================================   ===========
 Version                                 Date   
 =================================   ===========
+`0.5 <arithmetic-0.5.tar.gz>`_      06-Mar-2011
+---------------------------------   -----------
 `0.4 <arithmetic-0.4.tar.gz>`_      30-Dec-2010
 ---------------------------------   -----------
 `0.3 <arithmetic-0.3.tar.gz>`_      22-Aug-2010

manual.rst

@@ -20,7 +20,7 @@ arithmetic
 
 *arithmetic* is a Python module that allows mixing arithmetic
 operations and text.
-Sample Tk, GTK and wxWidgets based sample editors that use the module
+Tk, GTK and wxWidgets based sample editors that use the module
 are provided as a starting point.  A plugin for Zim and a patch for PyRoom
 editors.
 Tutorial documents are included, they will quickly show
@@ -50,41 +50,268 @@ Enter the folder arithmetic-<version> that was created::
  $ cd arithmetic-<version>
 
 
+Requirements
+~~~~~~~~~~~~
+
+The *arithmetic* module uses only modules from the standard
+Python library, no additional modules are required.
+
+The sample
+editors that are included require the Python bindings to the
+graphical toolkit they use.  The following table shows which
+package is required in each case:
+
+==============  ===============   ===========
+Editor          Package           Python
+                                  bindings
+==============  ===============   ===========
+editor-tk.py    python-tk         Tkinter
+--------------  ---------------   -----------
+editor-gtk.py   python-gtk2       gtk
+--------------  ---------------   -----------
+editor-wx.py    python-wxgtk2.8   wx
+==============  ===============   ===========
+
+Package **python-tk** might need to be installed in GNU/Linux, it is automatically
+installed with Python in Windows.
+Packages **python-wxgtk2.8** (or *python-wxgtk2.6*) and **python-gtk2** are
+normally installed in Ubuntu Linux.
+
+
 Tutorials
 ~~~~~~~~~
 
-Open the *tutorial-1* and *tutorial-2* files with editor-tk.py,
-the editor application included with the module.
-There is no need to install the module, editor-tk.py runs
-as is from the source directory.  In GNU/Linux, execute
-the following commands in the source directory::
+There is no need to install the module in your system, if you
+just want to try the module first.  The simplest demo is using
+a text file as input, the output is sent to the standard output::
+
+ ./arithmetic -f tutorial-1
+
+A graphical demo of using the module in a text editor is made
+using te sample editors. Open the *tutorial-1* and *tutorial-2* files
+with one of the editor applications, for example in GNU/Linux, execute
+the following commands in the source directory.  Using Tk::
 
  ./editor-tk.py tutorial-1
  ./editor-tk.py tutorial-2
 
+Using GTK::
 
-In Windows, explore the source directory and drag
-each tutorial file over the *editor-tk.py* icon.
+ ./editor-gtk.py tutorial-1
+ ./editor-gtk.py tutorial-2
 
 
-Requirements
-~~~~~~~~~~~~
+Using wxWidgets::
 
-Tkinter is required to run the editor-tk.py sample editor. you might need to install
-package python-tk in GNU/Linux. Tkinter is automatically installed in Windows.
+ ./editor-tk.py tutorial-1
+ ./editor-tk.py tutorial-2
 
+In Windows, explore the source directory and drag
+each tutorial file over one of the *editor-\*.py* icons.
 
 Installation
 ~~~~~~~~~~~~
 
-To install the module, execute as root from the source directory:: 
- 
+To install the module, execute as root from the source directory::
+
  # python setup.py install
 
+To install into your home directory (root user
+is not required)::
+
+ # python setup.py install --home=~
+
+Use in existing graphical applications
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Using arithmetic in an existing, Python-based GUI application
+involves adding a *calculate* function to the application
+and bind a key combination to call that function.
+These are the steps in more detail:
+
+1. Identify the text buffer used.  This is usually an instance
+of a text widget in the graphical toolkit and can be determined
+by looking at the source code.  The name of the text widget
+varies on each toolkit.  The table below shows the text
+buffer class name for each toolkit.
+
+2. Add a binding to the *calculate* routine.  This is done
+differently on each toolkit.  In some you can bind directly
+to F5 for example, other toolkits any key press is bound
+and you have to check for F5.
+
+3. Add a *calculate* routine that will receive an event or
+a reference to the text buffer.  This routine instanciates
+the Parser* class for the specific toolkit and calls the
+parse method that does all the work.  It scans the buffer
+line by line and writes back results if needed.
+
+4. Add an import statement at the begining of the
+source file where *calculate* is located, to import the
+appropriate class for the toolkit.
+
+================   ================ =======================
+Toolkit              Widget         Class in arithmetic
+================   ================ =======================
+Tk                 tkinter.Text     ParserTk
+----------------   ---------------- -----------------------
+GTK                gtk.TextBuffer   ParserGTK
+                   (displayed
+                   inside a
+                   gtk.TextView
+                   widget)
+----------------   ---------------- -----------------------
+wxWindows          wx.TextCtrl      ParserWx
+================   ================ =======================
+
+Tk-based applications
+---------------------
+
+Look at editor-tk.py for full detail.
+The key commmands that need to be added::
+
+ from arithmetic import ParserTk
+
+ TextWidget.bind( '<F5>', calculate )
+
+ def calculate( event ):
+     parser = ParserTk()
+     parser.parse( event.widget )
+
+GTK-based applications
+----------------------
+
+Look at editor-gtk.py for full detail.
+Commmands that need to be added::
+
+ from arithmetic import ParserGTK
+
+ def on_window1_key_press_event(self, widget, event, \*args ):
+     if event.keyval == gtk.keysyms.F5:
+         buf = self.textview.get_buffer()
+         self.calculate(buf)
+
+ def calculate( buf ):
+     parser = ParserGTK()
+     parser.parse( buf )
+
+wxWidgets-based applications
+----------------------------
+
+Look at editor-wx.py for full detail.
+Commmands that need to be added::
+
+ from arithmetic import ParserWx
+
+ self.control.Bind( wx.EVT_KEY_DOWN, calculate)
+
+ def calculate(event):
+     if event.GetKeyCode() == wx.WXK_F5:
+         control = event.GetEventObject()
+         parser = ParserWx()
+         parser.parse( control )
+     event.Skip()
+
+
+Adding the plugin to Zim
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you have Zim installed in your system, copy the **calc.py** file
+to */usr/local/lib/python2.6/dist-packages/zim/plugins*.  The 2.6 in
+this path might vary depending of the Python version::
+
+ su -c 'cp calc.py /usr/local/lib/python2.6/dist-packages/zim/plugins'
+
+If you just want to try Zim and arithmetic without installing any of
+them, download both sources to a folder, uncompress them, change into
+the zim-0.xx directory, copy the *calc.py* file into the zim/plugins
+path, and run this command::
+
+ PYTHONPATH=../arithmetic ./zim.py
+
+This will run Zim and tell the Python intepreter to find arithmetic in
+that path instead of the default path for installed packages.  In Zim
+use menu *Edit, Preferences*, then select the *Plugins* tab, look for
+for the Arithmetic entry and click on it.  Check in the dependencies that
+it says *arithmetic - OK*, then click on the checkbox in the *Enabled*
+column to enable it.  Click on OK to close the Preferences window.  Use
+menu *Tools* and verify that *Arithmetic  F5* is displayed.  You can now
+write arithmetic expressions ending in a '=', then press <F5> to
+obtain the results.
+
+Applying the patch to PyRoom
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you have PyRoom installed in your system, do the following commands
+in a shell::
+
+  cd /usr/local/lib/python2.6/dist-packages/PyRoom
+  su -c 'patch -p1 pyroom-0.4.1-arithmetic.patch'
+
+If you want to try PyRoom and arithmetic without installing them,
+download both sources into a folder. uncompress them, change into
+the pyroom folder and run the following command::
+
+ PYTHONPATH=../arithmetic ./pyroom
+
+This runs PyRoom telling the Python interpreter to find arithmetic
+in that path instead of the default path for installed packages.
+Once in PyRoom, you may use *Control-T* to obtain the results from
+calculations written in one of the buffers.
+
+How it works
+~~~~~~~~~~~~
+
+The input is a text buffer which might contain one or more
+interspersed arithmetic expressions.  This buffer is scanned
+line by line from top to bottom, and each line is scanned left
+to right.  For each equal sign that is found, the text to the
+left and to the right sides of the equals sign is parsed to
+determine if it is an expression, an identifier, or empty. Based
+on both sides, one of these actions is carried out:
+
+* Evaluate an expression on the left side, write the result
+  on the right side. For example:  *2 + 3 =*
+* Evaluate an expression on the right side, store the result
+  on the name on the left side.  For example:  width = 45
+* Store the formula for a function in the right side in the
+  formula name on the left side.  For example:  *area = width x height*.
+* Evaluate the value of a function on the left side, write the
+  result on the right side.  Like *area =*.
+
+Class *Parser* is the starting point. Its method *parse* accepts
+a string representing a single or multiple line buffer, and
+iterates through its lines. *parse* uses method *countLines* to
+know how many lines are in the text buffer, then repeateadly
+calls *readLine* to get a line and *parseLine* to scan it and
+modify it if needed. *parse* returns the input string, modified
+if any calculations where done.
+
+*parseLine* finds the equal signs and their left and right sides
+and determines what action to take.  Function *TypeAndValueOf*
+is used to know what is on each side (name, expression, etc.)
+*evaluate*, an expression parser, is used to get results of
+expressions, which may include variable or function names.  It
+uses *WriteResults* to modify a part of the line to write or
+update the result of an expression.
+
+*evaluate* uses class Lexer, a lexical analyzer, and accepts
+'x' for multiplication and n%, converting it to n/100.
+
+The *Parser* base class is used mostly for testing.
+Classes *ParserTk, ParserGTK* and *ParserWx* are derived from Parser
+and overwrite the *countLines, readLine* and *WriteResults*
+methods to include toolkit-specific commands.  These are the ones
+to be used for GUI applications.
+
+The names and values of variables found by parseLine are stored
+in the *variables* dictionary, the names and formulas of
+functions are stored in the *functions* dictionary.  These
+entries are read by evaluate when needed.  Both dictionaries
+are initialized when the Parser* instance is created.
 
 
 .. |date| date::
 .. |time| date:: %H:%M
 
 Document generated on |date| at |time| CST.
-

setup.py

@@ -7,7 +7,7 @@
 
 import sys,os,string,time
 
-version = '0.4'
+version = '0.5'
 
 kwargs = dict()
 if has_setuptools:
@@ -27,14 +27,17 @@
 	license = 'GNU GPL v2 or later',
 	py_modules = [ 'arithmetic' ],
 	data_files = [ ( 'share/arithmetic-' + version, [ 'COPYING',
-		'CHANGELOG', 'README', 'tutorial-1', 'tutorial-2' ] ) ],
-	scripts = [ 'libreta.py', 'arithmetic' ],
+		'CHANGELOG', 'README', 'tutorial-1', 'tutorial-2',
+                'pyroom-0.4.1-arithmetic.patch', 'calc.py' ] ) ],
+	scripts = [ 'editor-tk.py', 'arithmetic', 'editor-gtk.py',
+                    'editor.ui', 'editor-wx.py' ],
 	platforms = ['any'],
 	long_description='''arithmetic is a Python module that allows mixing arithmetic
 operations and text.  It resembles the calculator program bc.
 
-A sample Tk-based editor that uses the module is provided as
-a starting point.
+Tk, GTK and wxWidgets based sample editors that use the module
+are provided as a starting point.  A plugin for Zim and a patch for PyRoom
+editors.
 
 Tutorial documents are included, they will quickly show
 all the features of arithmetic.''',