Skip to content

Commit 979499a

Browse files
committed
docs: improved examples in the README.md
1 parent 29f2cea commit 979499a

File tree

1 file changed

+39
-21
lines changed

1 file changed

+39
-21
lines changed

README.md

+39-21
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,9 @@
33
This is a small library that provides utilities to parse and
44
manipulate [Java properties](https://docs.oracle.com/javase/9/docs/api/java/util/Properties.html) files.
55

6-
Intended mostly for the tools that need to modify existing property file, without reformatting the contents.
7-
That is achieved by using string array as a backing storage. If you want only to read the properties,
8-
you should convert it to an object or a `Map` using `toObject(...)` or `toMap(...)` function, respectively.
6+
Intended mostly for the tools that need to modify an existing property file without reformatting the contents. This is
7+
achieved by using a string array as a backing storage. If you want only to read the properties, you should convert it to
8+
an object or a `Map` using `toObject(...)` or `toMap(...)` function, respectively.
99

1010
## Usage
1111

@@ -15,6 +15,12 @@ You can install this library using NPM:
1515
npm install js-java-properties
1616
```
1717

18+
### Types
19+
20+
- `Properties` represent lines in the properties file. A single property can span multiple lines.
21+
It is a part of the API, and it may be extended in future versions.
22+
- `KeyValuePair` parsed key and value. Used by `listProperties`.
23+
1824
### Parsing
1925

2026
Parses correctly file contents as a string into lines.
@@ -60,22 +66,25 @@ they are returned here as well.
6066
import * as properties from 'js-java-properties'
6167

6268
const props = properties.empty()
69+
props.lines.push('# comment')
6370
props.lines.push('key1=value1', 'key2 = value2', 'key3: value3')
71+
props.lines.push('key3: duplicate')
6472

6573
for (const {key, value} of properties.listProperties(props)) {
6674
console.log(`${key}=${value}`)
6775
// key1=value1
6876
// key2=value2
6977
// key3=value3
78+
// key3=duplicate
7079
}
7180
```
7281

7382
### Getting a value by key
7483

7584
Note that this method has `O(n)` complexity for every operation.
76-
Use `toObject` or `toMap` methods to convert it into readable object.
85+
Use `toObject` or `toMap` methods to convert it into a readable object.
7786

78-
In case there are duplicate keys, last one is returned.
87+
In case there are duplicate keys, the last one is returned.
7988

8089
```ts
8190
import * as properties from 'js-java-properties'
@@ -85,10 +94,16 @@ props.lines.push('key1=value1', 'key2 = value2', 'key3: value3')
8594

8695
console.log(properties.getProperty(props, 'key2'))
8796
// 'value2'
97+
98+
props.lines.push('key2 = duplicate')
99+
console.log(properties.getProperty(props, 'key2'))
100+
// 'duplicate'
88101
```
89102

90103
### Converting to object or map
91104

105+
In case there are duplicate keys, the last one is returned.
106+
92107
```ts
93108
import * as properties from 'js-java-properties'
94109

@@ -104,10 +119,11 @@ console.log(properties.toMap(props))
104119

105120
### Setting a value
106121

107-
Adds or replaces given key and value. If value is undefined, it is removed.
108-
Empty string still counts as a value.
122+
This method adds or replaces the given key-value pair. If the value is undefined, the key is removed.
123+
Note that an empty string is still considered a value.
109124

110-
If there are duplicate keys in the list, all but first one are removed.
125+
If there are multiple occurrences of the same key in the list, only the first one is kept and
126+
all other occurrences are removed.
111127

112128
```ts
113129
import * as properties from 'js-java-properties'
@@ -116,25 +132,26 @@ const props = properties.empty()
116132
props.lines.push('key1=value1', 'key2 = value2', 'key3: value3')
117133

118134
properties.setProperty(props, 'key2', 'new-value')
119-
console.log(properties.stringify(props))
120-
// 'key1=value1\nkey2 = new-value\nkey3: value3\n'
135+
console.log(props)
136+
// { lines: [ 'key1=value1', 'key2 = new-value', 'key3: value3' ] }
121137

122138
properties.setProperty(props, 'new-key', 'new-value')
123-
console.log(properties.stringify(props))
124-
// 'key1=value1\nkey2 = new-value\nkey3: value3\nnew-key=new-value\n'
139+
console.log(props)
140+
// { lines: [ 'key1=value1', 'key2 = new-value', 'key3: value3', 'new-key: new-value' ] }
125141

126-
properties.setProperty(props, 'new-key', 'new-value', {separator: ':'})
127-
console.log(properties.stringify(props))
128-
// 'key1=value1\nkey2 = new-value\nkey3: value3\nnew-key:new-value\n'
142+
properties.setProperty(props, 'new-key', 'new-value', {separator: ' = '})
143+
console.log(props)
144+
// { lines: [ 'key1=value1', 'key2 = new-value', 'key3: value3', 'new-key = new-value' ] }
129145

130146
properties.setProperty(props, 'key3', undefined)
131-
console.log(properties.stringify(props))
132-
// 'key1=value1\nkey2 = new-value\n'
147+
console.log(props)
148+
// { lines: [ 'key1=value1', 'key2 = new-value', 'new-key = new-value' ] }
133149
```
134150

135151
### Removing a value
136152

137-
Removes given key and value. If there are duplicate keys in the list, all are removed.
153+
Removes the given key and its associated value. If there are duplicate keys with the same name,
154+
all values associated with the given key are removed.
138155

139156
```ts
140157
import * as properties from 'js-java-properties'
@@ -143,8 +160,8 @@ const props = properties.empty()
143160
props.lines.push('key1=value1', 'key2 = value2', 'key3: value3')
144161

145162
properties.removeProperty(props, 'key2')
146-
console.log(properties.stringify(props))
147-
// 'key1=value1\nkey3: value3\n'
163+
console.log(props)
164+
// { lines: [ 'key1=value1', 'key3: value3' ] }
148165
```
149166

150167
## Development
@@ -156,7 +173,8 @@ console.log(properties.stringify(props))
156173
### Publishing
157174

158175
Releases are generated using [Release Please](https://github.com/googleapis/release-please).
159-
Package is automatically published to a [npm registry](https://www.npmjs.com/package/js-java-properties) when release is created.
176+
Package is automatically published to a [npm registry](https://www.npmjs.com/package/js-java-properties),
177+
when release is created.
160178

161179
## Contributing
162180

0 commit comments

Comments
 (0)