Write Text File {R}←X ⎕NPUT Y

This function writes character data to a text file. See also Read Text File.

Y is either a simple character vector or scalar containing the name of the file to be written, or a 2-item vector whose first item is the file name and whose second is an integer scalar specifying flags for the operation.

If flags is 0 (the default value if omitted) the file will not be overwritten if it already exists and ⎕NPUT will signal an error. If flags is 1 the file will be overwritten. If flags is 2 the file will be appended to; i.e.

flags file does not exist file exists
0 data is written to new file error signalled, file is unchanged
1 data is written to new file file is overwritten
2 data is written to new file data is appended to file

The left-argument X is comprised of 1, 2 or 3 items which identify (content) (encoding) (newline) respectively.

content is either a vector of character vectors, each of which represents a line in the file to be written, or a simple character vector.

If specified, encoding is either:

If omitted, encoding defaults to UTF-8-NOBOM.

Note: If a non-empty file is appended to:

If specified, newline is numeric and is either or a scalar or vector from the column labelled Value in the newline characters section of the table Line separators:. Any other value causes DOMAIN ERROR. If newline is omitted it defaults to (13 10) on Windows and 10 on other platforms.

In all cases, newline is appended if required to a simple vector or to each vector in a vector of vectors.

If content contains anything other than a character vector or scalar (or these, nested) then a DOMAIN ERROR is signalled.

If both encoding and neline are omitted X specifies only content and may be a simple character vector or a vector of character vectors.

The shy result R is the number of bytes written to the file.

Examples:

      txt←'mene' 'mene' 'tekel' 'upharsin'

      ⎕←(⊂txt) ⎕NPUT 'writing.txt'
25
      ⊢(⊂'adding' '3' 'lines')⎕NPUT'writing.txt' 2
18
      LF←⎕UCS 10
      t←'adding',LF,'3',LF,'lines',LF
      ⊢t ⎕NPUT'writing.txt' 2
18                                         

NEOL Option

The NEOL variant option specifies how embedded line separators are treated.

0 embedded line separator characters are preserved as is
1 every embedded LF is replaced by newline
2 every embedded line separator character is replaced by newline

Embedded line-separator examples

      LF CR←⎕UCS 10 13
      t←'adding',LF,'3',CR,'lines',CR,LF
                  
      ⊢t ⎕NPUT'writing.txt' 2                             
17
      ⊢t(⎕NPUT⍠'NEOL' 0)'writing.txt' 2                   
16
      ⊢t(⎕NPUT⍠'NEOL' 2)'writing.txt' 2                   
18

t contains three lines each with different line endings: LF, CR and CRLF.

In the first example (NEOL is by default 1), only the LF is normalised so the written file contains lines ending with CRLF, CR and CRLF.

In the second example, none of the line endings are normalised so the written file contains lines ending with LF, CR and CRLF.

In the third example, all of the line endings are normalised so the written file contains lines ending with CRLF, CRLF and CRLF.