From 920e8edc4476976c1c72e3411e51745975c61d24 Mon Sep 17 00:00:00 2001
From: Florent <weboob@flo.fourcot.fr>
Date: Mon, 16 Dec 2013 16:40:14 +0100
Subject: [PATCH] Add documentation on conditions

---
 tools/make_man.py                | 47 +++++++++++++++++++++++++++++++-
 weboob/tools/application/repl.py |  4 +--
 2 files changed, 48 insertions(+), 3 deletions(-)

diff --git a/tools/make_man.py b/tools/make_man.py
index a5ae1a60..16690a17 100755
--- a/tools/make_man.py
+++ b/tools/make_man.py
@@ -163,6 +163,51 @@ def analyze_application(app, script_name):
     header = '.TH %s 1 "%s" "%s %s"' % (script_name.upper(), time.strftime("%d %B %Y"),
                                         script_name, app.VERSION.replace('.', '\\&.'))
     name = ".SH NAME\n%s \- %s" % (script_name, application.SHORT_DESCRIPTION)
+    condition = """.SH CONDITION
+The -c and --condition is a flexible way to sort and get only interesting results. It supports condition on numerical values, dates, and strings. Dates are given in YYYY-MM-DD format.
+The syntax of one expression is "\\fBfield operator value\\fR". The field to test is always the left member of the expression.
+.LP
+The field is a member of the objects returned by the command. For example, a bank account has "balance", "coming" or "label" fields.
+.SS The following opperators are supported:
+.TP
+=
+Test if object.field is egal to value.
+.TP
+!=
+Test if object.field is different to value.
+.TP
+>
+Test if object.field is superior to value. If object.field is date, return true if value is before that object.field.
+.TP
+<
+Test if object.field is inferior value. If object.field is date, return true if value is after that object.field.
+.TP
+|
+This operator is available only for string fields. It works like the Unix standard \\fBgrep\\fR command, and return true if the pattern specified in value is in object.field.
+.SS Combination of expressions
+You can make a combination of expression with the keywords \\fB" AND "\\fR and \\fB" OR "\\fR.
+
+.SS Examples:
+.nf
+.B boobank ls \-\-condition 'label=Livret A'
+.fi
+Display only the "Livret A" account.
+.PP
+.nf
+.B boobank ls \-\-condition 'balance>10000'
+.fi
+Display accounts with a lot of money.
+.PP
+.nf
+.B boobank history account@backend \-\-condition 'label|rewe'
+.fi
+Get transactions containing "rewe".
+.PP
+.nf
+.B boobank history account@backend \-\-condition 'date>2013-12-01 AND date<2013-12-09'
+.fi
+Get transactions betweens the 2th December and 8th December 2013.
+"""
     footer = """.SH COPYRIGHT
 %s
 .LP
@@ -177,7 +222,7 @@ For full COPYRIGHT see COPYING file with weboob package.
     # Skip internal applications.
     footer += "\n\n.SH SEE ALSO\nHome page: http://weboob.org/applications/%s" % application.APPNAME
 
-    mantext = u"%s\n%s\n%s\n%s\n%s" % (coding, header, name, helptext, footer)
+    mantext = u"%s\n%s\n%s\n%s\n%s\n%s" % (coding, header, name, helptext, condition, footer)
     with open(os.path.join(BASE_PATH, DEST_DIR, "%s.1" % script_name), 'w+') as manfile:
         for line in mantext.split('\n'):
             manfile.write('%s\n' % line.lstrip().encode('utf-8'))
diff --git a/weboob/tools/application/repl.py b/weboob/tools/application/repl.py
index 36495d47..379682b2 100644
--- a/weboob/tools/application/repl.py
+++ b/weboob/tools/application/repl.py
@@ -150,7 +150,7 @@ class ReplApplication(Cmd, ConsoleApplication):
         self._parser.formatter = ReplOptionFormatter()
 
         results_options = OptionGroup(self._parser, 'Results Options')
-        results_options.add_option('-c', '--condition', help='filter result items to display given a boolean expression')
+        results_options.add_option('-c', '--condition', help='filter result items to display given a boolean expression. See CONDITION section for the syntax')
         results_options.add_option('-n', '--count', type='int',
                                    help='limit number of results (from each backends)')
         results_options.add_option('-s', '--select', help='select result item keys to display (comma separated)')
@@ -767,7 +767,7 @@ class ReplApplication(Cmd, ConsoleApplication):
         """
         condition [EXPRESSION | off]
 
-        If an argument is given, set the condition expression used to filter the results.
+        If an argument is given, set the condition expression used to filter the results. See CONDITION section for more details and the expression.
         If the "off" value is given, conditional filtering is disabled.
 
         If no argument is given, print the current condition expression.