A simple command-line INI file editing tool based on ini-parser
npm install @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.
``shell
iniedit add -f /dev/null \
-s Section -l A=1 -l B=2 -c Comment > my.ini
[Section]
$3
If a section named
exists with property values A = 1 and B = 2,
then add a new section named Section #2 with properties A = 2 and B=3.`shell
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
`$3
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
in any INI file section that begins with Section.`shell
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
`$3
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.
shell
iniedit delete -f my.ini \
-r -n '.*=3'[Section]
Comment
A = 1
B = 2
Type = Awesome
`$3
This example adds a new key/value pair and comment to any section that starts
with
and has a Type of Awesome.`shell
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
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 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 readRead 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 addAdd 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 deleteDelete an entire section of an INI file
Local Options:
-c, --compactify Compact whitespace on both sides of deletion [boolean]
iniedit modifyModify 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
typescript
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
Ini.Query
typescript
let q = new Ini.Query(
_sections: Array?,
_where: Array<[ String|RegExp, String|RegExp ]>?,
_comments: Array?
);
`
Create a search query predicate for use with the
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
`typescript
ini.parse(_string: String)
`
Create an internal abstract syntax tree from the INI file contents specified
in
.
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
`typescript
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
, where i is the section
offset in this.tree, and section is the name of the section
being transformed,
ini.delete_section
`typescript
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
typescript
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
typescript
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
typescript
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_names__commentsCredits
-------
Copyright 2020, David Brown
Copyright 2020, Baby Britain, Ltd.
License
-------
MIT