Tools Reference

This section covers the utility tools provided by Alt-Ctrl-Proj for common operations when working with XER files.

XER Explorer

The XER Explorer is a utility for exploring and summarizing the contents of XER files. It provides both a command-line interface and a programmatic API.

Overview

When working with XER files, especially large ones, it can be difficult to quickly understand what data is contained within the file. The XER Explorer tool generates a concise report that summarizes the key elements in an XER file, including:

  • File statistics and collection sizes

  • Project details

  • Calendar information

  • WBS elements

  • Resources

  • And optionally activities and relationships (if not too large)

Command-Line Usage

The XER Explorer can be used directly from the command line after installing Alt-Ctrl-Proj. The CLI entry point is installed as xer-explorer:

# Basic usage
xer-explorer path/to/your/file.xer

# Specify custom output file
xer-explorer path/to/your/file.xer -o custom_report.txt

# Include large collections (which are skipped by default)
xer-explorer path/to/your/file.xer --include-large

Options:

  • -o, --output: Specify the output file path (default: xer_exploration.txt)

  • --include-large: Include detailed exploration of large collections

  • --threshold: Set the threshold for what is considered a large collection (default: 1000)

> Note: The xer-explorer command is available after installing the package. The script in scripts/xer_explorer.py is for development or manual use only.

API Reference

class xer_parser.tools.XerExplorer(xer_path)

A class for exploring and summarizing XER files.

Parameters:

xer_path (str) – Path to the XER file to explore

parse_file()

Parse the XER file using the Reader class.

Returns:

True if successful, False otherwise

Return type:

bool

collect_data()

Collect data from all collections in the XER file.

Returns:

Dictionary of collection names and their data

Return type:

dict

generate_report(output_file, skip_large_collections=True, large_threshold=1000)

Generate a report of the XER file contents.

Parameters:

  • output_file (str) – Path to the output file

  • skip_large_collections (bool) – Whether to skip detailed exploration of large collections

  • large_threshold (int) – Threshold for what is considered a large collection

Returns:

True if successful, False otherwise

Return type:

bool

xer_parser.tools.explore_xer_file(xer_path, output_file, skip_large=True, large_threshold=1000)

Explore a XER file and generate a report.

Parameters:

  • xer_path (str) – Path to the XER file

  • output_file (str) – Path to the output file

  • skip_large (bool) – Whether to skip detailed exploration of large collections

  • large_threshold (int) – Threshold for what is considered a large collection

Returns:

True if successful, False otherwise

Return type:

bool

Example Usage

from xer_parser.tools import XerExplorer, explore_xer_file

# Simple function approach
explore_xer_file("path/to/your/file.xer", "output_report.txt")

# Object-oriented approach for more control
explorer = XerExplorer("path/to/your/file.xer")
explorer.parse_file()
explorer.collect_data()
explorer.generate_report("output_report.txt",
                       skip_large_collections=True,
                       large_threshold=1000)

# Access the collected data directly
project_data = explorer.collection_data.get("projects", [])
for project in project_data:
    print(f"Project: {project.proj_short_name}")