WebSVN – perlutils – Diff – /trunk/configFileEditor.md



# configFileEditor
 
A Perl utility for managing configuration files with template merging, interactive editing, and format conversion capabilities.
 
## Overview
 
`configFileEditor` is designed to simplify configuration file management by:
- Merging template structures with existing configuration files
- Providing an interactive hierarchical editor for modifying configurations
- Converting between YAML and JSON formats
- Automatically backing up config files when saving changes
 

 
## Usage
 
```bash
# Basic usage
configFileEditor [-t <template_file>] [-c <config_file>] [-o <output_file>] [-e] [-C]
 
# Positional arguments (backward compatibility)
configFileEditor <template_file> [config_file]
 
# Compare multiple config files
configFileEditor -C -c <file1> -c <file2> [-c <file3> ...]
```
 
## Example of template file
 
The template file is a Perl hash reference that defines the complete configuration structure with default values and inline documentation. Below is a simplified excerpt from the `sneakernet` project's datastructure file (see `../zfs_utils/sneakernet/sneakernet.datastructure` for the full example).

 
## Examples
 
### Merge Template with Existing Config
```bash
configFileEditor -t template.pl -c config.yaml -o output.yaml
```
 
### Interactive Editing
```bash
configFileEditor -c config.yaml -e
```
Navigate through nested structures, modify values, add new keys/elements, rename keys, or delete existing ones.
 
### Compare Multiple Config Files
```bash
# Compare two config files
configFileEditor -C -c production.yaml -c staging.yaml
 
# Compare three or more files
configFileEditor -C -c prod.yaml -c staging.yaml -c dev.yaml
 
# Save comparison report to file
configFileEditor -C -c config1.yaml -c config2.yaml -o comparison.txt
```
Shows all differences including missing keys and differing values.
 
### Format Conversion
```bash
# YAML to JSON
configFileEditor -c config.yaml -o config.json
 
# JSON to YAML
configFileEditor -c config.json -o config.yaml
```
 
### Update Config with New Template Keys
```bash
# Merge new template keys into existing config, preserving user values
configFileEditor -t myapp.datastructure -c myapp.conf.yaml -o myapp.conf.yaml
```
 
### Start Fresh from Template
```bash
# Export template as YAML config
configFileEditor -t myapp.datastructure -o myapp.conf.yaml
```
 
## Interactive Editor Commands
 
When in edit mode (`-e`), the following commands are available:

 
# Export without version control metadata
svn export http://svn.dailydata.net/svn/perlutils/trunk perlutils
 
# Download just this script
svn export http://svn.dailydata.net/svn/perlutils/trunk/configFileEditor
```
 
## Use Cases
 
### 1. User-Friendly Configuration Editing
 
Enable non-technical users to modify complex configuration files without risking syntax errors:
```bash
configFileEditor -c /etc/myapp/config.yaml -e
```
 
### 2. Configuration Version Management
 
When software is updated with new configuration options, merge them into existing configs:
```bash
# v2.0 adds new keys to template
configFileEditor -t myapp-v2.datastructure -c myapp-v1.conf.yaml -o myapp-v2.conf.yaml
```
User customizations are preserved while new defaults are added.
 
### 3. Configuration Format Migration
 
Convert existing configs between formats:
```bash
# Organization switches from JSON to YAML
for file in configs/*.json; do
  configFileEditor -c "$file" -o "${file%.json}.yaml"
done
```
 
### 4. Configuration Deployment
 
Generate initial configuration files from templates:
```bash
configFileEditor -t defaults.pl -o /etc/newapp/config.yaml
```
 
### 5. Configuration Comparison and Auditing
 
Compare config files across environments to identify discrepancies:
```bash
# Compare production vs staging configurations
configFileEditor -C -c /etc/app/prod.yaml -c /etc/app/staging.yaml
 
# Audit multiple server configs
configFileEditor -C -c server1.yaml -c server2.yaml -c server3.yaml -o audit-report.txt
```
Identifies missing keys, type mismatches, and value differences for troubleshooting and compliance.
 
## Technical Details
 

Rev 6	Rev 7
Line 1...	Line 1...
1	`# perlConfigFileUtility`	1	`# configFileEditor`
2		2
3	`A Perl utility for managing configuration files with template merging, interactive editing, and format conversion capabilities.`	3	`A Perl utility for managing configuration files with template merging, interactive editing, and format conversion capabilities.`
4		4
5	`## Overview`	5	`## Overview`
6		6
7	`perlConfigFileUtility` is designed to simplify configuration file management by:	7	`configFileEditor` is designed to simplify configuration file management by:
8	`- Merging template structures with existing configuration files`	8	`- Merging template structures with existing configuration files`
9	`- Providing an interactive hierarchical editor for modifying configurations`	9	`- Providing an interactive hierarchical editor for modifying configurations`
10	`- Converting between YAML and JSON formats`	10	`- Converting between YAML and JSON formats`
11	`- Automatically backing up config files when saving changes`	11	`- Automatically backing up config files when saving changes`
12		12
Line 38...	Line 38...
38		38
39	`## Usage`	39	`## Usage`
40		40
41	```bash	41	```bash
42	`# Basic usage`	42	`# Basic usage`
43	`perlConfigFileUtility [-t <template_file>] [-c <config_file>] [-o <output_file>] [-e] [-C]`	43	`configFileEditor [-t <template_file>] [-c <config_file>] [-o <output_file>] [-e] [-C]`
44		44
45	`# Positional arguments (backward compatibility)`	45	`# Positional arguments (backward compatibility)`
46	`perlConfigFileUtility <template_file> [config_file]`	46	`configFileEditor <template_file> [config_file]`
47		47
48	`# Compare multiple config files`	48	`# Compare multiple config files`
49	`perlConfigFileUtility -C -c <file1> -c <file2> [-c <file3> ...]`	49	`configFileEditor -C -c <file1> -c <file2> [-c <file3> ...]`
50	```	50	```
51		51
52	`## Example of template file`	52	`## Example of template file`
53		53
54	The template file is a Perl hash reference that defines the complete configuration structure with default values and inline documentation. Below is a simplified excerpt from the `sneakernet` project's datastructure file (see `../zfs_utils/sneakernet/sneakernet.datastructure` for the full example).	54	The template file is a Perl hash reference that defines the complete configuration structure with default values and inline documentation. Below is a simplified excerpt from the `sneakernet` project's datastructure file (see `../zfs_utils/sneakernet/sneakernet.datastructure` for the full example).
Line 110...	Line 110...
110		110
111	`## Examples`	111	`## Examples`
112		112
113	`### Merge Template with Existing Config`	113	`### Merge Template with Existing Config`
114	```bash	114	```bash
115	`perlConfigFileUtility -t template.pl -c config.yaml -o output.yaml`	115	`configFileEditor -t template.pl -c config.yaml -o output.yaml`
116	```	116	```
117		117
118	`### Interactive Editing`	118	`### Interactive Editing`
119	```bash	119	```bash
120	`perlConfigFileUtility -c config.yaml -e`	120	`configFileEditor -c config.yaml -e`
121	```	121	```
122	`Navigate through nested structures, modify values, add new keys/elements, rename keys, or delete existing ones.`	122	`Navigate through nested structures, modify values, add new keys/elements, rename keys, or delete existing ones.`
123		123
124	`### Compare Multiple Config Files`	124	`### Compare Multiple Config Files`
125	```bash	125	```bash
126	`# Compare two config files`	126	`# Compare two config files`
127	`perlConfigFileUtility -C -c production.yaml -c staging.yaml`	127	`configFileEditor -C -c production.yaml -c staging.yaml`
128		128
129	`# Compare three or more files`	129	`# Compare three or more files`
130	`perlConfigFileUtility -C -c prod.yaml -c staging.yaml -c dev.yaml`	130	`configFileEditor -C -c prod.yaml -c staging.yaml -c dev.yaml`
131		131
132	`# Save comparison report to file`	132	`# Save comparison report to file`
133	`perlConfigFileUtility -C -c config1.yaml -c config2.yaml -o comparison.txt`	133	`configFileEditor -C -c config1.yaml -c config2.yaml -o comparison.txt`
134	```	134	```
135	`Shows all differences including missing keys and differing values.`	135	`Shows all differences including missing keys and differing values.`
136		136
137	`### Format Conversion`	137	`### Format Conversion`
138	```bash	138	```bash
139	`# YAML to JSON`	139	`# YAML to JSON`
140	`perlConfigFileUtility -c config.yaml -o config.json`	140	`configFileEditor -c config.yaml -o config.json`
141		141
142	`# JSON to YAML`	142	`# JSON to YAML`
143	`perlConfigFileUtility -c config.json -o config.yaml`	143	`configFileEditor -c config.json -o config.yaml`
144	```	144	```
145		145
146	`### Update Config with New Template Keys`	146	`### Update Config with New Template Keys`
147	```bash	147	```bash
148	`# Merge new template keys into existing config, preserving user values`	148	`# Merge new template keys into existing config, preserving user values`
149	`perlConfigFileUtility -t myapp.datastructure -c myapp.conf.yaml -o myapp.conf.yaml`	149	`configFileEditor -t myapp.datastructure -c myapp.conf.yaml -o myapp.conf.yaml`
150	```	150	```
151		151
152	`### Start Fresh from Template`	152	`### Start Fresh from Template`
153	```bash	153	```bash
154	`# Export template as YAML config`	154	`# Export template as YAML config`
155	`perlConfigFileUtility -t myapp.datastructure -o myapp.conf.yaml`	155	`configFileEditor -t myapp.datastructure -o myapp.conf.yaml`
156	```	156	```
157		157
158	`## Interactive Editor Commands`	158	`## Interactive Editor Commands`
159		159
160	When in edit mode (`-e`), the following commands are available:	160	When in edit mode (`-e`), the following commands are available:
Line 228...	Line 228...
228		228
229	`# Export without version control metadata`	229	`# Export without version control metadata`
230	`svn export http://svn.dailydata.net/svn/perlutils/trunk perlutils`	230	`svn export http://svn.dailydata.net/svn/perlutils/trunk perlutils`
231		231
232	`# Download just this script`	232	`# Download just this script`
233	`svn export http://svn.dailydata.net/svn/perlutils/trunk/perlConfigFileUtility`	233	`svn export http://svn.dailydata.net/svn/perlutils/trunk/configFileEditor`
234	```	234	```
235		235
236	`## Use Cases`	236	`## Use Cases`
237		237
238	`### 1. User-Friendly Configuration Editing`	238	`### 1. User-Friendly Configuration Editing`
239		239
240	`Enable non-technical users to modify complex configuration files without risking syntax errors:`	240	`Enable non-technical users to modify complex configuration files without risking syntax errors:`
241	```bash	241	```bash
242	`perlConfigFileUtility -c /etc/myapp/config.yaml -e`	242	`configFileEditor -c /etc/myapp/config.yaml -e`
243	```	243	```
244		244
245	`### 2. Configuration Version Management`	245	`### 2. Configuration Version Management`
246		246
247	`When software is updated with new configuration options, merge them into existing configs:`	247	`When software is updated with new configuration options, merge them into existing configs:`
248	```bash	248	```bash
249	`# v2.0 adds new keys to template`	249	`# v2.0 adds new keys to template`
250	`perlConfigFileUtility -t myapp-v2.datastructure -c myapp-v1.conf.yaml -o myapp-v2.conf.yaml`	250	`configFileEditor -t myapp-v2.datastructure -c myapp-v1.conf.yaml -o myapp-v2.conf.yaml`
251	```	251	```
252	`User customizations are preserved while new defaults are added.`	252	`User customizations are preserved while new defaults are added.`
253		253
254	`### 3. Configuration Format Migration`	254	`### 3. Configuration Format Migration`
255		255
256	`Convert existing configs between formats:`	256	`Convert existing configs between formats:`
257	```bash	257	```bash
258	`# Organization switches from JSON to YAML`	258	`# Organization switches from JSON to YAML`
259	`for file in configs/*.json; do`	259	`for file in configs/*.json; do`
260	`perlConfigFileUtility -c "$file" -o "${file%.json}.yaml"`	260	`configFileEditor -c "$file" -o "${file%.json}.yaml"`
261	`done`	261	`done`
262	```	262	```
263		263
264	`### 4. Configuration Deployment`	264	`### 4. Configuration Deployment`
265		265
266	`Generate initial configuration files from templates:`	266	`Generate initial configuration files from templates:`
267	```bash	267	```bash
268	`perlConfigFileUtility -t defaults.pl -o /etc/newapp/config.yaml`	268	`configFileEditor -t defaults.pl -o /etc/newapp/config.yaml`
269	```	269	```
270		270
271	`### 5. Configuration Comparison and Auditing`	271	`### 5. Configuration Comparison and Auditing`
272		272
273	`Compare config files across environments to identify discrepancies:`	273	`Compare config files across environments to identify discrepancies:`
274	```bash	274	```bash
275	`# Compare production vs staging configurations`	275	`# Compare production vs staging configurations`
276	`perlConfigFileUtility -C -c /etc/app/prod.yaml -c /etc/app/staging.yaml`	276	`configFileEditor -C -c /etc/app/prod.yaml -c /etc/app/staging.yaml`
277		277
278	`# Audit multiple server configs`	278	`# Audit multiple server configs`
279	`perlConfigFileUtility -C -c server1.yaml -c server2.yaml -c server3.yaml -o audit-report.txt`	279	`configFileEditor -C -c server1.yaml -c server2.yaml -c server3.yaml -o audit-report.txt`
280	```	280	```
281	`Identifies missing keys, type mismatches, and value differences for troubleshooting and compliance.`	281	`Identifies missing keys, type mismatches, and value differences for troubleshooting and compliance.`
282		282
283	`## Technical Details`	283	`## Technical Details`
284		284

Subversion Repositories perlutils

(root)/trunk/configFileEditor.md – Rev 6 → 7