313 lines
15 KiB
Text
313 lines
15 KiB
Text
Specification of configuration files for fillform.py
|
||
----------------------------------------------------
|
||
|
||
The configuration file syntax is inspired by the output of pdftk dump_data_fields.
|
||
This output actually complies with the syntax. This is done to be able to
|
||
parse this output and syntax files in a single way.
|
||
|
||
Parsing
|
||
-------
|
||
The file is read line by line. Line breaks with a logical line are not supported.
|
||
Empty lines are ignored.
|
||
Lines starting with the comment symbol # (see constants.COMMENT_SYMBOL) are ignored.
|
||
|
||
Overall structure
|
||
-----------------
|
||
The file is a list of fields. One for each field in the corresponding pdf.
|
||
The fields are seperated by lines consisting of three hyphens (---).
|
||
The first line can be ---.
|
||
The last line cannot be ---.
|
||
|
||
Each line consists of one "info". That is a key-value-pair, separated by ": ". The value can be empty. (The key probably as well, but not tested.)
|
||
|
||
Conventions: (not enforced)
|
||
------------
|
||
Keys that come from 'pdftk dump_data_fields' start with 'Field'. The rest do not.
|
||
Keys that are not specifier (see below) start with a upper-case-letter. Specifier are lower-case.
|
||
|
||
Some keys can appear more than once. Those are (see constants.MobileRegex):
|
||
FieldStateOption
|
||
Command (read as regular expression) (Commands, see below)
|
||
[^-]-If[^-] (read as regular expression) (Conditions, see below)
|
||
Data
|
||
The order of the infos do not matter and can change by reading and writing.
|
||
|
||
Nonfields
|
||
---------
|
||
For several cases it is necessary to create fields that do not correspond to
|
||
any form field in the pdf. Those are marked by the info "Nonfield"
|
||
(see constants.NON_FORMFIELD) that must appear to tell the program that
|
||
this field is not to be written to a pdf. The value of this info is irrelevant.
|
||
|
||
One use case are fields that have questions that can be used several
|
||
times and are therefore outside any specific form field. Other use case are listed below:
|
||
|
||
Mainconfig
|
||
----------
|
||
It is identified by the FieldName "Mainconfig" (see constants.CONFIGFIELD) and the
|
||
info "Nonfield" (see constants.NON_FORMFIELD).
|
||
In this 'field' some configuration that does not belong to any form field is placed.
|
||
So far this is only data file paths.
|
||
In variables (see below) one can reference to other form files to get data. In
|
||
the variables one only uses a "specifier". In the mainconfig it is saved which file
|
||
this corresponds to in the following way:
|
||
|
||
Data: f
|
||
f-Path: otherFile.form
|
||
|
||
or
|
||
|
||
Data: f
|
||
f-Path: directory
|
||
|
||
where f is the specifier used in variables.
|
||
These specifier - file mapping can be overwritten by the command-line argument --data.
|
||
In both cases (file or directory) it is taken to be relative to the form file itself.
|
||
When a directory is specified, the programm searches in this directory and
|
||
all subdirectories for a form file that fits to the specifier. (see section "Specifier"
|
||
below.)
|
||
|
||
Specifier
|
||
---------
|
||
As noted in "Mainconfig" data files can be searched for and are found if
|
||
they say "I am a suitable file for this data." This is done via a field with the
|
||
FieldName Specifier (see constants.SPECIFIERFIELD) which value must be
|
||
the same as the specifier written in the config file that corresponds to the
|
||
pdf worked on.
|
||
Since the empty (not yet used) form files should not be found,
|
||
this value should not be set there but be filled via an action (usually Default).
|
||
Hence a typical field that fits to the mainconfig used as an example above looks like
|
||
|
||
FieldName: Specifier
|
||
Nonfield: True
|
||
Default: d
|
||
d-Value: f
|
||
|
||
Since FieldName should be unique one only should have one specifier but
|
||
that should not be a restriction.
|
||
|
||
Output file names
|
||
-----------------
|
||
The name of the output files can be configured with the 'fields' with the FieldName
|
||
Outputconfig (see constants.OUTPUTFIELD) and Formoutputconfig (see constants.FORMOUTPUTFIELD).
|
||
When the pdf and form file are created, the names of the new files are taken from the
|
||
'Value' info of the respective field. This is overridden by output filenames specified
|
||
on the command line. If no such fields exists or it has no Value info, a standard name
|
||
based on the input file is used.
|
||
The Value info can (and usually should) be created with a Command, usually a Default
|
||
that can use information of other fields. Note that in this case the generated name
|
||
is only used if the Command is already done.
|
||
|
||
Stamps = Fields outside of the form
|
||
-----------------------------------
|
||
Sometimes one needs to fill in something at positions where the pdf creator
|
||
did not place any form fields, e.g. a printed name under the signature might be useful
|
||
but usually not intended. For those cases one can add arbitrary text at arbitrary
|
||
positions. For each of those texts add one field with the following information:
|
||
|
||
FieldName: does not really matter, should not appear somewhere else
|
||
Name: for easy recognition
|
||
Nonfield: (here anything including "" can be written), (see constants.NON_FORMFIELD)
|
||
Stamp: (here anything including "" can be written)
|
||
Page: integer: the page on which this text should be put
|
||
PosX: positive integer: the X-position of the text, larger number = more right (0 = left edge)
|
||
PosY: negative integer: the Y-position of the text, large negative = more down (0 = top edge)
|
||
|
||
In order to enter text, use one of the Commands (see below) as one does with any FormField.
|
||
As usual, the info Value includes the text printed. Please note, that this text is interpreted
|
||
as LaTeX code. In particular &, {, }, $ and many more symbols need to be escaped with '\'.
|
||
Umlauts are fine.
|
||
(I call those texts stamps because the program pdftk uses the command stamp to
|
||
put pdfs on top of each other. That's what happening here behind the scenes.)
|
||
|
||
Infos from pdftk
|
||
----------------
|
||
Infos from pdftk dump_data_fields include:
|
||
FieldType: always existent, Possiblities: Text or Button
|
||
FieldName: always existent, sometimes this includes a descriptive name, sometimes not useful
|
||
used for identifying the field in variables (see below)
|
||
FieldNameAlt: usually existing: usually similarly useless as FieldName, sometimes for helpful for identification
|
||
FieldFlags: a number. No idea what it means.
|
||
FieldJustification
|
||
FieldMaxLength: sometimes exitent, not used yet (it's a TODO!)
|
||
FieldStateOption: always (?) existent if FieldType is Button. Specifies what a valid values. Appears several times.
|
||
For single buttons usually On and Off.
|
||
For several buttons from which one is to be chosen usually 1, 2, 3, ..., Off
|
||
FieldValue: the value saved in the pdf
|
||
|
||
Infos from fillform
|
||
-------------------
|
||
Name: a short name that should easily tell which field it is. Is used when the user is asked for input.
|
||
Description: a longer text that describes what should be written in this field. Can include a lot of information. Is used as help when the user is asked for input.
|
||
Value: the value that is saved in the pdf. This info is not filled while writing the config file but by the program. It is used when the output of the program is used as data input while filling out other documents. For default values us the Command Default, not this info!
|
||
Question, Choice, Default: Commands, see below.
|
||
|
||
Commands
|
||
--------
|
||
Each field can define commands that are executed during the program. Usually each field has one command that in some way fills the field with a value that is at the end written in the pdf. But it is also possible to define several commands for one field, even several of the same kind.
|
||
The commands are Question, Choice and Default.
|
||
To create a command add the info
|
||
Commandname: specifier
|
||
E.g.:
|
||
|
||
Question: q
|
||
|
||
All infos that this command needs are specified with keys of the form
|
||
specifier-Subkey
|
||
E.g.:
|
||
|
||
q-Prompt: Gib deinen Reisebeginn an.
|
||
|
||
Convention:
|
||
-----------
|
||
As mentioned above, keys are Uppercased, including the subkeys. Specifier are lower-case.
|
||
|
||
Commands can have conditions for execution.
|
||
|
||
Condition - Ifexist
|
||
-------------------
|
||
If there is already a value saved in the field, the commands are not executed.
|
||
This is usually helpful when a pdf is partially filled and the user decides to finish it later. Then the config file with some input saved in the info Value can be used to continue.
|
||
If the command should be executed even if there is already a value, use the (sub)info Ifexist with any value, e.g. for the command with the specifier s:
|
||
s-Ifexist: blub
|
||
or with empty value:
|
||
s-Ifexist:
|
||
(! Pay attention to the whitespace after the : which is part of the seperator.)
|
||
|
||
Condition - Ifequal and Ifunequal
|
||
---------------------------------
|
||
Some fields must only be filled with user input if other fields have some specific value, usually a marked or not marked button. The conditions Ifequal and Ifunequal fulfill this possibility. Similarly to commands you specify a specifier and subkeys for this specifiers with two infos A and B.
|
||
E.g. for the command with the specifier s and the condition with the specifier c:
|
||
|
||
s-Ifequal: c
|
||
s-c-A: Blub
|
||
s-c-B: Blub
|
||
Of course having two simple strings for comparisons does not help. But those values can include "Variables" (see below) that are interpreted. To check if the checkbox "Tagegeld" is marked, one may write:
|
||
s-Ifequal: c
|
||
s-c-A: On
|
||
s-c-B: {Tagegeld}
|
||
|
||
Ifunequal works similarly.
|
||
|
||
Commands: Question
|
||
------------------
|
||
The command "Question" asks the user to write something that is saved in the info Value.
|
||
To inform the user what is asked, the subkey Prompt can be specified. If it is not used the name of the field is used (name = if exists: Name, otherwise if exists: FieldName, otherwise if exists: FieldNameAlt).
|
||
If the user types '?' a help is displayed. This help can be specified by the subkey Help. If this is not used, the info Description is used. (If no description is available "No help available." is displayed.)
|
||
E.g.:
|
||
Question: q
|
||
q-Prompt: destination
|
||
q-Help: Where did you go to (enter a city name)?
|
||
|
||
If the user enters nothing, an empty string is saved.
|
||
In order to save nothing, the user has to press Ctrl+D (means End of file on the command line.)
|
||
This is different to Enter (aka empty input) in that the user will get asked again if s:he continues
|
||
the form at another time and uses the partially filled form file if there is no value saved. If there
|
||
is the value empty string saved, the program already got an input and will not ask again.
|
||
|
||
Commands: Choice
|
||
----------------
|
||
In pdfs exist buttons that can be marked (a cross appears in graphical pdf-viewers) or not marked.
|
||
Additionally there are buttons from which one of several needs to be chosen. They can be identified with the info
|
||
|
||
FieldType: Button
|
||
|
||
and the info
|
||
|
||
FieldStateOption: ...
|
||
|
||
which appears several times with all possibilities. Usually those are On (or Ja) and Off or 1, 2, 3, ..., Off.
|
||
For those it only makes sense to use one of those options. Hence a different type of input than Question is possible and necessary.
|
||
As with Question (see above Commands: Question) you can specify the (sub)infos Prompt and Help. The help is displayed in case of the input '?'.
|
||
Additionally for every option specified by FieldStateOption, a short explanation/ name should be supplied via the subkey Option-op (for the option op ∈ {On, Off, Ja, Nein} ∪ ℕ). E.g. for the command Choice with the specifier c:
|
||
|
||
FieldStateOption: 1
|
||
FieldStateOption: 2
|
||
FieldStateOption: 3
|
||
FieldStateOption: 4
|
||
c-Option-1: Beamter:in
|
||
c-Option-2: Angestellte:r
|
||
c-Option-3: andere:r
|
||
c-Option-Off: keine:r davon
|
||
|
||
If the user inputs nothing (a.k.a. only presses Enter) a default value can be used. This is specified by the subkey Enter. E.g. for usually using "Beamter:in" this could be useful:
|
||
|
||
c-Enter: 1
|
||
|
||
(The value of the info -Enter can include variables.)
|
||
If no Enter is specified, the help is displayed in case of an empty input.
|
||
In order to input nothing the user presses Ctrl+D, explanation see above at Commands: Question.
|
||
|
||
After the prompt the user sees all options with a numbering. The default is at the beginning, followed by Yes-type options, followed by numbered options, followed by No-type options and followed by the remaining ones sorted alphabetically.
|
||
The user input is understood in the following way:
|
||
Ctrl+D: save nothing.
|
||
Empty: save default
|
||
Natural number: option with this number in the above mentioned numbering.
|
||
Otherwise, use the first option which name/ explanation begins with the user input (case-insensitive).
|
||
If none is found, ask again.
|
||
E.g. for the example above, the options are
|
||
1) 1 = Beamter:in
|
||
2) 2 = Angestellte:r
|
||
3) 3 = andere:r
|
||
4) 4 (No help avaiable)
|
||
5) Off = kein:r davon
|
||
|
||
the following input gives the following value:
|
||
1 -> 1
|
||
2 -> 2
|
||
? -> show Help, ask again
|
||
O -> ask again
|
||
B -> 1
|
||
ang -> 2
|
||
and -> 3
|
||
an -> ask again (since 2, 3 are possible)
|
||
k -> Off
|
||
-> 1 (no input, just Enter pressed)
|
||
4 -> 4
|
||
6 -> ask again
|
||
|
||
Commands: Default
|
||
-----------------
|
||
When filling out pdf forms by hand one usually starts with the pdf form from last time and only change everything that is different this time. This means that default value are helpful.
|
||
Another use case for default values is text that is used at several positions of the form. This is a kind of default as well ('use what is printed there'). This is especially true for values in other forms that were filled out at another time but use information usable here again.
|
||
|
||
For using a default value use the command Default.
|
||
It has the subkey, namely Value. The info in the subinfo Value is saved in the info Value of the field after replacing variables (see Variable interpretation).
|
||
After interpreting variables one can add (or subtract) a time by using the subkey Addhours and Addmin. This only works if the value is of the form hh:mm (where hh and mm must be integers of any length and sign). No validity check is done. (For example the hours can exceed 24, ...)
|
||
If Addhours or Addmin is specified and the value is not of this form, a warning is printed and the value is saved as is.
|
||
E.g.:
|
||
|
||
Default: d
|
||
d-Value: {otherForm|deptime}
|
||
d-Addhours: -2
|
||
|
||
This saves a time two hours before the departure time that is saved in the field deptime of the form known as otherForm.
|
||
|
||
If the result of the variable replacement results in an overall empty string, nothing is saved.
|
||
|
||
Variable interpretation
|
||
-----------------------
|
||
To allow referencing to other fields Default and the conditions If(un)equal allow variables in the values. Variables can have one of four forms:
|
||
1) for fields in the same form:
|
||
{fieldname} or {fieldname#default}
|
||
where fieldname is the info saved in FieldName.
|
||
FieldName is used since it should exist for every field and should be unique in a well-formed pdf.
|
||
{fieldname} is replaced by what is saved in the info Value.
|
||
If the field has no value saved, use default if given. If no # exists (aka no default is given) and no value is saved, an error is raised.
|
||
2) {form|fieldname} or {form|fieldname#default)
|
||
where form is a specifier for an other form which form-file got read as well and fieldname is a FieldName in this other form. The same as above for default applies.
|
||
When calling fillform on the commandline one can specify with the option
|
||
--data spec otherForm.form
|
||
a form-file that was produced while filling out another form (otherForm.form) and the specifier (spec) is the specifier used in variables (example above: form).
|
||
The other way to define the specifier is the field mainconfig (see there).
|
||
|
||
Variables are repeatedly replaced until there is no {, } pair is found.
|
||
{, |, }, # as special symbols are defined in constants.VARIABLE...
|
||
|
||
Additionally you can insert todays date with the syntax
|
||
[formatstr]
|
||
|
||
Here the allowed formatstr are described in
|
||
https://docs.python.org/3.5/library/datetime.html#strftime-strptime-behavior
|
||
|
||
[, ] as special symbols are defined in constants.DATE_...
|