Standard Library/files

This script defines file utilities and is included in the J standard library. Definitions are loaded into the z locale.

read verbs take a right argument of a filename, optionally linked with one or two numbers (as for 1!:11):

 0 = start of read (may be negative)
 1 = length of read (default rest of file)

write verbs return number of characters written.

filenames may be open or boxed character or unicode strings

string verbs write out text delimited with the host OS delimiter, and read in text delimited by LF.

on error, the result is _1, e.g. for file not found/file read error/file write error

Definitions

F	fappend, fappends, fapplylines, fboxname, fcopynew, fdir, ferase, fexist, fgets, fmakex, fpathcreate, fpathname, fread, freadblock, freadr, freads, frename, freplace, fsize, fss, fssrplc, fputs, fstamp, ftype, fview, fwrite, fwritenew, fwrites

---

fboxname	v	fix and box filename
fgets	v	convert text read from file to J string
fmakex	v	make file executable
fpathcreate	v	create a folder path, returning success
fpathname	v	split file name into path;name
fstamp	v	returns file timestamp
fputs	v	convert text for file write as string
fview	v	view file (requires textview)
fwrite	v	write text to file
fwritenew	v	write text to file if changed
fwrites	v	write string to file

fappend (verb)

Append text to file.

The text is first ravelled. The file is created if necessary.

Returns number of characters written, or an error message.

Syntax:

text fappend filename

Example:

   'chatham' fappend 'newfile.txt'
7

fappends (verb)

Append string to file.

The text is first ravelled into a vector with each row terminated by the host delimiter.

The file is created if necessary. Returns number of characters written, or an error message.

fapplylines (adverb)

Apply verb to lines in file delimited by LF.

fcopynew (verb)

Copies files if changed.

Syntax:

tofile fcopynew fromfiles

returns: 0, size not changed
         1, size changed
        _1 failure

fdir (verb)

File directory.

Example:

fdir jpath '~system/main/s*.ijs'

ferase (verb)

Erases a file.

Returns 1 if successful, otherwise _1

fexist (verb)

Returns 1 if the file exists, otherwise 0.

fread (verb)

Read file.

y is filename {;start size}
optional x calls freads

length error if size is larger than the size of the file. (Not useful for reading from zero length pseudo-files.)

freadblock (verb)

Read block of lines from file.

Lines are terminated by LF.

Blocksize defaults to 1e6

y is filename;start position

returns: block;new start position

freadr (verb)

Read records from flat file.

y is filename {;record start, # of records}

Records are assumed of fixed length delimited by one (only) of CR, LF, or CRLF.

the result is a matrix of records.

freads (verb)

Read file as string.

y is filename {;start size}
x is optional (b and m same as fread):
   = b read as boxed vector
   = m read as matrix

frename (verb)

Renames file.

Syntax:

newname frename oldname

Returns 1 if rename successful.

freplace (verb)

Replace text in file.

Syntax:

dat freplace file;pos

fsize (verb)

Returns file size or _1 if error

fss (verb)

Search file for string, returning indices.

Syntax:

str fss file

fssrplc (verb)

File string search and replace.

Syntax:

(old;new) fssrplc file

ftype (verb)

Get file type, as:

0 = not exist
1 = file
2 = directory