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, force_location) Returns path to sidecar directory (filename.sdr).
DocSettings:hasSidecarFile (doc_path) Returns true if there is a metadata.lua file.
DocSettings:findSidecarFile (doc_path, no_legacy) Returns path of metadata.lua file if it exists, or nil.
DocSettings:open (doc_path) Opens a document's individual settings (font, margin, dictionary, etc.)
DocSettings.openSettingsFile (sidecar_file) Light version of open().
DocSettings:flush (data, no_custom_metadata) Serializes settings and writes them to metadata.lua.
DocSettings:purge (sidecar_to_keep, data_to_purge) Purges (removes) sidecar directory.
DocSettings.removeSidecarDir (dir) Removes sidecar dir iff empty.
DocSettings.updateLocation (doc_path, new_doc_path, copy) Updates sdr location for file rename/copy/move/delete operations.
DocSettings:findCustomCoverFile (doc_path) Returns path to book custom cover file if it exists, or nil.
DocSettings:findCustomMetadataFile (doc_path) Returns path to book custom metadata file if it exists, or nil.


Functions

DocSettings:getSidecarDir (doc_path, force_location)
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)
  • force_location string prefer e.g., "hash" or "dir" location over standard "doc", if available

Returns:

    string path to the sidecar directory (e.g., /foo/bar.sdr)
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:findSidecarFile (doc_path, no_legacy)
Returns path of metadata.lua file if it exists, or nil.

Parameters:

  • doc_path string path to the document (e.g., /foo/bar.pdf)
  • no_legacy boolean set to true to skip check of the legacy history file

Returns:

    string (or nil on failure)
DocSettings:open (doc_path)
Opens a document's individual settings (font, margin, dictionary, etc.)

Parameters:

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

Returns:

    DocSettings object
DocSettings.openSettingsFile (sidecar_file)
Light version of open(). Opens a sidecar file or a custom metadata file. Returned object cannot be used to save changes to the sidecar file (flush()). Must be used to save changes to the custom metadata file (flushCustomMetadata()).

Parameters:

  • sidecar_file
DocSettings:flush (data, no_custom_metadata)
Serializes settings and writes them to metadata.lua.

Parameters:

  • data
  • no_custom_metadata
DocSettings:purge (sidecar_to_keep, data_to_purge)
Purges (removes) sidecar directory.

Parameters:

  • sidecar_to_keep
  • data_to_purge
DocSettings.removeSidecarDir (dir)
Removes sidecar dir iff empty.

Parameters:

  • dir
DocSettings.updateLocation (doc_path, new_doc_path, copy)
Updates sdr location for file rename/copy/move/delete operations.

Parameters:

  • doc_path
  • new_doc_path
  • copy
DocSettings:findCustomCoverFile (doc_path)
Returns path to book custom cover file if it exists, or nil.

Parameters:

  • doc_path
DocSettings:findCustomMetadataFile (doc_path)
Returns path to book custom metadata file if it exists, or nil.

Parameters:

  • doc_path
generated by LDoc 1.5.0 Last updated 2024-03-18 16:45:36