Advanced Techniques

Master powerful patterns and techniques for complex YAML manipulation.

Overview

This guide covers advanced techniques that combine multiple features for sophisticated frontmatter management. These patterns are useful for power users working with complex data structures.

For Power Users

These techniques assume familiarity with basic operations. Start with File Selection and Actions if you're new to the plugin.

Deep Nesting Strategies

Navigating Complex Hierarchies

Work with multi-level structures efficiently using path expressions.

Pattern: Drilling Down

Access deeply nested values without intermediate variables:

# Access pattern
config.api.endpoints[0].rateLimit.perMinute

# Condition pattern
metadata.author.profile.settings.notifications.email = true

# Update pattern
SET projects[0].milestones[2].tasks[-1].status "completed"

Pattern: Array of Objects Navigation

Navigate through nested arrays of structured data:

# Teams → Members → Skills pattern
teams[0].members[3].skills[-1]

# Projects → Phases → Tasks pattern
projects[2].phases[1].tasks[0].assignee

Best Practices:

• Start with outermost level and work inward
• Use negative indexing for "last item" access
• Validate intermediate paths exist with HAS checks
• Combine with type checking for data validation

Error-Safe Deep Access

Protect against missing intermediate paths:

# Problem: Breaks if config.server doesn't exist
Condition: config.server.database.host = "localhost"

# Solution 1: Check existence
Condition: HAS config.server AND config.server.database.host = "localhost"

# Solution 2: Create structure first
Action: SET config.server.database {host: "localhost", port: 5432}

Pattern Matching Mastery

Advanced Regular Expressions

Go beyond basic string replacement with powerful regex patterns.

Case-Insensitive Replacement

# Strip titles regardless of case
REPLACE author /dr\.?\s+/i ""

# Results:
# "Dr. Smith" → "Smith"
# "dr Smith" → "Smith"
# "DR. SMITH" → "Smith"

Pattern Extraction

Extract specific parts of strings:

# Extract year from filename
REPLACE title /^.*(\d{4}).*$/ "$1"
# "project-report-2024-final" → "2024"

# Extract domain from email
REPLACE contact /@(.+)$/ "$1"
# "alice@example.com" → "example.com"

# Extract first word
REPLACE title /^(\w+).*$/ "$1"
# "My Long Document Title" → "My"

Whitespace Normalization

# Collapse multiple spaces to single space
REPLACE content /\s+/g " "
# "Too   many    spaces" → "Too many spaces"

# Remove leading/trailing whitespace
REPLACE title /^\s+|\s+$/g ""
# "  Title  " → "Title"

# Remove all whitespace
REPLACE code /\s+/g ""
# "function   name ( )" → "functionname()"

Complex Character Removal

# Remove leading/trailing dashes and spaces
REPLACE title /^[-\s]+|[-\s]+$/g ""
# "  -- My Title --  " → "My Title"

# Remove special characters except spaces
REPLACE filename /[^a-zA-Z0-9\s]/g ""
# "My-File_Name#2!" → "MyFileName2"

# Sanitize for URL slugs
REPLACE slug /[^a-z0-9]+/g "-"
# "My Article Title!" → "my-article-title"

Advanced Capture Groups

# Reorder date format
REPLACE date /(\d{4})-(\d{2})-(\d{2})/ "$2/$3/$1"
# "2025-01-15" → "01/15/2025"

# Extract and reformat phone number
REPLACE phone /(\d{3})(\d{3})(\d{4})/ "($1) $2-$3"
# "5551234567" → "(555) 123-4567"

# Swap first and last name
REPLACE author /^(\w+)\s+(\w+)$/ "$2, $1"
# "John Smith" → "Smith, John"

Precision Positioning

Relative Array Manipulation

Move and insert items with surgical precision.

Pattern: Insert After Planning

Place urgent items right after planning phase:

# Scenario: Sprint workflow
Condition: ANY tasks WHERE priority = "critical"
Action: FOR tasks WHERE priority = "critical" MOVE TO AFTER type = "planning"

# Result: Critical tasks execute immediately after planning

Pattern: Group By Category

Organize items by moving related entries together:

# Move all setup tasks to start
FOR tasks WHERE category = "setup" MOVE TO START

# Move all cleanup tasks to end
FOR tasks WHERE category = "cleanup" MOVE TO END

# Group documentation tasks after setup
FOR tasks WHERE category = "documentation" MOVE TO AFTER category = "setup"

Pattern: Enforce Workflow Order

Maintain process dependencies:

# Ensure QA comes before deployment
FOR steps WHERE name = "QA" MOVE TO BEFORE name = "Deployment"

# Ensure testing follows development
FOR phases WHERE name = "Testing" MOVE TO AFTER name = "Development"

Pattern: Priority Insertion

Insert high-priority items at strategic positions:

# High priority after planning, before execution
FOR items WHERE priority > 8 MOVE TO AFTER phase = "planning"

# Urgent items to immediate start
FOR items WHERE urgent = true MOVE TO START

Negative Index Strategies

Access and modify array ends without knowing length.

Pattern: Process Recent Entries

Work with the most recent items in logs or histories:

# Mark last 3 entries as reviewed
FOR history[-3] SET reviewed true
FOR history[-2] SET reviewed true
FOR history[-1] SET reviewed true

# Update last task
Condition: tasks[-1].status = "pending"
Action: FOR tasks[-1] SET status "active", started "{{today}}"

Pattern: Insert Before Last

Maintain a "final" item at the end:

# Keep "summary" as last tag
FOR tags INSERT "important" AT -2

# Before:  [project, active, summary]
# After:   [project, active, important, summary]

Pattern: Remove Recent Items

Clean up recent entries:

# Remove last 2 items if over 100 total
Condition: history.length > 100
Action: FOR history WHERE ... REMOVE  # Remove specific recent items

Complex Conditions & Logic

Operator Precedence

Understand how conditions are evaluated.

Default Precedence: AND before OR

field1 = "a" OR field2 = "b" AND field3 = "c"

# Parsed as:
field1 = "a" OR (field2 = "b" AND field3 = "c")

Using Parentheses for Clarity

Control evaluation order explicitly:

# Group OR first, then AND
(status = "draft" OR status = "review") AND HAS assignee

# Multiple levels of grouping
((priority > 7 OR urgent = true) AND HAS deadline) OR status = "critical"

# Complex real-world example
(tags contains "important" AND created_date > "2025-01-01") OR
(status = "active" AND (priority > 8 OR deadline < "{{today}}"))

Multi-Condition Workflows

Combine multiple checks for sophisticated filtering.

Pattern: Quality Gate

Ensure multiple conditions before processing:

# All criteria must be met
Condition: (status = "draft" AND HAS tags AND tags.length >= 3) AND
           (word_count > 500 AND word_count < 5000) AND
           (HAS author AND author != "")

Action: SET status "ready-for-review", SET reviewed_date "{{today}}"

Pattern: Flexible Matching

Match any of several valid states:

# Any of these states is acceptable
Condition: status IN ["draft", "review", "pending"] AND
           (HAS assignee OR HAS team)

Action: FOR tags APPEND "in-progress"

Pattern: Exclude Multiple States

Filter out unwanted items:

# Exclude archived or deleted
Condition: NOT (status = "archived" OR status = "deleted") AND
           NOT tags contains "obsolete"

Action: FOR tags APPEND "active"

Quantifier Patterns

Use ANY/ALL for sophisticated array queries.

Pattern: Nested Verification

Check conditions in nested structures:

# All projects have at least one active task
Condition: ALL projects WHERE ANY tasks WHERE status = "active"

# Any team has all members verified
Condition: ANY teams WHERE ALL members WHERE verified = true

# Complex nested check
Condition: ANY projects WHERE
           (ALL milestones WHERE completed = true) AND
           (ANY tasks WHERE priority > 7)

Pattern: Existence Check

Verify items exist with specific properties:

# Has at least one high-priority task
Condition: ANY tasks WHERE priority > 8

# All tasks are assigned
Condition: ALL tasks WHERE HAS assignee

# No pending critical items (safety check)
Condition: NOT ANY items WHERE priority = "critical" AND status = "pending"

Bulk Operations & Workflows

Multi-Step Transformations

Execute complex workflows in a single action.

Pattern: Complete Workflow

Perform entire process in one operation:

# Project completion workflow
Action: SET status "completed",
        SET completed_date "{{now}}",
        FOR tasks WHERE status != "done" SET status "cancelled",
        FOR tasks WHERE status = "done" MOVE TO END,
        FOR tags REMOVE_ALL ["in-progress", "pending"],
        FOR tags APPEND "archived",
        SET archived_date "{{today}}",
        INCREMENT projects_completed 1

Pattern: Data Normalization

Clean and standardize data:

# Normalize tags and metadata
Action: FOR tags DEDUPLICATE,
        FOR tags SORT ASC,
        FOR tags WHERE ... REPLACE /\s+/g "-",
        SET tags_normalized true,
        SET normalized_date "{{today}}"

Pattern: Conditional Cascade

Apply multiple transformations conditionally:

# Review workflow with cascading updates
Condition: status = "pending-review" AND review_count < 3

Action: INCREMENT review_count 1,
        FOR tags APPEND "under-review",
        SET last_review_date "{{today}}",
        FOR history APPEND {date: "{{now}}", event: "review-started"},
        FOR reviewers WHERE status = "available" SET status "assigned"

Batch Processing Patterns

Efficiently process multiple items.

Pattern: Selective Updates

Update specific items based on multiple criteria:

# Update overdue high-priority tasks
Condition: ANY tasks WHERE priority > 7 AND deadline < "{{today}}"

Action: FOR tasks WHERE priority > 7 AND deadline < "{{today}}"
        SET status "overdue", flagged true,
        FOR tasks WHERE priority > 7 AND deadline < "{{today}}"
        MOVE TO START,
        SET needs_attention true

Pattern: Progressive Enhancement

Add metadata progressively:

# Enhance metadata over multiple rules
# Rule 1: Add basic metadata
Action: SET processed true, SET processed_date "{{today}}"

# Rule 2: Add counts (separate rule)
Action: SET tag_count "{{tags.length}}", SET has_tags true

# Rule 3: Add derived data (separate rule)
Action: SET category "{{tags[0]}}", SET primary_tag "{{tags[0]}}"

Performance Optimization

Efficient Condition Design

Write conditions that minimize processing.

Do:

• Use specific conditions first: status = "draft" before complex checks
• Check existence before accessing: HAS tags AND tags.length > 0
• Use type checking: priority :number before comparisons
• Exit early with OR: status = "skip" OR ... (short-circuit)

Don't:

• Avoid redundant checks: HAS field AND field exists (redundant)
• Don't nest deeply unnecessarily: Flatten where possible
• Avoid complex regex in conditions: Use simple string checks

Action Optimization

Combine Related Actions:

# Good: Combined
SET status "done", SET completed "{{today}}", INCREMENT count 1

# Bad: Separate rules
# Rule 1: SET status "done"
# Rule 2: SET completed "{{today}}"
# Rule 3: INCREMENT count 1

Order Actions Strategically:

# Process order matters
Action: FOR tags DEDUPLICATE,          # 1. Remove dupes first
        FOR tags SORT ASC,              # 2. Then sort
        FOR tags WHERE ... REMOVE,      # 3. Then remove unwanted
        SET tags_processed true         # 4. Finally mark processed

Edge Cases & Gotchas

Common Pitfalls

Pitfall: Assuming Field Exists

# Bad: Breaks if views doesn't exist
INCREMENT views 1

# Good: Check first or create
Condition: HAS views
Action: INCREMENT views 1

# Or: Create with default
Action: SET views 0, INCREMENT views 1

Pitfall: Type Assumptions

# Bad: Assumes tags is array
FOR tags APPEND "new"

# Good: Verify type
Condition: tags :array
Action: FOR tags APPEND "new"

# Or: Normalize first
Condition: tags !:array AND HAS tags
Action: SET tags ["{{fm:tags}}"]

Pitfall: Empty vs Missing

# Bad: Doesn't distinguish
Condition: NOT HAS tags

# Good: Be explicit
Condition: NOT HAS tags              # Field doesn't exist
Condition: tags empty                # Field exists but is []
Condition: tags :null                # Field exists but is null

Advanced Safety Patterns

Pattern: Defensive Checks

# Verify before complex operations
Condition: HAS projects AND projects :array AND projects.length > 0 AND
           ANY projects WHERE HAS tasks AND tasks :array

Action: FOR projects WHERE ... SET ...

Pattern: Graceful Degradation

# Provide fallbacks
Condition: HAS metadata.author.name

Action: SET display_name "{{fm:metadata.author.name}}"

# Separate rule for fallback
Condition: NOT HAS metadata.author.name

Action: SET display_name "Unknown"

Real-World Scenarios

Scenario: Project Management

Complete project lifecycle management:

# Initialize new project
Condition: status = "new" AND NOT HAS project_id
Action: SET project_id "{{now}}",
        SET created_date "{{today}}",
        SET status "planning",
        FOR tags APPEND "project"

# Start active work
Condition: status = "planning" AND ALL tasks WHERE HAS assignee
Action: SET status "in-progress",
        SET start_date "{{today}}",
        FOR tasks WHERE status = "pending" SET status "active"

# Complete project
Condition: status = "in-progress" AND ALL tasks WHERE status = "done"
Action: SET status "completed",
        SET completed_date "{{today}}",
        FOR tasks MOVE TO END,
        FOR tags REMOVE_ALL ["active", "in-progress"],
        FOR tags APPEND "archived"

Scenario: Content Management

Article lifecycle and metadata management:

# Tag drafts needing review
Condition: status = "draft" AND
           word_count > 1000 AND
           HAS tags AND tags.length >= 3 AND
           NOT tags contains "needs-review"

Action: FOR tags APPEND "needs-review",
        SET review_requested "{{today}}"

# Publish ready content
Condition: status = "reviewed" AND
           ALL reviewers WHERE approved = true AND
           HAS featured_image

Action: SET status "published",
        SET published_date "{{today}}",
        FOR tags REMOVE "needs-review",
        FOR tags APPEND "published",
        FOR history APPEND {date: "{{now}}", event: "published"}

Scenario: Task Management

Automated task prioritization and organization:

# Flag overdue tasks
Condition: ANY tasks WHERE deadline < "{{today}}" AND status != "done"

Action: FOR tasks WHERE deadline < "{{today}}" AND status != "done"
        SET flagged true, status "overdue",
        FOR tasks WHERE flagged = true MOVE TO START,
        SET needs_attention true

# Archive completed tasks
Condition: ALL tasks WHERE status = "done" AND completed_date < "{{today}}"

Action: FOR tasks WHERE status = "done" MOVE TO END,
        FOR tasks WHERE status = "done" SET archived true,
        SET all_tasks_current false

Tips & Best Practices

Development Workflow

1. Start Simple: Begin with basic conditions, add complexity incrementally
2. Test Often: Use the test panel to verify before applying to files
3. Use Dry Run: Preview changes before committing
4. Check One File: Test on a single file before batch operations
5. Keep Backups: Especially when learning complex patterns

Debugging Techniques

1. Break Down Complex Conditions: Test each part separately
2. Use Type Checks: Verify data types match expectations
3. Add Existence Checks: Always verify paths exist
4. Check Test Output: Review diff to ensure expected changes
5. Read Error Messages: They indicate exactly where things failed

Pattern Library

Build reusable patterns for common tasks:

• Data validation: Type checks + existence verification
• Cleanup: Deduplicate + sort + remove unwanted
• Workflow: Status progression + metadata updates + notifications
• Organization: Group + sort + move + flag
• Archival: Mark + move + add tags + set dates

Next Steps

• Explore Complex Queries for sophisticated file selection
• Review Batch Operations for bulk processing
• Check Examples for more real-world patterns
• Consult Syntax Reference for complete operator list

---

Remember: Advanced techniques are powerful but require careful testing. Always verify on test files before applying to your entire vault.