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 () 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)
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
DocSettings:hasSidecarFile (doc_path)
Returns true if there is a metadata.lua file.

Parameters:

  • doc_path string path to the document (e.g., /foo/bar.pdf)

Returns:

    bool
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
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 or true.

Parameters:

  • key
DocSettings:nilOrFalse (key)
Checks if setting is nil or false.

Parameters:

  • key
DocSettings:flipNilOrTrue (key)
Flips nil or true to false, and false to nil. e.g., a setting that defaults to true.

Parameters:

  • key
DocSettings:flipNilOrFalse (key)
Flips nil or false to true, and true to nil. e.g., a setting that defaults to false.

Parameters:

  • key
DocSettings:flipTrue (key)
Flips a setting between true and nil.

Parameters:

  • key
DocSettings:flipFalse (key)
Flips a setting between false and nil.

Parameters:

  • key
DocSettings:toggle (key)
Toggles a boolean setting

Parameters:

  • key
DocSettings:flush ()
Serializes settings and writes them to metadata.lua.
DocSettings:purge ()
Purges (removes) sidecar directory.
generated by LDoc 1.4.6 Last updated 2021-09-20 13:36:42