analysis

Documentation

Overview

Package analysis provides tools for analyzing IDML documents and tracking dependencies.

This package is used primarily for IDMS export to collect all resources needed for selected page items. It analyzes the dependency graph of IDML elements to ensure that exported snippets contain all necessary styles, fonts, colors, and other resources.

Key Types

• DependencySet: Tracks all dependencies for a set of page items
• DependencyTracker: Analyzes IDML elements and builds dependency sets
• DependencySummary: Provides counts of each type of dependency

Usage

Analyze dependencies for a selection:

// Create a tracker for the IDML package
tracker := analysis.NewDependencyTracker(pkg)

// Analyze a selection of page items
selection := idml.NewSelection()
selection.AddTextFrame(textFrame)
selection.AddRectangle(rectangle)

err := tracker.AnalyzeSelection(selection)
if err != nil {
    log.Fatal(err)
}

// Resolve style hierarchies to include parent styles
err = tracker.ResolveStyleHierarchies()
if err != nil {
    log.Fatal(err)
}

// Get the dependency set
deps := tracker.Dependencies()
fmt.Printf("Found %d stories, %d styles\n",
    len(deps.Stories), len(deps.ParagraphStyles))

Dependency Types

The tracker identifies these types of dependencies:

• Stories: Referenced story files by filename
• ParagraphStyles: Referenced paragraph style IDs
• CharacterStyles: Referenced character style IDs
• ObjectStyles: Referenced object style IDs
• Colors: Referenced color IDs
• Swatches: Referenced swatch IDs
• Fonts: Referenced font families
• Layers: Referenced layer IDs
• Links: Referenced external file links (for images)
• ColorSpaces: Referenced color spaces (RGB, CMYK, Lab, etc.)

Style Hierarchy Resolution

The ResolveStyleHierarchies method walks through style inheritance chains to ensure that when exporting an IDMS, all styles in the BasedOn hierarchy are included. This handles:

• Multi-level inheritance (grandparent styles, etc.)
• Circular reference detection (to prevent infinite loops)
• Built-in InDesign styles (which don't need to be included)

Architecture

This package is part of the domain-specific architecture that supports IDMS export functionality. It works closely with:

• pkg/idml: For accessing IDML package content
• pkg/spread: For analyzing page items
• pkg/story: For analyzing text content
• pkg/resources: For style hierarchy information

Package analysis provides tools for analyzing IDML documents and tracking dependencies. This is used for IDMS export to collect all resources needed for selected page items.

Example

Example demonstrates basic usage of the analysis package.

package main

import (
	"fmt"
	"log"
	"path/filepath"

	"github.com/dimelords/idmllib/v2/pkg/analysis"
	"github.com/dimelords/idmllib/v2/pkg/idml"
)

func main() {
	// Load a test IDML package
	path := filepath.Join("../../testdata", "example.idml")
	pkg, err := idml.Read(path)
	if err != nil {
		log.Fatal(err)
	}

	// Create a dependency tracker
	tracker := analysis.NewDependencyTracker(pkg)

	// Manually add some dependencies to demonstrate
	deps := tracker.Dependencies()
	deps.ParagraphStyles["ParagraphStyle/Heading1"] = true
	deps.CharacterStyles["CharacterStyle/Bold"] = true
	deps.Stories["Stories/Story_u1d8.xml"] = true

	// Get summary
	summary := tracker.Summary()
	fmt.Printf("Paragraph styles: %d\n", summary.ParagraphStylesCount)
	fmt.Printf("Character styles: %d\n", summary.CharacterStylesCount)
	fmt.Printf("Stories: %d\n", summary.StoriesCount)

}

Output:
Paragraph styles: 1
Character styles: 1
Stories: 1

Index

• type DependencySet
  • func NewDependencySet() *DependencySet
• type DependencySummary
• type DependencyTracker
  • func NewDependencyTracker(pkg *idml.Package) *DependencyTracker
  • func (dt *DependencyTracker) AnalyzeGraphicLine(line *spread.GraphicLine) error
  • func (dt *DependencyTracker) AnalyzeGroup(group *spread.Group) error
  • func (dt *DependencyTracker) AnalyzeImage(img *spread.Image) error
  • func (dt *DependencyTracker) AnalyzeOval(oval *spread.Oval) error
  • func (dt *DependencyTracker) AnalyzePolygon(polygon *spread.Polygon) error
  • func (dt *DependencyTracker) AnalyzeRectangle(rect *spread.Rectangle) error
  • func (dt *DependencyTracker) AnalyzeSelection(sel *idml.Selection) error
  • func (dt *DependencyTracker) AnalyzeStory(story *story.Story) error
  • func (dt *DependencyTracker) AnalyzeTextFrame(tf *spread.SpreadTextFrame) error
  • func (dt *DependencyTracker) Dependencies() *DependencySet
  • func (dt *DependencyTracker) ResolveStyleHierarchies() error
  • func (dt *DependencyTracker) Summary() DependencySummary

Examples

• Package
• DependencyTracker.ResolveStyleHierarchies

Types

type DependencySet

type DependencySet struct {
	// Stories tracks referenced story files by their filename
	// Key: story filename (e.g., "Stories/Story_u1d8.xml")
	Stories map[string]bool

	// ParagraphStyles tracks referenced paragraph style IDs
	// Key: paragraph style ID (e.g., "ParagraphStyle/$ID/[No paragraph style]")
	ParagraphStyles map[string]bool

	// CharacterStyles tracks referenced character style IDs
	// Key: character style ID (e.g., "CharacterStyle/$ID/[No character style]")
	CharacterStyles map[string]bool

	// ObjectStyles tracks referenced object style IDs
	// Key: object style ID (e.g., "ObjectStyle/$ID/[Normal]")
	ObjectStyles map[string]bool

	// Colors tracks referenced color IDs
	// Key: color ID (e.g., "Color/Black")
	Colors map[string]bool

	// Swatches tracks referenced swatch IDs
	// Key: swatch ID
	Swatches map[string]bool

	// Fonts tracks referenced font families
	// Key: font family name (e.g., "Minion Pro")
	Fonts map[string]bool

	// Layers tracks referenced layer IDs
	// Key: layer ID
	Layers map[string]bool

	// Links tracks referenced external file links (for images)
	// Key: link ID or URI
	Links map[string]bool

	// ColorSpaces tracks referenced color spaces (RGB, CMYK, Lab, etc.)
	// Key: color space name
	ColorSpaces map[string]bool
}

DependencySet tracks all dependencies for a set of selected page items. This includes stories, styles, colors, fonts, and other resources needed to export the selection as a standalone IDMS snippet.

func NewDependencySet

func NewDependencySet() *DependencySet

NewDependencySet creates a new empty DependencySet.

type DependencySummary

type DependencySummary struct {
	StoriesCount         int
	ParagraphStylesCount int
	CharacterStylesCount int
	ObjectStylesCount    int
	ColorsCount          int
	SwatchesCount        int
	FontsCount           int
	LayersCount          int
	LinksCount           int
	ColorSpacesCount     int
}

DependencySummary provides a count of each type of dependency.

type DependencyTracker

type DependencyTracker struct {
	// contains filtered or unexported fields
}

DependencyTracker analyzes IDML elements and tracks their dependencies.

func NewDependencyTracker

func NewDependencyTracker(pkg *idml.Package) *DependencyTracker

NewDependencyTracker creates a new DependencyTracker for the given package.

func (*DependencyTracker) AnalyzeGraphicLine

func (dt *DependencyTracker) AnalyzeGraphicLine(line *spread.GraphicLine) error

AnalyzeGraphicLine analyzes a graphic line and tracks all its dependencies. This includes: - Object style applied to the line - Layer the line is on - Colors used in stroke and fill

func (*DependencyTracker) AnalyzeGroup

func (dt *DependencyTracker) AnalyzeGroup(group *spread.Group) error

AnalyzeGroup analyzes a group and tracks all its dependencies. This includes: - Object style applied to the group - Layer the group is on Note: Group contents are typically analyzed separately

func (*DependencyTracker) AnalyzeImage

func (dt *DependencyTracker) AnalyzeImage(img *spread.Image) error

AnalyzeImage analyzes an image and tracks all its dependencies. This includes: - Object style applied to the image - Link to external file - Color space used by the image

func (*DependencyTracker) AnalyzeOval

func (dt *DependencyTracker) AnalyzeOval(oval *spread.Oval) error

AnalyzeOval analyzes an oval and tracks all its dependencies. This includes: - Object style applied to the oval - Layer the oval is on - Image and its dependencies if the oval contains an image - Colors used in stroke and fill

func (*DependencyTracker) AnalyzePolygon

func (dt *DependencyTracker) AnalyzePolygon(polygon *spread.Polygon) error

AnalyzePolygon analyzes a polygon and tracks all its dependencies. This includes: - Object style applied to the polygon - Layer the polygon is on - Image and its dependencies if the polygon contains an image - Colors used in stroke and fill

func (*DependencyTracker) AnalyzeRectangle

func (dt *DependencyTracker) AnalyzeRectangle(rect *spread.Rectangle) error

AnalyzeRectangle analyzes a rectangle and tracks all its dependencies. This includes: - Object style applied to the rectangle - Layer the rectangle is on - Image and its dependencies if the rectangle contains an image

Note: Rectangle doesn't have direct StrokeColor/FillColor attributes. Colors are inherited from AppliedObjectStyle or defined in Properties element.

func (*DependencyTracker) AnalyzeSelection

func (dt *DependencyTracker) AnalyzeSelection(sel *idml.Selection) error

AnalyzeSelection analyzes an entire selection and tracks all dependencies. This is a convenience method that calls the appropriate Analyze* method for each element in the selection.

func (*DependencyTracker) AnalyzeStory

func (dt *DependencyTracker) AnalyzeStory(story *story.Story) error

AnalyzeStory analyzes a story and tracks all style dependencies. This includes: - Paragraph styles used in the story - Character styles used in the story - Fonts referenced by the styles (future enhancement) - Colors used in the styles (future enhancement)

func (*DependencyTracker) AnalyzeTextFrame

func (dt *DependencyTracker) AnalyzeTextFrame(tf *spread.SpreadTextFrame) error

AnalyzeTextFrame analyzes a text frame and tracks all its dependencies. This includes: - The parent story - Object style applied to the frame - Layer the frame is on

func (*DependencyTracker) Dependencies

func (dt *DependencyTracker) Dependencies() *DependencySet

Dependencies returns the collected dependency set.

func (*DependencyTracker) ResolveStyleHierarchies

func (dt *DependencyTracker) ResolveStyleHierarchies() error

ResolveStyleHierarchies walks through all collected style dependencies and adds their parent styles. This ensures that when exporting an IDMS, all styles in the inheritance chain are included. For example, if a paragraph style is based on another style, both must be included.

This method handles: - Paragraph style inheritance (BasedOn relationships) - Character style inheritance (BasedOn relationships) - Object style inheritance (BasedOn relationships) - Circular reference detection (to prevent infinite loops) - Multi-level inheritance (grandparent styles, etc.)

Example

ExampleDependencyTracker_ResolveStyleHierarchies demonstrates style hierarchy resolution.

package main

import (
	"fmt"
	"log"
	"path/filepath"

	"github.com/dimelords/idmllib/v2/pkg/analysis"
	"github.com/dimelords/idmllib/v2/pkg/idml"
)

func main() {
	// Load a test IDML package
	path := filepath.Join("../../testdata", "example.idml")
	pkg, err := idml.Read(path)
	if err != nil {
		log.Fatal(err)
	}

	// Create a dependency tracker
	tracker := analysis.NewDependencyTracker(pkg)

	// Add a style that has a parent hierarchy
	deps := tracker.Dependencies()
	deps.CharacterStyles["CharacterStyle/Naviga%3aFreddans"] = true

	// Resolve style hierarchies
	if err := tracker.ResolveStyleHierarchies(); err != nil {
		log.Fatal(err)
	}

	// Check if parent styles were added
	summary := tracker.Summary()
	fmt.Printf("Character styles after hierarchy resolution: %d\n", summary.CharacterStylesCount)

}

Output:
Character styles after hierarchy resolution: 2

func (*DependencyTracker) Summary

func (dt *DependencyTracker) Summary() DependencySummary

Summary returns a summary of the dependencies found.