Merge remote-tracking branch 'refs/remotes/origin/main'

README.md

@@ -305,8 +305,15 @@ see the [full API docs](https://masaccio.github.io/numbers-parser/).
 ## Command-line scripts
 
 When installed from [PyPI](https://pypi.org/project/numbers-parser/),
-a command-like script `cat-numbers` is installed in Python’s scripts
-folder. This script dumps Numbers spreadsheets into Excel-compatible CSV
+a number of command-line scripts are installed:
+
+- `cat-numbers`: converts Numbers documents into CSV
+- `csv2numbers`: converts CSV files to Numbers documents
+- `unpack-numbers`: converts Numbers documents into JSON files for debug purposes
+
+### cat-numbers
+
+This script dumps Numbers spreadsheets into Excel-compatible CSV
 format, iterating through all the spreadsheets passed on the
 command-line.
 
@@ -343,6 +350,102 @@ and `datetime.strftime`. Numbers in English locales displays 12-hour
 times with ‘am’ and ‘pm’, but `datetime.strftime` on macOS at least
 cannot return lower-case versions of AM/PM.
 
+### csv2numbers
+
+This script converts Excel-compatible CSV files into Numbers documents. Output files
+can optionally be provided, but is none are provided, the output is created by replacing
+the input’s files suffix with .numbers. For example:
+
+```text
+csv2numbers file1.csv file2.csv -o file1.numbers file2.numbers
+```
+
+Columns of data can have a number of transformations applied to them. The primary use-
+case intended for `csv2numbers` is converting banking exports to well-formatted
+spreadsheets.
+
+```text
+usage: csv2numbers [-h] [-V] [--whitespace] [--reverse] [--no-header]
+                   [--day-first] [--date COLUMNS] [--rename COLUMNS-MAP]
+                   [--transform COLUMNS-MAP] [--delete COLUMNS]
+                   [-o [FILENAME ...]]
+                   [csvfile ...]
+
+positional arguments:
+  csvfile               CSV file to convert
+
+options:
+  -h, --help            show this help message and exit
+  -V, --version
+  --whitespace          strip whitespace from beginning and end of strings
+                        and collapse other whitespace into single space
+                        (default: false)
+  --reverse             reverse the order of the data rows (default:
+                        false)
+  --no-header           CSV file has no header row (default: false)
+  --day-first           dates are represented day first in the CSV file
+                        (default: false)
+  --date COLUMNS        comma-separated list of column names/indexes to
+                        parse as dates
+  --rename COLUMNS-MAP  comma-separated list of column names/indexes to
+                        renamed as 'OLD:NEW'
+  --transform COLUMNS-MAP
+                        comma-separated list of column names/indexes to
+                        transform as 'NEW:FUNC=OLD'
+  --delete COLUMNS      comma-separated list of column names/indexes to
+                        delete
+  -o [FILENAME ...], --output [FILENAME ...]
+                        output filename (default: use source file with
+                        .numbers)
+```
+
+The following options affecting the output of the entire file. The default for each is always false.
+
+- `--whitespace`: strip whitespace from beginning and end of strings and collapse other whitespace into single space
+- `--reverse`: reverse the order of the data rows
+- `--no-header`: CSV file has no header row
+- ``--day-first`: dates are represented day first in the CSV file
+
+`csv2numbers` can also perform column manipulation. Columns can be identified using their name if the CSV file has a header or using a column index. Columns are zero-indexed and names and indices can be used together on the same command-line. When multiple columns are required, you can specify them using comma-separated values. The format for these arguments, like for the CSV file itself, the Excel dialect.
+
+#### Deleting columns
+
+Delete columns using `--delete`. The names or indices of the columns to delete are specified as comma-separated values:
+
+```text
+csv2numbers file1.csv --delete=Account,3
+```
+
+#### Renaming columns
+
+Rename columns using `--rename`. The current column name and new column name are separated by a `:` and each renaming is specified as comma-separated values:
+
+```text
+csv2numbers file1.csv --rename=2:Account,"Paid In":Amount
+```
+
+#### Date columns
+
+The `--date` option identifies a comma-separated list of columns that should be parsed as dates. Use `--day-first` where the day and month is ambiguous anf the day comes first rather than the month.
+
+#### Transforming columns
+
+Columns can be merged and new columns created using simple functions. The –transform option takes a comma-seperated list of transformations of the form NEW:FUNC=OLD. Supported functions are:
+
+| Function   | Arguments                   | Description                                                                                                                                                                                                                                                                                                                                           |
+|------------|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| MERGE      | dest=MERGE:source           | The dest column is writen with values from one or more columns<br/>indicated by source. For multiple columns, which are separated<br/>by ;, the first empty value is chosen.                                                                                                                                                                          |
+| NEG        | dest=NEG:source             | The dest column contains absolute values of any column that is<br/>negative. This is useful for isolating debits from account<br/>exports.                                                                                                                                                                                                            |
+| POS        | dest=NEG:source             | The dest column contains values of any column that is<br/>positive. This is useful for isolating credits from account<br/>exports.                                                                                                                                                                                                                    |
+| LOOKUP     | dest=LOOKUP:source;filename | A lookup map is read from filename which must be an Apple<br/>Numbers file containing a single table of two columns. The table<br/>is used to match agsinst source, searching the first column<br/>for matches and writing the corresponding value from the second<br/>column to dest. Values are chosen based on the longest<br/>matching substring. |
+
+Examples:
+
+```text
+csv2numbers --transform="Paid In"=POS:Amount,Withdrawn=NEG:Amount file1.csv
+csv2numbers --transform='Category=LOOKUP:Transaction;mapping.numbers' file1.csv
+```
+
 ## Limitations
 
 Current known limitations of `numbers-parser` which may be implemented in the future are: