A terminal CLI tool for browsing and editing XML tag data directly in your preferred terminal text editor (nano, vim, etc.).

Designed to integrate with VS Code extension workflows and any XML-heavy project.

---

Table of Contents

• Installation
• Requirements
• Quick Start
• Usage
• Options
• Selection Syntax
• Examples
• Setting a Default Editor
• Compatible Editors
• How It Works
• Development
• Contributing

---

Installation

From npm (global install)

npm install -g xml-editor

From source

git clone https://github.com/isocialPractice/xml-editor.git
cd xml-editor
npm install
npm run build
npm link   # makes `xml-editor` available globally

---

Requirements

• Node.js >= 18.0.0
• npm >= 8
• A terminal text editor installed and accessible in your PATH:
  • nano, vim, vi, emacs, micro, ne, joe, pico, mcedit, or jed

---

Quick Start

See QUICKSTART.md for a fast hands-on walkthrough.

# Browse an XML file
xml-editor file.xml

# Use a specific editor
xml-editor --editor vim file.xml

# Set your default editor
xml-editor --set-default

---

Usage

xml-editor [options] <file.xml>

The pager opens, showing all XML tags with their text content truncated to 100 characters. Each tag is labelled:

• Top-level children of root get a digit: 1, 2, 3, ...
• Their children get the parent digit + letter suffix: 1a, 1b, ..., 1z, 1aa, ...
• Deeper nesting extends the suffix: 1aa, 1ab, ..., 1ba, ...

---

Options

Flag	Alias	Description
--help	-h, /?	Show help and exit
--version	-v	Print version and exit
--editor <name>		Use a specific editor for this session
--set-default		Interactively set the persistent default editor

---

Selection Syntax

Type a label (or labels) at the > prompt inside the pager and press Enter to open them.

Input	Action
1d	Open tag labelled 1d in terminal editor
2c	Open tag labelled 2c
1d,2c	Open 1d, save, then open 2c
q	Quit the pager

Navigation keys:

Key	Action
↑ / ↓	Scroll one line
PgUp / PgDn	Scroll one page
Mouse scroll wheel	Scroll (if terminal supports it)
q + Enter	Quit

---

Examples

Browse a file

xml-editor tests/sample/test.xml

The pager output looks like:

1 section -----
   1a title:
     JS Overview Basics

   1b listTitle:
     JavaScript Introduction

   1c paragraph:
     Open JS Full Reference page <a href="/Reference/JS-Full.html" target="_blank">HERE</a>. ...

   1d one:
     Can Change HTML Content: <br><hr><pre><div class="w3-code notranslate j...

2 section -----
   2a title:
     JS Overview Basics
   ...

--- (instructions) ---
>

Edit a single tag

At the prompt, type 1d and press Enter. Your default terminal editor opens containing the full raw text of that tag. Edit, save and quit. The XML file is updated immediately.

Edit multiple tags

> 1d,2d

Each tag opens in sequence; the file is saved after each one.

Specify an editor for one session

xml-editor --editor nano tests/sample/test.xml

Set persistent default editor

xml-editor --set-default

Interactive prompt:

Select editor to use as default for xml-editor:

  1. nano
  2. vim

> vim

The default terminal for this application has been set to `vim`.
To change this run `xml-editor --set-default`.

---

Setting a Default Editor

xml-editor stores its configuration in:

~/.config/xml-editor/config.json

You can edit this file manually, or use --set-default to update it interactively.

Priority order when resolving the editor:

1. --editor <name> CLI flag (current session only)
2. defaultEditor in ~/.config/xml-editor/config.json
3. $EDITOR or $VISUAL environment variables
4. First compatible editor found in PATH

---

Compatible Editors

Any terminal text editor accessible by name in your shell PATH:

• nano
• vim / vi
• emacs
• micro
• ne
• joe
• pico
• mcedit
• jed

---

How It Works

1. Parse - The XML file is parsed using xml2js with child-order preserved.
2. Label - Every element is assigned a hierarchical label (1, 1a, 1b, ...).
3. Display - A less-like pager shows the labelled list with text truncated to 100 characters. XML entities (<, >, etc.) are shown as-is so the display matches the raw file.
4. Edit - Selecting a label writes the tag's raw text (with XML entities) to a temporary file and opens it in your terminal editor.
5. Save - When you save and quit the editor, the temporary file content is decoded from XML entities and written back into the XML file via xml2js Builder, overwriting only the affected tag's content.

---

Development

# Install dependencies
npm install

# Compile TypeScript
npm run build

# Run in dev mode (no build step)
npm run dev -- tests/sample/test.xml

# Run tests
npm test

# Type-check without emitting
npm run lint

Project Structure

xml-editor/
├── src/
│   ├── index.ts      # CLI entry point, argument parsing, main loop
│   ├── parser.ts     # XML parsing, label generation, tree update
│   ├── display.ts    # Less-like pager, line rendering
│   ├── editor.ts     # Terminal editor integration
│   └── config.ts     # Persistent configuration management
├── tests/
│   ├── sample/
│   │   └── test.xml  # Read-only sample (never modified by tests)
│   ├── test.xml      # Generated by `npm run test:setup` (safe to overwrite)
│   └── xml-editor.test.ts
├── dist/             # Compiled output (generated by `npm run build`)
├── package.json
├── tsconfig.json
├── README.md
└── QUICKSTART.md

---

Contributing

Issues and pull requests welcome at issuse

---

xml-editor is authored by isocialPractice.