From: W. Trevor King <wking@drexel.edu>
Date: Thu, 17 Dec 2009 21:09:51 +0000 (-0500)
Subject: Added Alberto's mailing list comments about lib*.py to their docstrings.
X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=545013bfc6d3d67cb31c9d8501ba5f8a83d642f4;p=hooke.git

Added Alberto's mailing list comments about lib*.py to their docstrings.

From the thread:
  http://groups.google.com/group/hookesoftware/browse_thread/thread/7b893284cc317ea6#
---

diff --git a/hooke/libinput.py b/hooke/libinput.py
index 5ac69ac..21ca05f 100644
--- a/hooke/libinput.py
+++ b/hooke/libinput.py
@@ -4,6 +4,28 @@ Input check routines.
 Copyright (C) 2008 Alberto Gomez-Casado (University of Twente).
 
 This program is released under the GNU General Public License version 2.
+
+This is just a collection of wrappers for raw_input(), I noticed using
+hooke that unexpected answers from the user often triggered a nasty
+crash, so what they do is provide some basic check of inputs to avoid
+'voids', letters where numbers are expected, etc
+
+The basic call there is safeinput(message,[list])
+Message is a string that is shown to the user ('Enter filename:')
+[list] can be present or not.
+  - If not present safeinput is just a raw_input shielded against void
+inputs (it will keep asking until it gets some answer)
+  - If a list of only one element is provided, it is interpreted as a
+default value (in case a void input that value will be returned)
+  - If a list of two or more 'string' elements is provided, user input
+must match one of them to be valid
+  - If a list of two integer elements [a, b] is provided, user input
+is required to be in the interval [a,b]
+
+More info about the underlying calls can be found in the code. However
+I am still not very satisfied with them, That's why I made safeinput()
+to wrap all so I can improve them without further fiddling with other
+module's code.
 '''
 
 from types import *
diff --git a/hooke/liboutlet.py b/hooke/liboutlet.py
index 58edf32..aec7a4c 100644
--- a/hooke/liboutlet.py
+++ b/hooke/liboutlet.py
@@ -4,6 +4,35 @@ Basic outlet object
 Copyright (C) 2008 Alberto Gomez-Casado (University of Twente).
 
 This program is released under the GNU General Public License version 2.
+
+I though of this as just a centralized collector of command output.
+Other option would have been making each command save results, but I
+think that would have led to a lot of code duplication and probably
+huge user hassle (do you want to save this?  and this?  and this
+one?). So there's this object 'outlet' and the only thing each command
+has to know about it is the method outlet.push(line) and the format of
+that line, that so far is
+
+type  filename  [list]
+
+   - type identifies which command produced that line
+   - filename is the curve from which the command produced the output
+(this allows to know for example if a curve had more than one peak,
+but user is left responsible of their ordering!). It's also useful to
+keep track of where were you last time (if you follow natural order
+when looking at curves).
+   - list can have pretty much anything, depending on the particular
+command
+
+From the point of view of the commands there is nothing else about
+outlet. Apart from that I made a couple of commands to delete lines in
+case you had a twitch when click and don what that measurement to be
+saved and to have a look at current contents of outlet.
+
+Finally I put in outlet an attribute, relations, that could be used in
+the future by the viewers to register themselves  so outlet can
+trigger their actions when new data arrives (allowing automatic
+refreshes). But so far that's probably overdesigning.
 '''
 
 import re
diff --git a/hooke/libviewer.py b/hooke/libviewer.py
index ee3adb2..5397a6e 100644
--- a/hooke/libviewer.py
+++ b/hooke/libviewer.py
@@ -4,6 +4,19 @@ Basic Viewer and ascii saver example
 Copyright (C) 2008 Alberto Gomez-Casado (University of Twente).
 
 This program is released under the GNU General Public License version 2.
+
+So far outlet is useless.  That's where viewers (well, only one now)
+do the job. They query outlet for data of some type, process it and
+give some elaborated output. Again the only thing they have to know
+about outlet is how to call it and the 'line' format.
+
+I put in the viewer plugin a list to keep them so it is possible to
+create many. The basic operations in viewer.py
+   - vwnew: adds a new viewer to the list, and sets it so it defines
+what type of data it will be interested in
+   - vwaction: tells the viewer to 'do stuff', that is, retrieve data
+and process it. Just a wrapper call for the specific one of each
+viewer. 
 '''
 
 import liboutlet as lout