mirror of
https://github.com/TagStudioDev/TagStudio.git
synced 2026-02-02 08:09:13 +00:00
feat: implement base macro system
This commit is contained in:
Travis Abendshien
@@ -25,3 +25,7 @@ A long string of text displayed as a box of text.
|
||||
A date and time value.
|
||||
|
||||
- e.g: Date Published, Date Taken, etc.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
!!! note
|
||||
Datetime types are a work in progress, and can't currently be manually created or edited.
|
||||
|
||||
392
docs/macros.md
392
docs/macros.md
@@ -2,49 +2,389 @@
|
||||
icon: material/script-text
|
||||
---
|
||||
|
||||
# :material-script-text: Tools & Macros
|
||||
# :material-script-text: Macros
|
||||
|
||||
Tools and macros are features that serve to create a more fluid [library](libraries.md)-managing process, or provide some extra functionality. Please note that some are still in active development and will be fleshed out in future updates.
|
||||
TagStudio features a configurable macro system which allows you to set up automatic or manually triggered actions to perform a wide array of operations on your [library](libraries.md). Each macro is stored in an individual script file and is created using [TOML](https://toml.io/en/) with a predefined schema described below. Macro files are stored in your library's ".TagStudio/macros" folder.
|
||||
|
||||
## Tools
|
||||
## Schema Version
|
||||
|
||||
### Fix Unlinked Entries
|
||||
The `schema_version` key declares which version of the macro schema is currently being used. Current schema version: 1.
|
||||
|
||||
This tool displays the number of unlinked [entries](entries.md), and some options for their resolution.
|
||||
```toml
|
||||
schema_version = 1
|
||||
```
|
||||
|
||||
Refresh
|
||||
: Scans through the library and updates the unlinked entry count.
|
||||
## Triggers
|
||||
|
||||
Search & Relink
|
||||
: Attempts to automatically find and reassign missing files.
|
||||
The `triggers` key declares when a macro may be automatically ran. Macros can still be manually triggered even if they have automatic triggers defined.
|
||||
|
||||
Delete Unlinked Entries
|
||||
: Displays a confirmation prompt containing the list of all missing files to be deleted before committing to or cancelling the operation.
|
||||
- `on_open`: Run when the TagStudio library is opened.
|
||||
- `on_refresh`: Run when the TagStudio library's directories have been refreshed.
|
||||
- `on_new_entry`: Run a new [file entry](entries.md) that has been created.
|
||||
|
||||
### Fix Duplicate Files
|
||||
```toml
|
||||
triggers = ["on_new_entry"]
|
||||
```
|
||||
|
||||
This tool allows for management of duplicate files in the library using a [DupeGuru](https://dupeguru.voltaicideas.net/) file.
|
||||
## Actions
|
||||
|
||||
Load DupeGuru File
|
||||
: load the "results" file created from a DupeGuru scan
|
||||
Actions are defined as TOML tables and serve as an individual action that the macro will perform. An action table must have a unique name, but the name itself has no importance to the macro.
|
||||
|
||||
Mirror Entries
|
||||
: Duplicate entries will have their contents mirrored across all instances. This allows for duplicate files to then be deleted with DupeGuru as desired, without losing the [field](fields.md) data that has been assigned to either. (Once deleted, the "Fix Unlinked Entries" tool can be used to clean up the duplicates)
|
||||
```toml
|
||||
[newgrounds]
|
||||
```
|
||||
|
||||
### Create Collage
|
||||
Action tables must have an `action` key with one of the following values:
|
||||
|
||||
This tool is a preview of an upcoming feature. When selected, TagStudio will generate a collage of all the contents in a Library, which can be found in the Library folder ("/your-folder/.TagStudio/collages/"). Note that this feature is still in early development, and doesn't yet offer any customization options.
|
||||
- [`import_data`](#import-data): Import data from a supported external source.
|
||||
- [`add_data`](#add-data): Add data declared inside the macro file.
|
||||
|
||||
## Macros
|
||||
```toml
|
||||
[newgrounds]
|
||||
action = "import_data"
|
||||
```
|
||||
|
||||
### Auto-fill [WIP]
|
||||
### Import Data
|
||||
|
||||
Tool is in development and will be documented in a future update.
|
||||
The `import_data` action allows you to import external data from any supported source. While some sources need explicit support (e.g. ID3, EXIF) generic sources such as JSON sidecar files can leverage wide array of data shaping options that allow the underlying data structure to be abstracted from TagStudio's internal data structures. This macro pairs very well with tools such as [gallery-dl](https://github.com/mikf/gallery-dl).
|
||||
|
||||
### Sort fields
|
||||
### Add Data
|
||||
|
||||
Tool is in development. Will allow for user-defined sorting of [fields](fields.md).
|
||||
The `add_data` action lets you add data to a [file entry](entries.md) given one or more conditional statements. Unlike the [`import_data`](#import-data) action, the `add_data` action adds data declared in the macro itself rather than importing it form a source external to the macro.
|
||||
|
||||
### Folders to Tags
|
||||
### Data Sources
|
||||
|
||||
Creates tags from the existing folder structure in the library, which are previewed in a hierarchy view for the user to confirm. A tag will be created for each folder and applied to all entries, with each subfolder being linked to the parent folder as a [parent tag](tags.md#parent-tags). Tags will initially be named after the folders, but can be fully edited and customized afterwards.
|
||||
#### Source Format
|
||||
|
||||
The `source_format` key is used in conjunction with the [`import_data`](#import-data) key to declare what type of source data will be imported from.
|
||||
|
||||
```toml
|
||||
[newgrounds]
|
||||
action = "import_data"
|
||||
source_format = "json"
|
||||
```
|
||||
|
||||
- `exif`: Embedded EXIF metadata
|
||||
- `id3`: Embedded ID3 metadata
|
||||
- `json`: A JSON formatted file
|
||||
- `text`: A plain text file
|
||||
- `xml`: An XML formatted file
|
||||
- `xmp`: Embedded XMP metadata or an XMP sidecar file
|
||||
|
||||
#### Source Location
|
||||
|
||||
The `source_location` key is used in conjunction with the `import_data` key to declare where the metadata should be imported from. This can be a relative or absolute path, and can reference the targeted filename with the `{filename}` placeholder.
|
||||
|
||||
```toml
|
||||
[newgrounds]
|
||||
action = "import_data"
|
||||
source_format = "json"
|
||||
source_location = "{filename}.json" # Relative sidecar file
|
||||
```
|
||||
|
||||
<!-- - `absolute`: An absolute file location
|
||||
- `embedded`: Data that's embedded within the targeted file
|
||||
- `sidecar`: A sidecar file with a relative file location -->
|
||||
|
||||
#### Embedded Metadata
|
||||
|
||||
If targeting embedded data, add the `is_embedded` key and set it to `true`. If no `source_location` is used then the file this macro is targeting will be used as a source.
|
||||
|
||||
```toml
|
||||
[newgrounds]
|
||||
action = "import_data"
|
||||
source_format = "id3"
|
||||
is_embedded = true
|
||||
```
|
||||
|
||||
#### Source Filters
|
||||
|
||||
`source_filters` are used to declare a glob list of files that are able to be targeted by this action. An entry filepath only needs to fall under one of the given source filters in order for the macro to continue. If not, then the macro will be skipped for this file entry.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
=== "import_data"
|
||||
```toml
|
||||
[newgrounds]
|
||||
action = "import_data"
|
||||
source_format = "json"
|
||||
source_location = "{filename}.json"
|
||||
source_filters = ["**/Newgrounds/**"]
|
||||
```
|
||||
=== "add_data"
|
||||
```toml
|
||||
[animated]
|
||||
action = "add_data"
|
||||
source_filters = ["**/*.gif", "**/*.apng"]
|
||||
```
|
||||
|
||||
#### Value
|
||||
|
||||
The `value` key is specifically used with the [`add_data`](#add-data) action to define what value should be added to the file entry.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
=== "Title Field"
|
||||
```toml
|
||||
[animated]
|
||||
action = "add_data"
|
||||
source_filters = ["**/*.gif", "**/*.apng"]
|
||||
[animated.title]
|
||||
ts_type = "text_line"
|
||||
name = "Title"
|
||||
value = "Animated Image"
|
||||
```
|
||||
=== "Tags"
|
||||
```toml
|
||||
[animated]
|
||||
action = "add_data"
|
||||
source_filters = ["**/*.gif", "**/*.apng"]
|
||||
[animated.tags]
|
||||
ts_type = "tags"
|
||||
value = ["Animated"]
|
||||
```
|
||||
|
||||
### Importing Data
|
||||
|
||||
With the [`import_data`](#import-data) action it's possible to import various types of data into your TagStudio library in the form of [tags](tags.md) and [fields](fields.md). Since TagStudio tags are more complex than other tag implementations you may be aware of, there are several options for fine-tuning how tags should be imported.
|
||||
|
||||
In order to target the specific kind of TagStudio data you wish to import as, create a table with your action name followed by the "key" name separated by a dot. In most object notation formats (e.g. JSON) this is the key of the key/value pair.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
=== "Importable JSON Data"
|
||||
```json
|
||||
{
|
||||
"newgrounds": {
|
||||
"tags": ["tag1", "tag2"]
|
||||
}
|
||||
}
|
||||
```
|
||||
=== "TOML Macro"
|
||||
```toml
|
||||
[newgrounds]
|
||||
# Newgrounds table info here
|
||||
[newgrounds.tags]
|
||||
# Tag key config here
|
||||
```
|
||||
|
||||
Inside "key" table we can now declare additional information about the native data formats and how they should be imported into TagStudio.
|
||||
|
||||
<!-- #### Source Types
|
||||
|
||||
The `source_type` key allows for the explicit declaration of the type and/or format of the source data. When this key is omitted, TagStudio will default to the data type that makes the most sense for the destination [TagStudio type](#tagstudio-types).
|
||||
|
||||
- `string`: A character string (text)
|
||||
- `integer`: An integer
|
||||
- `float`: A floating point number
|
||||
- `url`: A string with a special URL formatting pass
|
||||
- [`ISO8601`](https://en.wikipedia.org/wiki/ISO_8601) A standard datetime format
|
||||
- `list:string`: List of strings (text)
|
||||
- `list:integer`: List of integers
|
||||
- `list:float`: List of floating point numbers -->
|
||||
|
||||
#### TagStudio Types
|
||||
|
||||
The required `ts_type` key defines the destination data format inside TagStudio itself. This can be [tags](tags.md) or any [field](fields.md) type.
|
||||
|
||||
- [`tags`](tags.md)
|
||||
- [`text_line`](fields.md#text-line)
|
||||
- [`text_box`](fields.md#text-box)
|
||||
- [`datetime`](fields.md#datetime)
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
=== "Title Field"
|
||||
```toml
|
||||
[newgrounds]
|
||||
# newgrounds table info here
|
||||
[newgrounds.title]
|
||||
ts_type = "text_line"
|
||||
name = "Title"
|
||||
```
|
||||
=== "Tags"
|
||||
```toml
|
||||
[newgrounds]
|
||||
# newgrounds table info here
|
||||
[newgrounds.tags]
|
||||
ts_type = "tags"
|
||||
```
|
||||
|
||||
### Multiple Imports per Key
|
||||
|
||||
You may wish to import from the same source key more than once with different instructions. In this case, wrap the table name in an extra pair of brackets for every duplicate key table. This ensures that TagStudio will individually processes each group of instructions for the single key.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
=== "Single Import per Key"
|
||||
```toml
|
||||
[newgrounds]
|
||||
# Newgrounds table info here
|
||||
[newgrounds.artist]
|
||||
ts_type = "tags"
|
||||
use_context = false
|
||||
on_missing = "create"
|
||||
```
|
||||
=== "Multiple Imports per Key"
|
||||
```toml
|
||||
[newgrounds]
|
||||
# Newgrounds table info here
|
||||
[[newgrounds.artist]]
|
||||
ts_type = "tags"
|
||||
use_context = false
|
||||
on_missing = "skip"
|
||||
[[newgrounds.artist]]
|
||||
ts_type = "text_line"
|
||||
name = "Artist"
|
||||
```
|
||||
|
||||
### Field Specific Keys
|
||||
|
||||
#### Name
|
||||
|
||||
`name`: The name of the field to import into.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
=== "text_line"
|
||||
```toml
|
||||
[newgrounds.user]
|
||||
ts_type = "text_line"
|
||||
name = "Author"
|
||||
```
|
||||
=== "text_box"
|
||||
```toml
|
||||
[newgrounds.content]
|
||||
ts_type = "text_box"
|
||||
name = "Description"
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
!!! note
|
||||
As of writing (v9.5.0) TagStudio fields still do not allow for custom names. The macro system is designed to be forward-thinking with this feature in mind, however currently only existing TagStudio field names are considered valid. Any invalid field names will default to the "Notes" field.
|
||||
|
||||
### Tag Specific Keys
|
||||
|
||||
#### Delimiter
|
||||
|
||||
`delimiter`: The delimiter between tags to use.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
=== "Comma + Space Separation"
|
||||
```toml
|
||||
[newgrounds.tags]
|
||||
ts_type = "tags"
|
||||
delimiter = ", "
|
||||
```
|
||||
=== "Newline Separation"
|
||||
```toml
|
||||
[newgrounds.tags]
|
||||
ts_type = "tags"
|
||||
delimiter = "\n"
|
||||
```
|
||||
|
||||
#### Prefix
|
||||
|
||||
`prefix`: An optional prefix to remove.
|
||||
|
||||
Given a list of tags such as `["#tag1", "#tag2", "#tag3"]`, you may wish to remove the "#" prefix.
|
||||
|
||||
```toml
|
||||
[instagram.tags]
|
||||
ts_type = "tags"
|
||||
prefix = "#"
|
||||
```
|
||||
|
||||
#### Strict
|
||||
|
||||
`strict`: Determines what [names](tags.md#naming-tags) of the TagStudio tags should be used to compare against the source data when matching.
|
||||
|
||||
- `true`: Only match against the TagStudio tag [name](tags.md#name) field.
|
||||
- `false` (Default): Match against any TagStudio tag name field including [shorthands](tags.md#shorthand), [aliases](tags.md#aliases), and the [disambiguation name](tags.md#disambiguation).
|
||||
|
||||
#### Use Context
|
||||
|
||||
`use_context`: Determines if TagStudio should use context clues from other source tags to provide more accurate tag matches.
|
||||
|
||||
- `true` (Default): Use context clue matching (slower, less ambiguous).
|
||||
- `false`: Ignore surrounding source tags (faster, more ambiguous).
|
||||
|
||||
#### On Missing
|
||||
|
||||
`on_missing`: Determines the behavior of how to react to source tags with no match in the library.
|
||||
|
||||
- `"prompt"`: Ask the user if they wish to create, skip, or manually choose an existing tag.
|
||||
- `"create"`: Automatically create a new TagStudio tag based on the source tag.
|
||||
- `"skip"` (Default): Ignore the unmatched tags.
|
||||
|
||||
```toml
|
||||
[newgrounds.tags]
|
||||
ts_type = "tags"
|
||||
strict = false
|
||||
use_context = true
|
||||
on_missing = "create"
|
||||
```
|
||||
|
||||
### Manual Tag Mapping
|
||||
|
||||
If the results from the standard tag matching system aren't good enough to properly import specific source data into your TagStudio library, you have the option to manually specify mappings between source and destination tags. A table with the `.map` or `.reverse_map` suffixes will be used to map tags in the nearest scope.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
=== "Global Scope"
|
||||
```toml
|
||||
# Applies to all actions in the macro file
|
||||
[map]
|
||||
```
|
||||
=== "Action Scope"
|
||||
```toml
|
||||
# Applies to all tag keys in the "newgrounds" action
|
||||
[newgrounds.map]
|
||||
```
|
||||
=== "Key Scope"
|
||||
```toml
|
||||
# Only applies to tags within the "ratings" key inside the "newgrounds" action
|
||||
[newgrounds.ratings.map]
|
||||
```
|
||||
|
||||
- `map`: Used for [1 to 0](#1-to-0-ignore-matches), [1 to 1](#1-to-1), and [1 to Many](#1-to-many) mappings.
|
||||
- `reverse_map`: Used for [Many to 1](#many-to-1-reverse-map) mappings.
|
||||
|
||||
#### 1 to 0 (Ignore Matches)
|
||||
|
||||
By mapping the key of the source tag name to an empty string, you can ignore that tag when matching with your own library. This is useful if you're importing from a source that uses tags you don't wish to use or create inside your own libraries.
|
||||
|
||||
```toml
|
||||
[newgrounds.tags.map]
|
||||
# Source Tag Name = Nothing, Ignore Matches
|
||||
favorite = ""
|
||||
```
|
||||
|
||||
#### 1 to 1
|
||||
|
||||
By mapping the key of the source tag name to the name of one of your TagStudio tags, you can directly specify a destination tag while bypassing the matching algorithm.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
!!! tip
|
||||
Consider using tag [aliases](tags.md#aliases) instead of 1 to 1 mapping. This mapping technique is useful if you want to map a specific source tag to a destination tag that you otherwise don't consider to be an alternate name for the destination tag.
|
||||
|
||||
```toml
|
||||
[newgrounds.tags.map]
|
||||
# Source Tag Name = TagStudio Tag Name
|
||||
colored_pencil = "Drawing"
|
||||
```
|
||||
|
||||
#### 1 to Many
|
||||
|
||||
By mapping the key of the source tag name to a list of your TagStudio tag names, you can cause one source tag to import as more than one of your TagStudio tags.
|
||||
|
||||
```toml
|
||||
[newgrounds.tags.map]
|
||||
# Source Tag Name = List of TagStudio Tag Names
|
||||
drawing = ["Drawing (2D)", "Image (Meta Tags)"]
|
||||
video = ["Animation (2D)", "Animated (Meta Tags)"]
|
||||
```
|
||||
|
||||
#### Many to 1 (Reverse Map)
|
||||
|
||||
By mapping a key of the name of one of your TagStudio tags to a list of source tags, you can declare a combination of required source tags that result in a wholly new matched TagStudio tag. This is useful if you use a single tag in your TagStudio library that is represented by multiple split tags from your source.
|
||||
|
||||
```toml
|
||||
[newgrounds.tags.reverse_map]
|
||||
# TagStudio Tag Name = List of Source Tag Names
|
||||
"Animation (2D)" = ["drawing", "video"]
|
||||
"Animation (3D)" = ["3D", "video"]
|
||||
```
|
||||
|
||||
34
docs/relinking.md
Normal file
34
docs/relinking.md
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Entry Relinking
|
||||
icon: material/link-variant
|
||||
---
|
||||
|
||||
# :material-link-variant: Entry Relinking
|
||||
|
||||
### Fix Unlinked Entries
|
||||
|
||||
This tool displays the number of unlinked [entries](entries.md), and some options for their resolution.
|
||||
|
||||
Refresh
|
||||
|
||||
- Scans through the library and updates the unlinked entry count.
|
||||
|
||||
Search & Relink
|
||||
|
||||
- Attempts to automatically find and reassign missing files.
|
||||
|
||||
Delete Unlinked Entries
|
||||
|
||||
- Displays a confirmation prompt containing the list of all missing files to be deleted before committing to or cancelling the operation.
|
||||
|
||||
### Fix Duplicate Files
|
||||
|
||||
This tool allows for management of duplicate files in the library using a [DupeGuru](https://dupeguru.voltaicideas.net/) file.
|
||||
|
||||
Load DupeGuru File
|
||||
|
||||
- load the "results" file created from a DupeGuru scan
|
||||
|
||||
Mirror Entries
|
||||
|
||||
- Duplicate entries will have their contents mirrored across all instances. This allows for duplicate files to then be deleted with DupeGuru as desired, without losing the [field](fields.md) data that has been assigned to either. (Once deleted, the "Fix Unlinked Entries" tool can be used to clean up the duplicates)
|
||||
@@ -252,9 +252,15 @@ Discrete library objects representing [attributes](<https://en.wikipedia.org/wik
|
||||
- [ ] On Library Refresh :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [ ] [...]
|
||||
- [ ] Actions **[v9.5.x]**
|
||||
- [ ] Add Tag(s) :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [ ] Add Field(s) :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [ ] Set Field Content :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [x] Import from JSON file :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [ ] Import from plaintext file :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [ ] Import from XML file :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [x] Create templated fields from other table keys :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [x] Remove tag prefixes from import sources :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [x] Specify tag delimiters from import sources :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [x] Add data (tags + fields) configured in macro :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [x] Glob filter for entry file :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [x] Map source tags to TagStudio tags :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [ ] [...]
|
||||
|
||||
### :material-table-arrow-right: Sharable Data
|
||||
@@ -274,7 +280,7 @@ Packs are intended as an easy way to import and export specific data between lib
|
||||
- [ ] UUIDs + Namespaces :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [ ] Standard, Human Readable Format (TOML) :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [ ] Versioning System :material-chevron-double-up:{ .priority-med title="Medium Priority" }
|
||||
- [ ] Macro Sharing :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.5.x]**
|
||||
- [x] Macro Sharing :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.5.x]**
|
||||
- [ ] Importable :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [ ] Exportable :material-chevron-triple-up:{ .priority-high title="High Priority" }
|
||||
- [ ] Sharable Entry Data :material-chevron-double-up:{ .priority-med title="Medium Priority" } **[v9.9.x]**
|
||||
|
||||
Reference in New Issue
Block a user