Skip to content

Commit 9d28cbe

Browse files
CobbCoding1CobbCoding1
authored
Add documentation file for overwrite command (#320)
* Add overwrite documentation markdown file
1 parent a8edf02 commit 9d28cbe

File tree

4 files changed

+322
-0
lines changed

4 files changed

+322
-0
lines changed

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,7 @@ that implements the expected
111111
`jq`, `prop`, `rm`
112112
- easily [convert between CSV/JSON/sqlite3](docs/csv_json_sqlite.md)
113113
- [compare multiple files](docs/compare.md)
114+
- [overwrite cells in files](docs/overwrite.md)
114115
- CLI is easy to extend/customize with a few lines of code via modular plug-in
115116
framework. Just write a few custom functions and compile into a distributable
116117
DLL that any existing zsv installation can use.

‎data/bulkdata.csv

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
row,col,value,timestamp
2+
1,2,Saudi Arabia,1733283235
3+
1,7,Kuwait,1733283102
4+
2,3,Israel,1733282194
5+
2,7,Jordan,1733258125
6+
2,2,Palestine,1733285225
7+
2,5,Iraq,1733284211
8+
3,3,Georgia,1733284010
9+
3,4,Azerbaijan,1733285510

‎data/mydata.csv

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Arabian,Fertile Crescent,South Caucasus
2+
Kuwait,Iraq,Armenia
3+
Oman,Jordan,Azerbaijan
4+
Qatar,Lebanon,Georgia
5+
Yemen,Palestine
6+
Bahrain,Syria
7+
Saudi Arabia,Israel
8+
United Arab Emirates

‎docs/overwrite.md

Lines changed: 304 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,304 @@
1+
# Overwrite - Manage Overwrites Associated with a CSV File
2+
3+
The `overwrite` utility allows you to manage a list of "overwrites" associated with a given CSV input file. Each overwrite entry is a tuple consisting of row, column, and new value, along with optional timestamp and author metadata.
4+
5+
## Usage
6+
7+
```shell
8+
overwrite <file> <command> [arguments] [options]
9+
```
10+
11+
### Commands
12+
13+
**List**
14+
`list`
15+
List all overwrites in the overwrites file.
16+
17+
**Add**
18+
`add <cell> <value>`
19+
Add an overwrite entry.
20+
Option for either row-col style cells, or Excel A1 style.
21+
Examples:
22+
1. Overwrite the first column of the first non-header row:
23+
```sh
24+
overwrite mydata.csv add B2 "new value"
25+
```
26+
or
27+
```sh
28+
overwrite mydata.csv add 1-1 "new value"
29+
```
30+
31+
2. Change the header in the second column to "ID #":
32+
```sh
33+
overwrite mydata.csv add B1 "ID #"
34+
```
35+
or
36+
```sh
37+
overwrite mydata.csv add 0-1 "ID #"
38+
```
39+
40+
**Remove**
41+
`remove <cell>`
42+
Remove an overwrite entry.
43+
Similar to add for examples, without value.
44+
45+
**Clear**
46+
`clear`
47+
Remove any or all overwrites.
48+
49+
**Bulk Operations**
50+
`bulk-add <datafile>`
51+
or
52+
`bulk-remove <datafile>`
53+
Bulk operations add or remove overwrite entries from a CSV or JSON file.
54+
55+
**Note:**
56+
JSON not currently supported.
57+
58+
### Options
59+
60+
- **-h, --help**
61+
Show this help message.
62+
63+
- **--old-value <value>**
64+
For `add` or `remove`, only proceed if the current overwrite value matches the given value at the given cell.
65+
66+
- **--force**
67+
- For `add`, proceed even if an overwrite for the specified cell already exists.
68+
- For `remove`, exit without error even if no overwrite for the specified cell already exists.
69+
70+
- **--no-timestamp**
71+
For `add`, do not save a timestamp when adding an overwrite.
72+
73+
- **--all**
74+
For `remove`, remove all overwrites and delete the SQLite file.
75+
76+
- **--A1**
77+
For `list`, display addresses in A1-notation.
78+
79+
## Description
80+
81+
Overwrite data for a given input file `/path/to/my-data.csv` is stored in the "overwrites" table of `/path/to/.zsv/data/my-data.csv/overwrite.sqlite3`.
82+
83+
For bulk operations, the data file must be a CSV with "row", "col," and "value" columns and may optionally include "old value," "timestamp," and/or "author."
84+
85+
## Examples
86+
87+
Example CSV file ([mydata.csv](../data/mydata.csv)):
88+
| Arabian | Fertile Crescent | South Caucasus |
89+
| -------------------- | ------------ | -------------- |
90+
| Kuwait | Iraq | Armenia |
91+
| Oman | Jordan | Azerbaijan |
92+
| Qatar | Lebanon | Georgia |
93+
| Yemen | Palestine | |
94+
| Bahrain | Syria | |
95+
| Saudi Arabia | Israel | |
96+
| United Arab Emirates | | |
97+
98+
### Bulk Overwrite operations
99+
Example layout of a bulk file [bulkdata.csv](../data/bulkdata.csv):
100+
101+
| row | col | value | timestamp |
102+
| --- | --- | ------------ | ---------- |
103+
| 1 | 2 | Saudi Arabia | 1733283235 |
104+
| 1 | 7 | Kuwait | 1733283102 |
105+
| 2 | 3 | Israel | 1733282194 |
106+
| 2 | 7 | Jordan | 1733258125 |
107+
| 2 | 2 | Palestine | 1733285225 |
108+
| 2 | 5 | Iraq | 1733284211 |
109+
| 3 | 3 | Georgia | 1733284010 |
110+
| 3 | 4 | Azerbaijan | 1733285510 |
111+
112+
bulk-add would add overwrites to the overwrite file, where bulk-remove would remove matching overwrites from the overwrite file.
113+
114+
```sh
115+
overwrite mydata.csv bulk-add bulkdata.csv
116+
select mydata.csv --apply-overwrites
117+
```
118+
Output:
119+
| Arabian | Fertile Crescent | South Caucasus |
120+
| ---------------- | ---------------- | -------------- |
121+
| Saudi Arabia | Palestine | Armenia |
122+
| Oman | Israel | Georgia |
123+
| Qatar | Lebanon | Azerbaijan |
124+
| Yemen | Iraq | |
125+
| Bahrain | Syria | |
126+
| Saudi Arabia | Jordan | |
127+
| Kuwait | | |
128+
129+
Now we can list the overwrites
130+
```sh
131+
overwrite mydata.csv list
132+
```
133+
Output:
134+
```
135+
row,column,value,timestamp,author
136+
1,2,Saudi Arabia,1733283235,
137+
1,7,Kuwait,1733283102,
138+
2,2,Palestine,1733285225,
139+
2,3,Israel,1733282194,
140+
2,5,Iraq,1733284211,
141+
2,7,Jordan,1733258125,
142+
3,3,Georgia,1733284010,
143+
3,4,Azerbaijan,1733285510,
144+
```
145+
146+
Applying bulk-remove
147+
```sh
148+
overwrite mydata.csv bulk-remove bulkdata.csv
149+
overwrite mydata.csv list
150+
```
151+
Output:
152+
```
153+
row,column,value,timestamp,author
154+
```
155+
156+
### Basic Overwrite operations
157+
158+
To add an overwrite entry that changes the value in cell B2:
159+
160+
To add a value:
161+
```sh
162+
overwrite mydata.csv add B2 "Syria"
163+
select mydata.csv --apply-overwrites
164+
```
165+
Output:
166+
| Arabian | Fertile Crescent | South Caucasus |
167+
| -------------------- | ------------ | -------------- |
168+
| Kuwait | Syria | Armenia |
169+
| Oman | Jordan | Azerbaijan |
170+
| Qatar | Lebanon | Georgia |
171+
| Yemen | Palestine | |
172+
| Bahrain | Syria | |
173+
| Saudi Arabia | Israel | |
174+
| United Arab Emirates | | |
175+
176+
To remove the added value:
177+
```sh
178+
overwrite mydata.csv remove B2
179+
select mydata.csv --apply-overwrites
180+
```
181+
Output:
182+
| Arabian | Fertile Crescent | South Caucasus |
183+
| -------------------- | ------------ | -------------- |
184+
| Kuwait | Iraq | Armenia |
185+
| Oman | Jordan | Azerbaijan |
186+
| Qatar | Lebanon | Georgia |
187+
| Yemen | Palestine | |
188+
| Bahrain | Syria | |
189+
| Saudi Arabia | Israel | |
190+
| United Arab Emirates | | |
191+
192+
To force add a value, even if there is already a value in that cell.
193+
This overwrites the original value in B2 with the new selected value.
194+
```sh
195+
overwrite mydata.csv add B2 "Lebanon" --force
196+
select mydata.csv --apply-overwrites
197+
```
198+
Output:
199+
| Arabian | Fertile Crescent | South Caucasus |
200+
| -------------------- | ------------ | -------------- |
201+
| Kuwait | Lebanon | Armenia |
202+
| Oman | Jordan | India |
203+
| Qatar | Lebanon | Georgia |
204+
| Yemen | Palestine | |
205+
| Bahrain | Syria | |
206+
| Saudi Arabia | Israel | |
207+
| United Arab Emirates | | |
208+
209+
To remove/add a value, depending on the old value at the cell position.
210+
This will only trigger if the existing value is "Azerbaijan":
211+
```sh
212+
overwrite mydata.csv add C3 "India" --old-value "Azerbaijan"
213+
select mydata.csv --apply-overwrites
214+
```
215+
Output:
216+
| Arabian | Fertile Crescent | South Caucasus |
217+
| -------------------- | ------------ | -------------- |
218+
| Kuwait | Iraq | Armenia |
219+
| Oman | Jordan | India |
220+
| Qatar | Lebanon | Georgia |
221+
| Yemen | Palestine | |
222+
| Bahrain | Syria | |
223+
| Saudi Arabia | Israel | |
224+
| United Arab Emirates | | |
225+
226+
Alternatively, if the old value was not the same as the value in the table.
227+
```sh
228+
overwrite mydata.csv add C3 "Pakistan" --old-value "Armenia"
229+
select mydata.csv --apply-overwrites
230+
```
231+
The output would remain the same, as no values would be changed.
232+
233+
To remove all overwrites and delete the SQLite file:
234+
```sh
235+
overwrite mydata.csv remove --all
236+
select mydata.csv --apply-overwrites
237+
```
238+
Output:
239+
| Arabian | Fertile Crescent | South Caucasus |
240+
| -------------------- | ------------ | -------------- |
241+
| Kuwait | Iraq | Armenia |
242+
| Oman | Jordan | Azerbaijan |
243+
| Qatar | Lebanon | Georgia |
244+
| Yemen | Palestine | |
245+
| Bahrain | Syria | |
246+
| Saudi Arabia | Israel | |
247+
| United Arab Emirates | | |
248+
The table now looks like the original table.
249+
250+
251+
## File Storage
252+
253+
Overwrite data is stored in a dedicated SQLite database for each input file. The SQL operations are optimized for performance, by limiting the number of operations.
254+
The SQLite file gets automatically created when a new overwrite is initialized, and is organized based on the input filename.
255+
256+
## Usage Details
257+
```
258+
zsv overwrite -h
259+
260+
Usage:
261+
overwrite <file> <command> [arguments] [options]
262+
263+
Commands (where <cell> can be <row>-<col> or an Excel-style address):
264+
list : Display all saved overwrite entries
265+
add <cell> <value> : Add an overwrite entry
266+
Example 1: overwrite the first column of the first
267+
non-header row
268+
overwrite mydata.csv add B2 "new value"
269+
- or -
270+
overwrite mydata.csv add 1-1 "new value"
271+
Example 2: change the header in the second column
272+
to "ID #"
273+
overwrite mydata.csv add B1 "new value"
274+
- or -
275+
overwrite mydata.csv add 0-1 "ID #"
276+
remove <cell> : Remove an overwrite entry
277+
clear : Remove any / all overwrites
278+
bulk-add <datafile> : Bulk add overwrite entries from a CSV or JSON file
279+
bulk-remove <datafile> : Bulk remove overwrite entries from a CSV or JSON file
280+
281+
Options:
282+
-h,--help : Show this help message
283+
--old-value <value> : For `add` or `remove`, only proceed if the old value
284+
matches the given value
285+
--force. : For `add`, proceed even if an overwrite for the specified
286+
cell already exists
287+
For `remove`, exit without error even if no overwrite for
288+
the specified cell already exists
289+
--no-timestamp. : For `add`, don't save timestamp when adding an overwrite
290+
--all : For `remove`, remove all overwrites and delete sqlite file
291+
--A1 : For `list`, Display addresses in A1-notation
292+
293+
Description:
294+
The `overwrite` utility allows you to manage a list of "overwrites" associated
295+
with a given CSV input file. Each overwrite entry is a tuple consisting of row,
296+
column, original value, and new value, along with optional timestamp and author
297+
metadata.
298+
299+
Overwrite data for a given input file `/path/to/my-data.csv` is stored in the "over‐
300+
writes" table of `/path/to/.zsv/data/my-data.csv/overwrite.sqlite3`.
301+
302+
For bulk operations, the data file must be a CSV with "row", "col" and "value" columns
303+
and may optionally include "old value", "timestamp" and/or "author"
304+
```

0 commit comments

Comments
 (0)