@castlelemongrab/iniedit v0.0.5-pre1

iniedit

Introduction

The iniedit utility is a small program for adding, updating, and deleting sections and/or entries in Common INI Format files. It provides a Javascript API and command-line interface, and allows for conditional criteria to be specified as preconditions for any section modification, addition, or deletion operation.

This repository is a work in progress and absolutely should not be used in production at this time.

CLI Quick Start

In addition to an ES7 Javascript API, this package provides a fully-functional command-line executable called iniedit, which is suitable for small one-off modification of INI files. To get started, run npm i @castlelemongrab/iniedit, then iniedit -h, iniedit add -h, iniedit delete -h, or iniedit modify -h to view built-in documentation.

Example: Build an INI file from /dev/null

iniedit add -f /dev/null \
  -s Section -l A=1 -l B=2 -c Comment > my.ini

[Section]
# Comment
A = 1
B = 2

Example: Conditionally add a new INI section

If a section named Section exists with property values A = 1 and B = 2, then add a new section named Section #2 with properties A = 2 and B=3.

iniedit add \
  -f my.ini -x Section -n A=1 -n B=2 -s 'Section #2' -l A=2 -l B=3

[Section]
# Comment
A = 1
B = 2
[Section #2]
A = 2
B = 3

Example: Adding a property to multiple sections

Regular expressions can be used to match section names, property names, and property values. This example adds or replaces an INI line (N.B. section property) named Type in any INI file section that begins with Section.

iniedit modify -f my.ini \
  -r -x '^Section.*' -l Type=Awesome

[Section]
# Comment
A = 1
B = 2
Type = Awesome
[Section #2]
A = 2
B = 3
Type = Awesome

Example: Deleting a section with regular expressions

Regular expressions can be used to match section names, property names, and property values. This example seletes an INI section thst has a certain matching property value; the key is ignored.

iniedit delete -f my.ini \
  -r -n '.*=3'

[Section]
# Comment
A = 1
B = 2
Type = Awesome

Example: Editing properties

This example adds a new key/value pair and comment to any section that starts with Section and has a Type of Awesome.

iniedit modify -f my.ini -r \
  -x '^Section.*$' -n 'Type=Awesome!?' -l ' Key = Value' -m Extra

[Section]
# Extra
# Comment
A = 1
B = 2
Type = Awesome
Key = Value

CLI Documentation

The command-line interface makes references to INI file "lines"; these are section-contained INI properties specified as key = value pair arguments. Backslash (\) is the escape character for the key portion; values are currently passed along as-is. This CLI escaping behavior – along with escaping and quoting behavior in serialized INI files themselves – will be made more configurable in a future version.

iniedit <command>

Commands:
  iniedit read    Read from one or more matched sections
  iniedit add     Add an entire section to an INI file
  iniedit delete  Delete an entire section of an INI file
  iniedit modify  Modify properties in an INI file section

Global Options:
  --version              Show version number                           [boolean]
  -h, --help             Show help                                     [boolean]
  -v, --verbose          Print extra information to standard error     [boolean]
  -f, --file             The input file in common INI format [string] [required]
  -x, --require-section  Only modify this section name matches           [array]
  -n, --require-line     Only modify if this line exists                 [array]
  -m, --require-comment  Only modify if this comment exists              [array]
  -r, --regex            Interpret all match criteria as expressions   [boolean]

iniedit read

Read from one or more matched sections

Local Options:
  -l, --line             The property/line values to read                [array]
  -c, --comments         Also print all comments, in order             [boolean]

iniedit add

Add an entire section to an INI file

Local Options:
  -s, --section          The name of the section to add      [string] [required]
  -l, --line             A line to add, or key name to read from stdin   [array]
  -c, --comment          A comment string to add                         [array]
  -t, --top              Add the new section to the top of the file    [boolean]

iniedit delete

Delete an entire section of an INI file

Local Options:
  -c, --compactify       Compact whitespace on both sides of deletion  [boolean]

iniedit modify

Modify properties in an INI file section

Local Options:
  -l, --line             A line to add, or key name to read from stdin   [array]
  -c, --comment          A comment string to add                         [array]
  -d, --delete-line      A line name to delete                           [array]
  -o, --delete-comment   A comment string to delete                      [array]
  -e, --section          A replacement section name                     [string]

API Documentation

let ini = new Ini.Default(_string: String, _options: Object)

let q = new Ini.Query(
  _sections: Array<String|RegExp>?,
  _where: Array<[ String|RegExp, String|RegExp ]>?,
  _comments: Array<String|RegExp>?
);

ini.parse(_string: String)

let transform = new transformer(ini.tree);
transform.run(
  _query: Ini.Query, _fn: Function(_i: Number, _section: Object)
)

ini.delete_section(
  _query: Ini.Query
)

ini.modify_section(
  _query: Ini.Query,
    _properties: Object?, _comments: Object?, _name: String?
)

ini.add_section(
  _name: String, _properties: Object?,
  _comments: Object?, _should_prepend: Boolean?, _query: Ini.Query?
)

ini.read_properties(
  _query: Ini.Query?, _names: Object, _comments: Boolean?
)

Credits

Copyright 2020, David Brown
Copyright 2020, Baby Britain, Ltd.

License

MIT