Purpose of CSS-like Selectors in the OfficeCLI Query Command

CSS-like selectors in the OfficeCLI query command provide a concise, expressive syntax for filtering elements across Word, Excel, and PowerPoint documents without requiring exact XML paths.

The query verb serves as the read-only entry point for inspecting Office documents in the iOfficeAI/OfficeCLI repository. Instead of navigating complex XML structures manually, users can leverage CSS-like selectors to target specific elements using familiar patterns from web development. This design creates a format-agnostic query language that works uniformly whether you are searching Word paragraphs, Excel cells, or PowerPoint shapes.

Selector Syntax and Capabilities

The selector engine implemented in OfficeCli.Core.AttributeFilter.FilterSelector supports a comprehensive CSS-inspired syntax that goes beyond simple tag matching.

Element Type Selection

You can filter by document-specific element types that map to the underlying Office Open XML structure:

• paragraph – Text blocks in Word documents
• cell – Individual cells in Excel worksheets
• table – Tabular structures across all formats
• row – Table rows and worksheet rows
• slide – Presentation slides in PowerPoint
• shape – Drawing objects and placeholders
• revision – Track changes markup

Attribute Filters

The engine supports precise attribute matching with multiple operators:

• [attr=value] – Exact equality match
• [attr!=value] – Not equal
• [attr~=text] – Contains substring
• [attr>=value] – Greater than or equal (numeric)
• [attr<=value] – Less than or equal (numeric)
• [attr] – Attribute exists (any value)

Pseudo-Classes and Combinators

Advanced filtering uses CSS-style pseudo-classes and structural combinators:

• :contains() – Text content matching
• :empty – Elements with no content
• :has() – Parent elements containing specific children
• :no-alt – Accessibility checks (e.g., images without alt text)
• > – Direct parent-child relationship
• (space) – Any descendant relationship

Boolean Logic

Complex queries combine conditions using explicit operators:

• and – Both conditions must match
• or – Either condition matches
• Parentheses for grouping precedence

Example: cell[(type=Number or type=Date) and value>0]

Architecture and Implementation

The selector system spans multiple source files in the repository, each handling specific responsibilities:

Core Engine

The OfficeCli.Core.AttributeFilter.FilterSelector class serves as the central parsing and execution engine. It processes selector strings into an internal tree structure (SelectorPart) and applies attribute filters uniformly across all document handlers.

Handler-Specific Implementation

In src/officecli/Handlers/Word/WordHandler.Selector.cs, the selector tree is matched against Word-specific elements like paragraphs, runs, and tables. Similar handler implementations exist for Excel and PowerPoint formats.

Command Entry Point

src/officecli/CommandBuilder.GetQuery.cs defines the entry point for the query verb. This file forwards the raw selector string to the appropriate format handler based on the file extension, ensuring the same syntax works across .docx, .xlsx, and .pptx files.

Attribute Processing

src/officecli/Core/AttributeFilter.cs contains the low-level logic for evaluating attribute comparisons. It handles type coercion (converting string attributes to numbers for comparison) and manages the boolean logic evaluation.

Practical Query Examples

Word Document Queries

Find every paragraph styled as "Heading1" in a report:

officecli query report.docx "paragraph[style=Heading1]" --json

Locate empty paragraphs that might indicate formatting issues:

officecli query notes.docx "paragraph:empty" --json

Excel Workbook Queries

List all rows where the "Salary" column exceeds 5000:

officecli query payroll.xlsx "Sheet1!row[Salary>5000]" --json

Combine boolean logic to find outliers:

officecli query data.xlsx "cell[value>1000 or value<0]" --json

PowerPoint Presentation Queries

Retrieve slides containing shapes without alt text for accessibility auditing:

officecli query deck.pptx "slide > shape:no-alt" --json

Find slides containing specific text content:

officecli query presentation.pptx "slide:has(shape:contains('Q4 Results'))" --json

Performance and Design Benefits

The CSS-like selector approach provides specific architectural advantages over traditional XML navigation:

Discoverability – The officecli help <format> query command exposes available element types and attributes, mirroring familiar CSS documentation patterns and reducing the learning curve.

Optimized Execution – The selector engine first narrows candidate sets using pure-AND attribute filters before walking the document object model. This reduces the amount of XML that must be inspected and parsed.

Round-Trip Safety – Because selectors are evaluated read-only, they guarantee that a subsequent set or remove command can target the same element using the same selector. This query → set round-trip preserves context without requiring fragile index-based references.

Extensibility – New element types (such as chart or media) are added by exposing a simple element name in the respective handler. The existing selector syntax works automatically without requiring parser modifications.

Summary

• CSS-like selectors replace complex XML path navigation with familiar, expressive syntax for querying Office documents.
• The system supports element types, attribute operators (=, !=, ~, >=, <=), pseudo-classes (:empty, :contains(), :no-alt), and boolean logic (and/or).
• Core implementation resides in OfficeCli.Core.AttributeFilter.FilterSelector with format-specific handlers in files like WordHandler.Selector.cs.
• The format-agnostic design allows the same query syntax to work across Word, Excel, and PowerPoint files.
• Performance optimization occurs through early filtering, while the read-only nature ensures safe round-trip operations between query and modification commands.

Frequently Asked Questions

How do CSS-like selectors work across different Office formats?

The selector syntax abstracts away format-specific XML differences. According to the iOfficeAI/OfficeCLI source code, the FilterSelector engine parses the selector string into a generic tree structure (SelectorPart) that format handlers then map to their specific element types. This means paragraph maps to Word's <w:p> elements while cell maps to Excel's <c> elements, but the bracket syntax and operators remain identical.

What attribute operators are supported in OfficeCLI selectors?

The src/officecli/Core/AttributeFilter.cs file implements six comparison operators: equality (=), inequality (!=), substring containment (~=), greater-than-or-equal (>=), less-than-or-equal (<=), and existence ([attr]). These work on both string and numeric attributes, with automatic type coercion for numerical comparisons in Excel cells.

How does the selector engine optimize query performance?

The engine applies pure-AND attribute filters first to narrow the candidate set before walking the document hierarchy. As implemented in the FilterSelector class, this filtering happens at the attribute level without requiring full DOM traversal for elements that fail basic criteria. This approach minimizes XML parsing overhead, particularly beneficial for large Excel workbooks with thousands of cells.

Can I combine multiple conditions in a single selector?

Yes, the parser supports explicit boolean logic using and and or keywords with parentheses for precedence grouping. For example, cell[(type=Number or type=Date) and value>0] first evaluates the type condition, then applies the value constraint. This boolean evaluation occurs in AttributeFilter.cs after the initial element type matching completes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}