Skip to content
Browse files

Prepare to release 0.5

  • Loading branch information...
1 parent 4744fed commit 02aceb51fa2bd5d3a5c310588d9636b9ee2a937e @ppaez committed Mar 6, 2011
Showing with 261 additions and 23 deletions.
  1. +5 −0 CHANGELOG
  2. +1 −1 Makefile
  3. +5 −2 index.rst
  4. +242 −15 manual.rst
  5. +8 −5 setup.py
View
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
View
2 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
View
7 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
View
257 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.
-
View
13 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.''',

0 comments on commit 02aceb5

Please sign in to comment.
Something went wrong with that request. Please try again.