edf2csv 0.4.78 → 0.5.13

package/dist/cli.js

@@ -45,6 +45,9 @@ Options
       --annotations-only Write only the EDF+ annotations, no signal data
       --decimals <n>     Fix the decimal places instead of deriving them per channel
       --checksum         Record a SHA-256 of the input in metadata.json
+      --layout <kind>    wide (default): one column per channel, one file per
+                         sampling rate. long: one file of time_s,channel,value,
+                         every rate together, one row per sample
       --gzip             Compress every CSV, writing .csv.gz files
       --bom              Start each CSV with a UTF-8 byte order mark, so Excel
                          reads accented text and units like µV correctly
@@ -54,7 +57,7 @@ Options
       --json             Print machine-readable JSON to stdout (works with --info too)
       --strict           Exit 1 if the recording raised any warning
       --stdout           Write the signal CSV to stdout instead of a directory
-                         (single-rate recordings only)
+                         (one table only: one sampling rate, or --layout long)
   -h, --help             Show this help
   -V, --version          Show the version
 
@@ -74,6 +77,9 @@ Output
   With --gzip each CSV becomes a .csv.gz; metadata.json stays plain text so the
   directory can still be read at a glance. With --bom each CSV starts with a
   UTF-8 byte order mark and metadata.json does not, since JSON.parse rejects one.
+  With --layout long every channel goes into one signals.csv as time_s, channel
+  and value, in time order, whatever rates the recording mixes — which is also
+  the one arrangement --stdout can stream for a mixed-rate file.
 
 Examples
   edf2csv recording.edf
@@ -152,6 +158,7 @@ export async function main(argv) {
                 'annotations-only': { type: 'boolean' },
                 decimals: { type: 'string' },
                 checksum: { type: 'boolean' },
+                layout: { type: 'string' },
                 gzip: { type: 'boolean' },
                 bom: { type: 'boolean' },
                 jobs: { type: 'string', short: 'j' },
@@ -201,6 +208,24 @@ export async function main(argv) {
         process.stderr.write(`error: ${printable(entry)}: could not be read, so any recordings inside it were skipped.\n`);
     }
     if (expanded.length === 0) {
+        /*
+          "None here" and "could not look" are different answers, and so are their exit codes.
+    
+          A folder the process cannot read gave the same exit 2 and the same "No EDF or BDF
+          recordings found" as an empty one — while the line above it said the folder could not
+          be read. Exit 2 is this tool's code for "the command itself was wrong", so a script
+          was being told to fix its arguments when what needed fixing was a permission. The
+          command was fine; the filesystem refused.
+    
+          And the sentence itself claimed a fact the run is in no position to state: nothing was
+          found because nothing was looked at.
+        */
+        if (unreadable.length > 0) {
+            process.stderr.write(`Nothing could be converted: ${unreadable.length === 1 ? 'that path' : 'those paths'} ` +
+                `could not be read, so whether ${unreadable.length === 1 ? 'it holds' : 'they hold'} ` +
+                `recordings is unknown.\n`);
+            return EXIT_ERROR;
+        }
         process.stderr.write(`No EDF or BDF recordings found in ${listed(positionals.map((p) => `"${p}"`))}.\n`);
         return EXIT_USAGE;
     }
@@ -228,14 +253,47 @@ export async function main(argv) {
             'Use --stdout for the CSV, or --json for the summary.\n');
         return EXIT_USAGE;
     }
-    // One stream holds one table, for the same reason it holds one recording: concatenating
-    // them would give a CSV whose rows come from different files with nothing marking where
-    // one ends. Naming the count makes it obvious a glob was the cause.
+    /*
+      One stream holds one table, for the same reason it holds one recording: concatenating
+      them would give a CSV whose rows come from different files with nothing marking where
+      one ends. Naming the count makes it obvious a glob was the cause — except when the count
+      is one, which happens for a folder holding a single recording. That read "--stdout writes
+      a single CSV, so it cannot take 1 recordings": ungrammatical, and wrong on its face, since
+      one recording is exactly what it can take. What it cannot take is a folder, whose contents
+      are not known until they are walked.
+    */
     if (toStdout && batch) {
-        process.stderr.write(`--stdout writes a single CSV, so it cannot take ${inputs.length} recordings.\n` +
-            `Convert them to directories instead, or run edf2csv once per file.\n`);
+        process.stderr.write(inputs.length === 1
+            ? `--stdout writes a single CSV, and a folder is converted as a batch even when it ` +
+                `holds one recording.\nName the recording itself — ${inputs[0]} — or convert to a ` +
+                `directory instead.\n`
+            : `--stdout writes a single CSV, so it cannot take ${inputs.length} recordings.\n` +
+                `Convert them to directories instead, or run edf2csv once per file.\n`);
         return EXIT_USAGE;
     }
+    /*
+      Flags that --stdout has nowhere to put.
+  
+      Both were accepted and dropped in silence. `--out` names a directory that is never
+      created, so the run looked like it had written one. `--checksum` is worse than useless:
+      the hash is computed before the first record is read, which is a second full pass over
+      the input, and then the only file it is ever written to — metadata.json — is not written
+      at all. A recording large enough to want a checksum is large enough to notice reading it
+      twice for nothing.
+  
+      Refusing rather than ignoring is what this tool already does for `--stdout --json` and
+      `--stdout --annotations-only`.
+    */
+    for (const [flag, given] of [
+        ['--out', values['out'] !== undefined],
+        ['--checksum', values['checksum'] === true],
+    ]) {
+        if (toStdout && given) {
+            process.stderr.write(`--stdout and ${flag} cannot be combined: --stdout writes no files, and ${flag} has ` +
+                `nothing to act on.\nDrop ${flag}, or drop --stdout and convert to a directory.\n`);
+            return EXIT_USAGE;
+        }
+    }
     /*
       One recording prints the document it always printed; several print one per line.
   
@@ -264,6 +322,7 @@ export async function main(argv) {
             annotationsOnly: values['annotations-only'] === true,
             gzip: values['gzip'] === true,
             bom: values['bom'] === true,
+            layout: optionalLayout(values['layout']),
         };
         // Validated before the --info branch, not inside the conversion path: a flag that
         // cannot be honoured is a usage error whatever mode it was given in, and accepting
@@ -573,7 +632,18 @@ async function convertOne(input, destination, options, emit = writeThrough) {
             // thing worth saying — on stderr, so the CSV on stdout stays clean.
             if (toStdout) {
                 const rows = result.files[0]?.rows ?? 0;
-                emit('err', `Wrote ${rows.toLocaleString('en-US')} rows to stdout.\n`);
+                /*
+                  A reader that closed the pipe did not receive a conversion, so it does not get a
+                  conversion's summary. `edf2csv rec.edf --stdout | head -1` announced "Wrote 52,507
+                  rows to stdout" — a number that is neither the recording's 102,400 nor the one row
+                  head took, but however many had been formatted before the close was noticed. The
+                  count that reached the reader is not knowable from this side; that it stopped early
+                  is, so that is what is said.
+                */
+                emit('err', result.readerHungUp
+                    ? `Stopped: the reader closed the pipe after ${rows.toLocaleString('en-US')} rows ` +
+                        `had been written. The recording was not converted in full.\n`
+                    : `Wrote ${rows.toLocaleString('en-US')} rows to stdout.\n`);
             }
             else {
                 emit('err', `${formatSummary(result)}\n`);
@@ -974,7 +1044,7 @@ async function convertInChild(input, destination, values, running) {
         if (values[flag] === true)
             args.push(`--${flag}`);
     }
-    for (const flag of ['start', 'duration', 'end', 'decimals']) {
+    for (const flag of ['start', 'duration', 'end', 'decimals', 'layout']) {
         if (typeof values[flag] === 'string')
             args.push(`--${flag}=${values[flag]}`);
     }
@@ -1132,6 +1202,14 @@ function optionalTime(raw, option) {
         return undefined;
     return parseTimeSpec(String(raw), option);
 }
+/** `--layout`, which is one of two words and not a guess at what was meant. */
+function optionalLayout(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (raw === 'wide' || raw === 'long')
+        return raw;
+    throw new OptionError(`--layout must be "wide" or "long", got "${String(raw)}".`);
+}
 function optionalDecimals(raw) {
     if (raw === undefined)
         return undefined;