Profile Match

This reference describes the Profile Match: the Filter Expression or tree a profile document carries in its match key.

A Profile Match tests one Zotero item. ZotLit evaluates it when it creates a literature note. It uses the Filter Expression language of an items query filter. The 匹配 tab of the Template Workbench View writes it into a profile document, and a shared profile carries it in its manifest.

Where a Profile Match livesCopy anchor link

A Profile Match is the match key of a profile document manifest. The match key holds one expression or one tree.

The built-in Default profile carries no match, and a profile without a match key is never selected automatically. You can still select that profile by hand. For the procedure, see Use a different template for different notes, which sets a Match on the 匹配 tab of the Template Workbench View.

FieldsCopy anchor link

A Profile Match can read any field of an item that an items query filter reads. The zotlit:query-schema command lists them. These four fields are the common ones.

Library valuesCopy anchor link

A library value is "personal" or "group:<groupID>", where <groupID> is a positive integer. The value names a group Library by its group ID rather than by a local database ID, so it survives a rebuild of your Zotero database.

A value in neither form, or a group that is not connected, matches no item.

Item type valuesCopy anchor link

Item type names come from the closed set ZotLit builds from Zotero's schema: the top-level item types, excluding the child types attachment, note, and annotation. Fields by item type lists every name in the set. A name outside it matches no item.

Tag valuesCopy anchor link

Tag names are free text, and matching is exact and case-sensitive. Tags you add and tags Zotero adds automatically count alike.

Collection pathsCopy anchor link

A Collection path starts with the root Collection and continues to the direct parent of the item, with the names joined by /. For example, Project/Drafts/Review names the Review Collection under Drafts, under Project.

Paths have no escape syntax, so a Collection whose name contains / is ambiguous. ZotLit evaluates a path against the item's own Library, and it accepts a path that no Library contains: a positive membership test for an absent path is simply false.

Text conditionsCopy anchor link

Text conditions in the Match editor ignore letter case by default. For example, title.icontains("Nature") matches both Nature and NATURE.

Saved title.contains("Nature") expressions open as 包含，区分大小写 rows and keep their results. Each row keeps the text as you typed it. Tag and Collection conditions use exact, case-sensitive membership tests.

Equality testsCopy anchor link

The text fields library and itemType take an equality test.

A value may use double or single quotes, and either side may hold the field. An equality test between a list field and a text, such as tags == "Read", matches no item.

List methodsCopy anchor link

The list fields tags and collections take a list method.

containsAny and containsAll also take one list of values, such as tags.containsAny(["Read", "Cited"]). List methods gives the signature and result of each method.

On collections, contains tests direct filing: collections.contains("Project/Drafts") holds only when the item is filed directly in that exact path. within accepts any descendant. On tags, the value is one Tag name, not a path.

ZotLit rejects a call with the wrong number of arguments, and a within path that is not text. A text field has methods of its own, so itemType.contains("book") tests for book inside the item type name.

OperatorsCopy anchor link

! binds tightest, then &&, then ||:

!tags.contains("Read")
!(itemType == "book" || itemType == "thesis")
itemType == "book" && tags.contains("Read")

true matches every item, and false matches no item.

Tree formCopy anchor link

The match key holds either one expression string or one tree node. A tree node is a mapping with a single key, and, or, or not, whose value is a list of entries. Each entry is an expression string or another tree node.

match: 'itemType == "book" && tags.contains("Read")'

match:
  and:
    - 'itemType == "book"'
    - or:
        - 'tags.contains("Read")'
        - 'collections.within("Project/Drafts")'

and holds when every entry holds. or holds when at least one entry holds. not holds when no entry holds.

An empty list is legal. An empty and or not matches every item. An empty or matches no item.

An entry that is an empty expression string is a mistake, because a leaf has to test something.

Rejected formsCopy anchor link

The three legacy names also take a Library argument. The current language has no equal, because a Collection path is evaluated against the item's own Library.

Selection with a Profile MatchCopy anchor link

ZotLit treats a Profile Match it cannot evaluate as a non-match, not as a refusal. It reports the problem as a diagnostic, keeps the profile out of automatic selection, and continues with the other profiles. Causes include invalid syntax, an unknown function, and a call with the wrong arguments. A profile's row in Settings shows the status of its Profile Match, and the 匹配 tab of the Template Workbench View shows the diagnostic.

A profile with no match key never takes part in automatic selection. A profile whose match holds is used for the new note. When several profiles match, the profile picker opens with the matching candidates. Settings describes the statuses, the condition summary, and the picker. A Match is edited in the profile document, on the 匹配 tab of the Template Workbench View; Use a different template for different notes gives the procedure.

See alsoCopy anchor link

• Profile document for the manifest keys, the note source, the {% managed %} block, and the Annotation Section.
• Use a different template for different notes for creating and sharing a Profile Match.