OfficeCLI DOM Path System: How to Construct Paths Like `/slide[1]/shape[2]`

The OfficeCLI DOM path system uses slash-separated element selectors in the format <tag>[<index>] to uniquely address elements within Word, Excel, or PowerPoint documents through a hierarchical, 1-based indexing scheme.

The OfficeCLI DOM path system provides a unified addressing model for manipulating Office Open XML (OOXML) documents programmatically. In the iOfficeAI/OfficeCLI repository, this system allows developers to target specific elements—whether slides in PowerPoint, paragraphs in Word, or cells in Excel—using intuitive, filesystem-like syntax. Understanding how to construct valid paths such as /slide[1]/shape[2] is essential for automating document modifications via the command line or SDK.

Understanding the OfficeCLI DOM Path Syntax

Element Selector Structure

Each segment in a DOM path follows the pattern <tag>[<index>], where <tag> represents the local name of the OOXML element (e.g., slide, shape, paragraph, cell). The parser splits the path string on forward slashes, ignoring the leading empty segment, and validates each segment against the regular expression ^([a-zA-Z]+)(\[(\d+|[A-Za-z_]\w*)\])?$.

1-Based Indexing and Parameterized Paths

OfficeCLI uses 1-based indexing, meaning shape[1] refers to the first shape of its type under the current parent. When the index is omitted, the parser assumes the first element of that type. The system also supports parameterized paths where indices can be symbolic placeholders like I or myIdx, allowing runtime substitution in scripts and loops.

How the Path Parser Resolves DOM Addresses

The resolution engine in PowerPointHandler.cs implements a five-step validation and traversal process:

1. Tokenization: The input string is split on / characters, discarding the leading empty segment to produce a list of selectors.
2. Pattern Matching: Each segment is validated against the regex ^([a-zA-Z]+)(\[(\d+|[A-Za-z_]\w*)\])?$ to extract the tag name and optional index.
3. OOXML Resolution: The extracted tag is mapped to the concrete OOXML part (slides, shapes, rows, cells, etc.) within the document's in-memory model.
4. Index Conversion: Numeric indices are converted to integers; symbolic names are stored as variables for later substitution by the caller.
5. DOM Traversal: The resolver walks the hierarchical object tree, throwing a not_found error if any step cannot be resolved in the live DOM.

This same resolution logic is reused across document types via WordHandler.cs and ExcelHandler.cs.

Constructing Paths for Different Office Document Types

PowerPoint Path Examples

• /slide[1] — Targets the first slide in the presentation.
• /slide[3]/shape[2] — Targets the second shape on the third slide.
• /slide[I]/shape[2] — Uses a parameterized index for the slide number.

Word and Excel Equivalents

Word documents support paths like /body/p[1] for paragraphs or /tbl[2] for tables, while Excel uses /Sheet1/cell[A1] or /Sheet1/row[3] to address spreadsheet elements.

Practical Code Examples

The following examples demonstrate how to construct and use DOM paths in various scripting environments:

Command Line (Bash)

# Add a shape to slide 2 using a hard-coded index

officecli add deck.pptx '/slide[2]' \
  --type shape --prop text="Hello" --prop x=2cm --prop y=3cm

# Use a shell variable for parameterized access

I=5
officecli get deck.pptx "/slide[${I}]/shape[3]" --json

Python SDK

import officecli

doc = officecli.create("deck.pptx")
for i in range(1, 4):
    # Build path dynamically with f-string

    shape_path = f"/slide[{i}]/shape[1]"
    doc.send({
        "command": "set", 
        "path": shape_path, 
        "props": {"text": f"Slide {i}"}
    })
doc.close()

PowerShell

for ($i = 1; $i -le 3; $i++) {
    officecli set deck.pptx "/slide[$i]/shape[2]" --prop fill=FF0000
}

Core Implementation Files

The DOM path resolution logic is implemented in the following source files within the iOfficeAI/OfficeCLI repository:

• src/officecli/Handlers/Pptx/PowerPointHandler.cs — Contains the core resolve routine that parses /slide[…] syntax and walks the in-memory slide DOM.
• src/officecli/Handlers/Word/WordHandler.cs — Provides analogous path resolution for Word documents, handling tags like body, p, and tbl.
• src/officecli/Handlers/Excel/ExcelHandler.cs — Implements the path system for spreadsheets, resolving sheet names, rows, and cell references.
• README.md — Documents the high-level "Path-based addressing" conceptual model for end users.

Summary

• The OfficeCLI DOM path system uses slash-separated selectors in the format <tag>[<index>] to address OOXML elements.
• Indices are 1-based and can be either literal integers or symbolic placeholders (e.g., I, myIdx) for dynamic resolution.
• The parser validates segments using the regex ^([a-zA-Z]+)(\[(\d+|[A-Za-z_]\w*)\])?$ before traversing the document tree.
• Path resolution is implemented in PowerPointHandler.cs, WordHandler.cs, and ExcelHandler.cs, with each handler mapping tags to document-specific OOXML parts.
• Unresolvable paths trigger a not_found error during DOM traversal.

Frequently Asked Questions

What is the syntax for OfficeCLI DOM paths?

OfficeCLI DOM paths consist of forward-slash-separated segments where each segment follows the pattern <tag>[<index>]. The tag represents the OOXML element name (such as slide, shape, or cell), and the index is a 1-based integer specifying which occurrence of that element to target. For example, /slide[2]/shape[1] addresses the first shape on the second slide.

How do I use variables or placeholders in DOM paths?

You can use symbolic names like I or myIdx inside the brackets instead of literal numbers, creating parameterized paths such as /slide[I]/shape[2]. When executing commands, these placeholders are substituted at runtime by the calling script or application, enabling dynamic iteration over document elements.

Which Office document types support the DOM path system?

The DOM path system supports Word (DOCX), Excel (XLSX), and PowerPoint (PPTX) documents. Each document type has specific handler implementations—WordHandler.cs for paragraphs and tables, ExcelHandler.cs for sheets and cells, and PowerPointHandler.cs for slides and shapes—that parse the same path syntax against their respective OOXML structures.

Where is the path parsing logic implemented in the source code?

The primary path parsing and resolution logic resides in src/officecli/Handlers/Pptx/PowerPointHandler.cs for PowerPoint files, with analogous implementations in src/officecli/Handlers/Word/WordHandler.cs and src/officecli/Handlers/Excel/ExcelHandler.cs. These handlers use the regex ^([a-zA-Z]+)(\[(\d+|[A-Za-z_]\w*)\])?$ to validate path segments before traversing the in-memory DOM.

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