Subversion Repositories perlutils

Rev

Rev 6 | Show entire file | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed

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