@castlelemongrab/iniedit

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

Ini.Default

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

Create a new instance of the INI file modification engine.

_string

Optional: Contents of the INI file to pass to parse

_options

Optional: An associative array of generic opeions as an `Object`

Ini.Query

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

Create a search query predicate for use with the `Ini.Default` methods add_section, delete_section, modify_section, or read_properties,

_sections

Optional: An array of section names that should be matched against the section names in the INI file.. Values are case-sensitive strings and/or regular expressions. This is an OR operation; of any one of the specified criteria matches, the section matches.

_where

Optional: An array of two-tuple (key/value pair) properties that must match in order for the the transformation to be applied. Both keys and values are case-sensitive, and may be strings or regular expressions. THis criteria is combined via AND: all clauses must match in order for a section to match.

_comment_where

Optional: An array of comment text that must exist for a match to occur. Values are case-sensitive text and/or regular expressions. These are ANDed together; all must exist independentely and match.

Create a new query for the INI file transformation system.

ini.parse

ini.parse(_string: String)

Create an internal abstract syntax tree from the INI file contents specified in `_string`.

ini.serialize

Emit the internal abstract syntax tree, using this instance's IOH object. To capture or redirect output, provide an IOH instance via the constructor's _options.io parameter.

Ini.Transformer

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

Call _fn and allow it to modify any section of the parsed INI file's abstract syntax tree if the predicates provided match. A set of entirely empty predicates will match any and all sections.

_query

Optional: An instance of Ini.Query specifying matching criteria for the modifications requested. If a section does not match, it will not be modified.

_fn

Required: The transformation function to be applied. The function's prototype is `fn(i, section)`, where `i` is the section offset in `this.tree`, and `section` is the name of the section being transformed,

ini.delete_section

ini.delete_section(
  _query: Ini.Query
)

Remove an INI file section that matches the query _query,

_query

Optional: An instance of Ini.Query specifying matching criteria for the modifications requested. If a section does not match, it will not be altered in any way.

_query

ini.modify_section

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

Modify an INI file section that matches the _sections, _where, and _comment_where criteria.

_query

Optional: An instance of Ini.Query specifying matching criteria for the modifications requested. If a section does not match, it will not be altered in any way.

_properties

Optional: An Object-based associative array of new properties to add. Keys are interpreted as new or replacement property names; values are interpreted as new or replacement property values. A value of null is interpreted as a request to repove the entire INI line whose property name matches the key.

_comments

Optional: An Object-based associative array of new comments to add. Keys are interpreted as new or replacement comments; values are interpreted as either null or non-null. If a value is non-null, the comment is added. If a value is strictly null, the comment is removed if it exists.

_name

Optional: A String to replace the section name with. If this option is null or undefined or omitted, the section's name will remain the same.

ini.add_section

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

Add a new section to an INI file, provided that the _sections, _where, and _comment_where criteria match at least one section in the abstract syntax tree. If all three criteria are omitted or empty, this function considers it a match, and adds the requested section.

_name

Required: The name of the new section to be added.

_properties, _comments

For information on what these arguments mean and how they are structured, see the modify_section method.

_should_prepend

Optional: True if the section should be added at the beginning of the abstract syntax tree (and therefore at the top of the resulting INI file). False or false-like if the section should be appended to the abstract syntax tree (and therefore at the bottom of the resulting file).

_query

Optional: An instance of Ini.Query specifying matching criteria for the modifications requested. If a section does not match, it will not be altered in any way.

ini.read_properties

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

For all sections matching the _sections, _where, and _comment_where criteria, write the INI property values print the value of any property name that appears in _names. Emit results to the current IO object (or standard ourpur) in file order.

_query

Optional: An instance of Ini.Query specifying matching criteria for the modifications requested. If a section does not match, it will not be altered in any way.

_names

An object containing property names as keys; values for these keys will be printed to the current IO object (or standard output) in file order.

__comments

Optional: True if all comments in matching sections should be included in the output in file order. Comments will appear in file order.

Credits

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

License

MIT