feat: Add a macro that allows users to convert paths into field values

docs/macros.md

@@ -48,3 +48,20 @@ Tool is in development. Will allow for user-defined sorting of [fields](fields.m
 ### Folders to Tags
 
 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.
+
+### Paths to Fields
+
+Populates fields on entries based on their file paths. Users can define regular expressions to extract specific parts of the path, which can be referenced when adding a field.
+In addition, simple operations (`++` and `--`) can be applied on numberic fields. This allows 0-indexed fields to be converted to 1-indexed fields, and vise-a-versa.
+Example usage:
+: Say you have paths like
+: `TagStudioLibrary/artist-artistusername/series name/work title --- page 0.png`
+: We want to extract `artistusername`, `series name`, `work title`, and `0` (the page number).
+: To do this, we can define an expression to fully constrain our path. We *can* allow looser constraints, however if we do that we need to be more careful ensuring the preview matches our desired outcome. 
+: Here are some handy pieces: 
+: * `[^\.]+$` - This matches anything after the final `.` in the path. In other words, the file extension. Even if your path contains a `.`, this ensures the matching does not end early. `$` is an anchor to the end of the line. Similarly, `^` is the anchor to the start, so can be used in the begining. We need to escape `.` with a `\`, because `.` means "match any character once" in regex. `+` means "match this pattern one or more times".
+: * `\\` and `\/` - these match your directory (folder) seperators. Which you use can depend on your Operating System, so use of `[\\\/]` (which matches both) is encouraged. 
+: * `[^\\\/]+` - Similar to the previous, but this does the opposite. This matches as many characters as it can, before it runs into a folder seperator. This is helpful in ensureing that each field you capture is truly in the folder level you expect, and not because the name of an internal folder is similar to that of an external one. 
+: * `\d+` and `\s+` - These match one or more digit and one or more whitespace (like spaces and tabs), respectively. If you need to further constrain this, you can use `\s?` (match a space if its there, otherwise continue) or `\d{3,5}` (match 3 to 5 digits only)  to do so.
+: * `(?P<name_of_group>match_pattern)` - This is a named capture group. We can define `match_pattern` to match the field we want, and make `name_of_group` our field name. This allows us to use `$name_of_group` to reference the item. If these groups were unnamed, we would need to count the order in which they occur, and use their number (ie, the first item is `$1`).
+: Putting this together, we can make our regex capture: `artist-(?P<artist>[^\\\/]+)[\\\/](?P<series>[^\\\/]+)[\\\/](?P<title>.+) --- page\s?(?P<page>\d+)[^\.]+$`

src/tagstudio/core/library/alchemy/library.py

@@ -966,6 +966,12 @@ def remove_entries(self, entry_ids: list[int]) -> None:
                 session.query(Entry).where(Entry.id.in_(sub_list)).delete()
             session.commit()
 
+    def entry_count(self) -> int:
+        """Return the total number of entries in the library."""
+        with Session(self.engine) as session:
+            count = session.scalar(select(func.count(Entry.id)))
+            return int(count or 0)
+
     def has_path_entry(self, path: Path) -> bool:
         """Check if item with given path is in library already."""
         with Session(self.engine) as session:
@@ -1262,6 +1268,73 @@ def get_value_type(self, field_key: str) -> ValueType:
             session.expunge(field)
             return field
 
+    def add_value_type(
+        self,
+        key: str,
+        *,
+        name: str | None = None,
+        field_type: FieldTypeEnum = FieldTypeEnum.TEXT_LINE,
+        is_default: bool = False,
+        position: int | None = None,
+    ) -> ValueType:
+        """Create a new ValueType row and return it.
+
+        - Preserves the provided `key` as-is.
+        - Derives a display `name` from key when not provided.
+        - Appends to the end of current field positions when `position` is not provided.
+        """
+        display_name = name or key.replace("_", " ").title()
+
+        with Session(self.engine) as session:
+            existing = session.scalar(select(ValueType).where(ValueType.key == key))
+            if existing:
+                session.expunge(existing)
+                return existing
+
+            if position is None:
+                max_pos = session.scalar(select(func.max(ValueType.position)))
+                position = (max_pos or 0) + 1
+
+            vt = ValueType(
+                key=key,
+                name=display_name,
+                type=field_type,
+                is_default=is_default,
+                position=position,
+            )
+            try:
+                session.add(vt)
+                session.commit()
+                session.expunge(vt)
+            except IntegrityError:
+                session.rollback()
+                # Fetch the existing row to return a consistent object
+                vt = unwrap(session.scalar(select(ValueType).where(ValueType.key == key)))
+                session.expunge(vt)
+            return vt
+
+    def ensure_value_type(
+        self,
+        key: str,
+        *,
+        name: str | None = None,
+        field_type: FieldTypeEnum = FieldTypeEnum.TEXT_LINE,
+        is_default: bool = False,
+    ) -> ValueType:
+        """Get or create a `ValueType` with the provided key.
+
+        Returns the existing type when present; otherwise creates it.
+        """
+        try:
+            return self.get_value_type(key)
+        except Exception:
+            return self.add_value_type(
+                key,
+                name=name,
+                field_type=field_type,
+                is_default=is_default,
+            )
+
     def add_field_to_entry(
         self,
         entry_id: int,