Module docsettings
This module is responsible for reading and writing metadata.lua files
in the so-called sidecar directory
(Wikipedia definition).
Functions
| DocSettings:getSidecarDir (doc_path) | Returns path to sidecar directory (filename.sdr). |
| DocSettings:getSidecarFile (doc_path) | Returns path to metadata.lua file. |
| DocSettings:hasSidecarFile (doc_path) | Returns true if there is a metadata.lua file. |
| DocSettings:open (docfile) | Opens a document's individual settings (font, margin, dictionary, etc.) |
| DocSettings:readSetting (key, default) | Reads a setting, optionally initializing it to a default. |
| DocSettings:saveSetting (key, value) | Saves a setting. |
| DocSettings:delSetting (key) | Deletes a setting. |
| DocSettings:has (key) | Checks if setting exists. |
| DocSettings:hasNot (key) | Checks if setting does not exist. |
| DocSettings:isTrue (key) | Checks if setting is true (boolean). |
| DocSettings:isFalse (key) | Checks if setting is false (boolean). |
| DocSettings:nilOrTrue (key) | Checks if setting is nil or true. |
| DocSettings:nilOrFalse (key) | Checks if setting is nil or false. |
| DocSettings:flipNilOrTrue (key) | Flips nil or true to false, and false to nil. |
| DocSettings:flipNilOrFalse (key) | Flips nil or false to true, and true to nil. |
| DocSettings:flipTrue (key) | Flips a setting between true and nil. |
| DocSettings:flipFalse (key) | Flips a setting between false and nil. |
| DocSettings:toggle (key) | Toggles a boolean setting |
| DocSettings:flush () | Serializes settings and writes them to metadata.lua. |
| DocSettings:purge (full) | Purges (removes) sidecar directory. |
Functions
- DocSettings:getSidecarDir (doc_path)
-
Returns path to sidecar directory (
filename.sdr).Sidecar directory is the file without last suffix.
Parameters:
- doc_path
string
path to the document (e.g.,
/foo/bar.pdf)
Returns:
-
string
path to the sidecar directory (e.g.,
/foo/bar.sdr) - doc_path
string
path to the document (e.g.,
- DocSettings:getSidecarFile (doc_path)
-
Returns path to
metadata.luafile.Parameters:
- doc_path
string
path to the document (e.g.,
/foo/bar.pdf)
Returns:
-
string
path to
/foo/bar.sdr/metadata.luafile - doc_path
string
path to the document (e.g.,
- DocSettings:hasSidecarFile (doc_path)
-
Returns
trueif there is ametadata.luafile.Parameters:
- doc_path
string
path to the document (e.g.,
/foo/bar.pdf)
Returns:
-
bool
- doc_path
string
path to the document (e.g.,
- DocSettings:open (docfile)
-
Opens a document's individual settings (font, margin, dictionary, etc.)
Parameters:
- docfile
string
path to the document (e.g.,
/foo/bar.pdf)
Returns:
-
DocSettings
object
- docfile
string
path to the document (e.g.,
- DocSettings:readSetting (key, default)
-
Reads a setting, optionally initializing it to a default.
If default is provided, and the key doesn't exist yet, it is initialized to default first. This ensures both that the defaults are actually set if necessary, and that the returned reference actually belongs to the DocSettings object straight away, without requiring further interaction (e.g., saveSetting) from the caller.
This is mainly useful if the data type you want to retrieve/store is assigned/returned/passed by reference (e.g., a table), and you never actually break that reference by assigning another one to the same variable, (by e.g., assigning it a new object). c.f., https://www.lua.org/manual/5.1/manual.html#2.2
Parameters:
- key The setting's key
- default Initialization data (Optional)
- DocSettings:saveSetting (key, value)
-
Saves a setting.
Parameters:
- key
- value
- DocSettings:delSetting (key)
-
Deletes a setting.
Parameters:
- key
- DocSettings:has (key)
-
Checks if setting exists.
Parameters:
- key
- DocSettings:hasNot (key)
-
Checks if setting does not exist.
Parameters:
- key
- DocSettings:isTrue (key)
-
Checks if setting is
true(boolean).Parameters:
- key
- DocSettings:isFalse (key)
-
Checks if setting is
false(boolean).Parameters:
- key
- DocSettings:nilOrTrue (key)
-
Checks if setting is
nilortrue.Parameters:
- key
- DocSettings:nilOrFalse (key)
-
Checks if setting is
nilorfalse.Parameters:
- key
- DocSettings:flipNilOrTrue (key)
-
Flips
nilortruetofalse, andfalsetonil. e.g., a setting that defaults to true.Parameters:
- key
- DocSettings:flipNilOrFalse (key)
-
Flips
nilorfalsetotrue, andtruetonil. e.g., a setting that defaults to false.Parameters:
- key
- DocSettings:flipTrue (key)
-
Flips a setting between
trueandnil.Parameters:
- key
- DocSettings:flipFalse (key)
-
Flips a setting between
falseandnil.Parameters:
- key
- DocSettings:toggle (key)
-
Toggles a boolean setting
Parameters:
- key
- DocSettings:flush ()
-
Serializes settings and writes them to
metadata.lua. - DocSettings:purge (full)
-
Purges (removes) sidecar directory.
Parameters:
- full Remove any of the old ones we may consider as candidates in DocSettings open()