Configuration file format for prompts.py version 0.80beta, 2013-07-08
configuration_file.
Config file:
last argument.
Can be full path, can begin ~; relative path works if in terminal (relative to cwd)
Comments begin with "#"
Key names are case-insensitive.
You should test a newly-created or modified configuration file by running it with prompts.py in test mode, e.g.
[<path_to>/]prompts.py --no-save --verbose <path_to>/config_file
After you've run it for real (without --no-save), you can test again, simulating a run at a later date with e.g.
[<path_to>/]prompts.py --date=$(date --date='30 day' +"%Y%m%d") --verbose <path_to>/config_file
Keys in this section apply to all prompts defined in other sections of the configuration file.
The title for each prompt message box.
Defaults to "Reminder"
Text put in front of each question presented in a message box (ie. in from of the contents of the Ask key in each prompt section).
Defaults to "Time to "
Last date prompt.py run. Updated by script; normally you will never edit it.
Format must be yyyymmdd.
If today's date, prompt.py will quit and not run. (Lock determining that prompt only runs once a day).
Prefix put before Action key contents for any prompt with key Terminal to something true-ish (1, yes, y...)
Defaults to gnome-terminal --execute
Prefix put before Doc key contents for any prompt
Defaults to "xdg-open" for linux systems, start "" /B for Winodws and "open " for mac.
To show message boxes, prompt.py attempts to import one of the following packages, in the following order:
under linux: gtk, easygui, easydialogs, dialog under win: gtk, easygui, ctypes, easydialogs
You can override the evaluation order by setting the Framework key to one of the above, or to "terminal" if you want questions delivered and responses taken on the command line.
If either the 'terminal' or 'dialog' framework is specified, it will have the effect of specifying the --successive command line option; the assumption is that you've launched prompts within a terminal window, and will only be able to process one prompt at a time.
UserStateNow may be one of the (comma separated) values in this key
Defaults to "home, work, holiday"
An item from UserStates. If set, each prompt section is checked (case-insensitively) for a key with that name (e.g. "Home = yes"). If present that keys value is expected to be something boolean-ish (1, yes, y, 0, no). If the key is present and its value false-ish, the prompt item is not run.
You can set UserStateNow via the -u or --user-state command line options.
Each prompt section may include a Trigger condition. By default if there's both a Trigger condition and a DaysBetweenRuns key, the prompt will be skipped if the Trigger evaluates to something false-ish, or if DaysBetweenRuns hasn't yet expired.
Also by default, there can be an alternative key, TriggerAnd in any prompt section (there can't be both a TriggerAnd and a Trigger key in the same section).
If you set Trigger in the [prompts] section to something containing "and", both the Trigger condition must be false and DaysBetweenRuns must not have expired for the prompt not to fire, and instead of TriggerAnd there may be an alternative TriggerOr key.
If a dialog pops up while youre in the middle of typing, you can inadvertently choose a dialog option. Anyway popup dialogs are annoying when youre in the middle of Something Important. Set SecsIdleWait to a number, and popups won't come up until theres no mouse or keyboard activity for that number of seconds.
You can have any number of groups, each distinguished by its own case-insensitive key in this section. There is a maximum number of prompts that can be started on any given day n any one group. That maximum number if the group keys value, e.g.
maint=3 links = 2
You can have any number of variables, each distinguished by its own case-sensitive key in this section. Variable names (therefore keys) follow linux variable naming rules, so may be made up of alphanumerics and underscores, but may not begin with an integer. You may not use any environmental variable name (which are normally all-caps, so you might want to avoid all-caps keys to be on the safe side).
If a key is followed by "==" instead of "=", the text after the "==" is interpreted as an expression which is passed to the shell for evaluation; whatever ends up in stdout becomes the variable value.
If on any line any key from the [variables] section occurs preceded by $, $<keyname> is repaced by the value of the <keyname> key. If a $ is followed by anything else, it is ignored and left as-is in the line.
================================================
All other sections define prompts and when they should be made. Each must begin with a unique section name in square brackets, e.g.
[MySection]
Your prompt sections can't be called [prompts], [groups] or [variables].
The only required key. It's the text which will be presented in a message box (preceeded by the value of QuestionPrefix, see above).
Programme to run, with any required arguments. Provide the full path to the programme, unless its on your PATH. Alternatively you can provide the Doc key (below). You must provide either one or the other, but not both, in a section describing a prompt.
If present the Terminal keys value is expected to be something boolean-ish (1, yes, y, 0, no). If the key is present and its value true-ish, the Action key is prefixed with the value of the Terminal key in the [prompts] section. If Terminal is true-ish and there is no Terminal key in the [prompts] section, its an error.
Full path to a non-executable file. The value of the key OpenDocWith in the [prompts] section (or the default document runner for your platform, if OpenDocWith absent) will be prefixed to the specified path to a non-executable file.
Prompt won't appear until this number of seconds passed.
Number of days between runs. LastDateRun is date of last run. If LastDateRun or DaysBetweenRuns not present, programme will run every day. If DaysBetweenRuns present but LastDateRun is not, LastDateRun will be set to today's date.
Days of week on which NOT to run. One letter for each day of week, starting with Monday. Excluded days marked with "X", other positions may be anything, though I use MTWTFS.
Example entry:
MTWTFXX (i.e. not on weekends)
Last date on which Action was performed or Doc opened. Must be in yyyymmdd format. Updated by script; normally you will never edit it.
If present the Trigger keys value is expected to be something that can be executed and which would produce something boolean-ish (1, yes, y, 0, no, n) on stdout. Any expression that returns something suitably bookean on the command line should aslo work as the value of a Trigger key.
If the key is present and its value produce something false-ish (0, no, n) on stdout, the prompt will not be made.
In Windows about the only thing thats likely to work would be a path to a suitably tailored script file. The batch command language not being rich enough, vbscript, jscript or powershell scripts might do.
On *nix, these sorts of things would work:
programme may belong to exactly one group, defined by a key in the [groups] section. If a prompt section has a Group key, the value of that key must itself be a key in the [groups] section. The key [groups] section must be of the form "group=n", where n is the maximum number of prompts in that group allowed to run on one day.
Last date on which a message box was displayed for the prompt, in yyyymmdd format.
If present and LastReminder present, number of days between reminders. So if LastReminder date added to the value of DaysBetweenReminders is greated than today's date, a prompt isnt shown, even if its due according to all other criteria.
Prompt won't happen if after this hour in the day (24 hour clock).