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.lua
file.Parameters:
- doc_path
string
path to the document (e.g.,
/foo/bar.pdf
)
Returns:
-
string
path to
/foo/bar.sdr/metadata.lua
file - doc_path
string
path to the document (e.g.,
- DocSettings:hasSidecarFile (doc_path)
-
Returns
true
if there is ametadata.lua
file.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
nil
ortrue
.Parameters:
- key
- DocSettings:nilOrFalse (key)
-
Checks if setting is
nil
orfalse
.Parameters:
- key
- DocSettings:flipNilOrTrue (key)
-
Flips
nil
ortrue
tofalse
, andfalse
tonil
. e.g., a setting that defaults to true.Parameters:
- key
- DocSettings:flipNilOrFalse (key)
-
Flips
nil
orfalse
totrue
, andtrue
tonil
. e.g., a setting that defaults to false.Parameters:
- key
- DocSettings:flipTrue (key)
-
Flips a setting between
true
andnil
.Parameters:
- key
- DocSettings:flipFalse (key)
-
Flips a setting between
false
andnil
.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()