Options go on the left as a keyed vector, and the data goes on the right. Option names are case-insensitive.
Files
]help •nget
•nget — Read a file
•nget path reads a UTF-8 text file. •nget "-" reads the rest of standard input. A path that starts with ./ or ../ is relative to the file holding the code, as for •load.
X •nget path takes options on the left: binary (1 reads a vector of byte values) and encoding ("UTF-8"). Files covers bytes and options.
Errors: IO for missing files, invalid UTF-8, other file errors, and standard input that fails or that the frontend doesn’t provide; DOMAIN for invalid options.
]help •nput
•nput — Write a file
path •nput data writes data to a new file. It returns the number of bytes written, which isn’t displayed, as with an assignment. Text is written as UTF-8. An array of numbers is written as bytes, each from 0 to 255, in ravel order. A path that starts with ./ or ../ is relative to the file holding the code, as for •load.
"-" •nput data writes data to standard output, with no line ending added. Text written this way just before a read of ⎕ is that read’s prompt. See ⎕.
X •nput data takes options on the left: path, overwrite (1 replaces an existing file) and encoding ("UTF-8", for text). With the option unique, •nput writes a new file with a unique name inside the directory path. It returns the new file’s path, which is displayed. The option prefix sets the start of the name, as for •mkdir. Plain text on the left is the path. Files covers bytes and options.
Errors: IO for an existing file without overwrite, and for other file errors; DOMAIN for invalid options or byte values, and for bytes written to standard output that aren’t UTF-8.
text←•nget"sales.csv""copy.csv"•nput text["path":"copy.csv""overwrite":1] •nput text
Directories must already exist. Binary reads return exact integers in 0…255. •nput writes an array of numbers as bytes, each an integer in that range. It checks the data before opening the file.
•vfi text returns two vectors, [valid numbers], for the whitespace-separated fields of text. An invalid field has the flag 0ₓ and the value 0. Fields are parsed as numbers, never executed.
separators •vfi text splits on each character in separators instead. It trims whitespace around fields. An empty field is a valid 0. Numeric input covers it.
Errors: DOMAIN when either argument is not text.
Invalid fields have flag 0ₓ and value 0. Valid fields have flag 1ₓ:
A number written plainly, such as 2 or 1.5, is approximate. A number written with an x suffix, such as 3x, or as a rational, such as 1r4, is exact. •vfi also accepts complex numbers written with j or J, ∞, inf, infinity, ASCII signs and signed exponents. nan gives $n. An invalid field gives the number 0 with the flag 0ₓ.
The numbers all become approximate when one of them is approximate and a float can represent every one exactly. Otherwise each number keeps its kind. The 0 from an invalid field doesn’t count as approximate.
1⊃•vfi"2 3x 1r4 1j-2 -1e-3 ∞"
2 3ₓ 1ᵣ4 1ⱼ¯2 ¯0.001 ∞
separators •vfi text splits on any supplied character and trims surrounding whitespace. Empty fields are valid zero. Internal whitespace remains part of the field.
','•vfi"3.9,2.4,,76,"'⋄'•vfi"1 ⋄ 2 3 ⋄ 4"
(1ₓ 1ₓ 1ₓ 1ₓ 1ₓ⋄3.9 2.4 0 76 0)
(1ₓ 0ₓ 1ₓ⋄1 0 4)
Empty input returns two empty vectors. With no separator characters ("" on the left), nonempty input is one field. DOMAIN: either argument is not character text.
JSON
]help •json
•json — JSON
•json text reads JSON5, which includes all JSON. JSON5 adds comments, trailing commas, single-quoted strings, unquoted keys, hexadecimal numbers, Infinity and NaN. Objects become keyed vectors. Arrays become vectors. Strings become character vectors. Integers of up to 128 bits stay exact. true and false become $t and $f.
•json⁻¹ Y writes JSON text. Keyed axes become objects. Unkeyed axes become arrays. Character vectors become strings. Keyed entries that hold functions are left out. NaN writes as null.
["fill":v] •json text reads null as v. The default is NaN. An integer array with a null stays exact. ["fill":v] •json⁻¹ Y writes v as null. JSON covers the conversions.
Errors: DOMAIN for malformed JSON, with its line and column, and for values that JSON can’t hold: an infinity that isn’t fill, out-of-range floats, nonintegral rationals, complex numbers and other functions.
JSON integers are exact. Numbers with a decimal point or an exponent are approximate. An array’s numbers combine by the rule in Numeric input. true and false read as $t and $f. •json⁻¹ writes Booleans back as true and false:
•csv text parses CSV into a vector of columns. Headers become keys. Numeric columns become numbers. Missing numeric cells become NaN. An integer column with missing cells stays exact. Missing text cells become "".
•csv⁻¹ T writes CSV text for a vector of columns. Keys supply the header. Column lengths must agree. NaN writes as an empty cell, and so does the exact value given as fill.
Both directions take options on the left: header, separator, quotechar, doublequote, escapechar, decimal, thousands, trim and fill. Reading also takes text_columns, numeric_columns and missing, and writing takes forcequotes and lineending. "forcequotes":2 quotes every field. CSV describes the options.
Errors: DOMAIN for invalid options, duplicate headers, and cells that CSV can’t hold: nonintegral rationals, complex numbers, functions or nested cells; LENGTH for unequal record widths or columns.
Each numeric column uses compact integer or float storage where possible:
text←"price,qty10.5,220.0,4"T←•csv textTT.qty+/¨T
["price":[10.5 20] "qty":[2 4]ₓ]
[2 4]ₓ
["price":30.5 "qty":6ₓ]
"f.csv" •nput •csv⁻¹ T writes CSV to a file. Unkeyed input writes the data without a header. Parsing the text restores the columns:
Separator, quote and escape must be distinct ASCII characters other than CR, LF or NUL. Fields support Unicode, doubled quotes and embedded newlines. Import accepts LF, CRLF and CR record endings. Export with escapechar quotes every field and doubles literal escape characters. With quoting disabled, export errors if a field requires quoting.
Numbers and missing cells
Inference examines a whole column, ignoring missing cells. Integer fields produce exact numbers. Decimal/scientific notation produces floats. A column containing other text stays text. Quoted numbers participate in inference too.
T←•csv"count,label2,0013,yes"T.countT.label
[2 3]ₓ
"001" "yes"
A column of integers uses integer storage when every value fits in 64 bits. Larger integers stay exact. A value with a decimal point or an exponent is approximate. A column’s numbers combine by the rule in Numeric input.
Missing numeric cells become NaN, written $n. A missing cell never makes a column float. An integer column with a gap stays exact, in integer storage. Missing text cells become "". Entirely missing columns are text unless forced numeric.
T←•csv"price,qty10.5,2,4"T.priceT.qty
10.5 $n
[2 4]ₓ
Configure extra missing markers and numeric fill explicitly.
text←"qtyNA4"["missing":"NA""fill":¯1ₓ] •csv text
["qty":[¯1 4]ₓ]
Export uses - for negative numbers, decimal/scientific float spelling and plain exact integers. Infinity writes as inf or -inf. Set fill to export a chosen numeric sentinel as an empty field. Nonintegral rationals, complex numbers, functions and nested nonstring cells give DOMAIN.
Empty input returns an empty unkeyed vector. Header-only input returns keyed empty columns. Empty header names are allowed. Duplicate header names give DOMAIN. Unequal record widths or column lengths give LENGTH. Invalid forced numeric fields report their row and column.