From fdb4e46542a1d477f13e4c79c75f0d3e2f90548c Mon Sep 17 00:00:00 2001 From: Oliver Hamlet Date: Wed, 21 Feb 2018 17:33:25 +0000 Subject: [PATCH] Document the group metadata syntax --- docs/api/reference.rst | 3 ++ docs/api/sorting.rst | 3 +- docs/metadata/data_structures/group.rst | 63 ++++++++++++++++++++++++ docs/metadata/data_structures/index.rst | 1 + docs/metadata/data_structures/plugin.rst | 16 ++++++ docs/metadata/file_structure.rst | 44 +++++++++++------ 6 files changed, 114 insertions(+), 16 deletions(-) create mode 100644 docs/metadata/data_structures/group.rst diff --git a/docs/api/reference.rst b/docs/api/reference.rst index 171fb182..8f4cdff6 100644 --- a/docs/api/reference.rst +++ b/docs/api/reference.rst @@ -54,6 +54,9 @@ Classes .. doxygenclass:: loot::File :members: +.. doxygenclass:: loot::Group + :members: + .. doxygenclass:: loot::Location :members: diff --git a/docs/api/sorting.rst b/docs/api/sorting.rst index 4e9a58e3..d278d74b 100644 --- a/docs/api/sorting.rst +++ b/docs/api/sorting.rst @@ -25,7 +25,8 @@ Create plugin graph vertices Once loaded, a directed graph is created and the plugins are added to it in lexicographical order as vertices. Any metadata a plugin has in the masterlist -and userlist are then merged into its vertex's data store. +and userlist are then merged into its vertex's data store. Plugin group +dependencies are also resolved and added as additional load after plugins. Create plugin graph edges ============================== diff --git a/docs/metadata/data_structures/group.rst b/docs/metadata/data_structures/group.rst new file mode 100644 index 00000000..5eaf49c4 --- /dev/null +++ b/docs/metadata/data_structures/group.rst @@ -0,0 +1,63 @@ +Group +===== + +Groups represent sets of plugins, and are a way to concisely and extensibly +load sets of plugins after other sets of plugins. + +This structure can be used to hold group definitions. It is a key-value map. + +.. describe:: name + + ``string`` + + **Required.** A case-sensitive name that identifies the group. + +.. describe:: after + + ``string set`` + + The names of groups that this group loads after. Group names are + case-sensitive. If undefined, the set is empty. The named groups must be + defined when LOOT sorts plugins, but they don't need to be defined in the same + metadata file. If at sort time a group is defined to load after a group that + does not exist, a sorting error will occur. + +Merging Groups +-------------- + +When a group definition for an already-defined group is encountered, the +``after`` sets of the two definitions are merged. + +The ``default`` Group +--------------------- + +There is one predefined group named ``default`` that all plugins belong to by +default. It is defined with an empty ``after`` set, as no other predefined +groups exist for it to load after. + +Like any other group, the ``default`` group can be redefined to add group names +to its ``after`` set. + +Equality +-------- + +Two group data structures are equal if the values of their ``name`` keys are identical. + +Examples +-------- + +.. code-block:: yaml + + # Create a group for map marker plugins that loads after the predefined + # 'default' group. + name: 'Map Markers' + after: + - 'default' + +.. code-block:: yaml + + # Extend the predefined 'default' group to load after an 'Unofficial Patches' + # group that is defined elsewhere. + name: 'default' + after: + - 'Unofficial Patches' diff --git a/docs/metadata/data_structures/index.rst b/docs/metadata/data_structures/index.rst index 3c15a97d..01b2855e 100644 --- a/docs/metadata/data_structures/index.rst +++ b/docs/metadata/data_structures/index.rst @@ -9,6 +9,7 @@ LOOT expects metadata to be laid out using a certain set of data structures, des tag file + group localised_content message location diff --git a/docs/metadata/data_structures/plugin.rst b/docs/metadata/data_structures/plugin.rst index df8ef1aa..c647ae23 100644 --- a/docs/metadata/data_structures/plugin.rst +++ b/docs/metadata/data_structures/plugin.rst @@ -15,6 +15,21 @@ This is the structure that brings all the others together, and forms the main co Enables or disables use of the plugin object. Used for user rules, but no reason to use it in the masterlist. If unspecified, defaults to ``true``. +.. describe:: group + + ``string`` + + The name of the group the plugin belongs to. If unspecified, defaults to ``default``. + + The named group must be exist when LOOT sorts plugins, but doesn't need to + be defined in the same metadata file. If at sort time the group does not + exist, a sorting error will occur. + + A plugin must load after all the plugins in the groups its group is defined to + load after. Group loading is resolved recursively. For example, if group C + loads after group B, and group B loads after group A, a plugin in C must load + after all the plugins in A even if no plugins in B are installed. + .. describe:: priority ``integer`` @@ -99,6 +114,7 @@ Key Merge Behaviour (merging B into A) =============== ================================== name Not merged. enabled Replaced by B's value. +group Replaced by B's value. priority Replaced by B's value, unless that value is ``0`` and it was not explicitly set. global_priority Replaced by B's value, unless that value is ``0`` and it was not explicitly set. after Merged. If B's file set contains an item that is equal to one already present in A's file set, B's item is discarded. diff --git a/docs/metadata/file_structure.rst b/docs/metadata/file_structure.rst index cf495d3e..e39f1725 100644 --- a/docs/metadata/file_structure.rst +++ b/docs/metadata/file_structure.rst @@ -10,13 +10,18 @@ The root of a metadata file is a key-value map. LOOT will recognise the followin A list of Bash Tags that are supported by the masterlist's game. These Bash Tags are used to provide autocomplete suggestions in LOOT's metadata editor. - .. describe:: globals message list A list of message data structures for messages that are displayed independently of any plugin. +.. describe:: groups + + group set + + A set of group data structures that represent the groups that plugins can belong to. + .. describe:: plugins plugin list *and* plugin set @@ -33,20 +38,29 @@ Example bash_tags: - 'C.Climate' - 'Relev' + globals: - type: say content: 'You are using the latest version of LOOT.' - condition: 'version("LOOT", "0.5.0.0", ==)' - plugins: - - name: 'Armamentarium.esm' - tag: - - Relev - - name: 'ArmamentariumFran.esm' - tag: - - Relev - - name: 'Beautiful People 2ch-Ed.esm' - tag: - - Eyes - - Graphics - - Hair - - R.Relations + condition: 'version("LOOT", "0.5.0.0", ==)' + + groups: + - name: 'Map Markers' + after: + - 'default' + + plugins: + - name: 'Armamentarium.esm' + tag: + - Relev + - name: 'ArmamentariumFran.esm' + tag: + - Relev + - name: 'Beautiful People 2ch-Ed.esm' + tag: + - Eyes + - Graphics + - Hair + - R.Relations + - name: 'More Map Markers.esp' + group: 'Map Markers'