Name: read from file

Type: command

Syntax: read from {file <pathName> | stdin} [at <start>] {until {<string> | end | EOF | empty} | for <amount> [<chunkType>]} [in <time>]

Summary:
Takes data from a <file> that has been opened with the <open file>
<command>, and places the data in the <it> <variable>.

Introduced: 1.0

OS: mac, windows, linux, ios, android

Platforms: desktop, server, mobile

Security: disk

Example:
read from file "Test" for 8 -- reads 8 characters

Example:
read from file "COM1:" at 20 until EOF

Example:
read from file (field "Datafile") at -100 for charsToRead

Example:
read from stdin for 1 line

Parameters:
pathName:
The pathName specifies the name and location of the file you want to
read from. It must be the same as the path you used with the open file
command.
>*Important:* The pathName is case-sensitive, even on platforms
where file names are not case-sensitive. It must be exactly the
same--including the case of characters--as the name you used with the
open file command. If you specify the name of a serial port on Mac OS or
Windows systems, LiveCode reads from the specified port. The names of
serial ports end in a colon (:).

start:
The start specifies the character or byte position in the file where you
want to begin reading. A positive number begins start characters after
the beginning of the file; a negative number begins start characters
before the end of the file.

string (string):
When LiveCode encounters the string in the file, it stops reading. If
the string is not encountered, the read from file command continues
reading until it reaches the end of the file.

amount:
A positive integer and specifies how much data to read.

chunkType:
One of chars, characters, words, items, lines, int1, uInt1, int2, uint2,
int4, or uint4. The read from file command reads amount of the specified
chunkType. If you don't specify a chunkType, amount characters are read
from the file.

time:
The time to wait for the read to be completed, in milliseconds, seconds,
or ticks.


It:
The data is placed in the <it> variable after reading. If you specified
a <binary file|binary data> <chunkType> (int1, uInt1, int2, uint2, int4,
or uint4), the data consists of a comma-separated list of numbers, one
for the numerical value of each chunk that was read. Otherwise, the data
is placed in the <it> <variable> as it appears in the <file>.

The result:
The file to read from must be opened first with the <open file>
<command>, and the mode the <file> was opened in must be either read or
update. If the file is not open or is open write-only, the <result>
<function> is set to "File is not open for read.". If the <read from
file> <command> encounters the end of the <file>, the <result>
<function> is set to "eof". If the command was successful and did not
encounter the end of the <file>, the result <function> is set to empty.

Description:
Use the <read from file> <command> to get data from a <file>.

>*Important:*  The <pathName> is <case-sensitive>, even on
> <platform|platforms> where file names are not <case-sensitive>. It
> must be exactly the same--including the case of characters--as the
> name you used with the <open file> <command>.

If you specify the name of a serial port on Mac OS or Windows systems,
LiveCode reads from the specified port. The names of serial ports end in
a colon (:).

The <start> specifies the <character> or <byte> position in the <file>
where you want to begin reading. A positive number begins <start>
<characters> after the beginning of the <file>; a <negative> number
begins <start> <characters> before the end of the <file>.

The <string> is any <expression> that <evaluate|evaluates> to a
<string>. When LiveCode encounters the <string> in the <file>, it stops
reading. If the <string> is not encountered, the <read from file>
<command> continues reading until it reaches the end of the <file>.

If you specify any of EOF, end, or empty, the read continues reading
until it reaches the end of the file. (If you're reading from a serial
port, you must use the form read from file <portname> until empty.)

The <amount> is a positive <integer> and specifies how much data to
read. 

The <chunkType> is one of chars, characters, words, items, lines, int1,
uInt1, int2, uint2, int4, or uint4. The <read from file> <command> reads
<amount> of the specified <chunkType>. If you don't specify a
<chunkType>, <amount> <characters> are read from the <file>.

The <time> is the time to wait for the read to be completed, in
<milliseconds>, seconds, or <ticks>.

If you don't specify a <start>, LiveCode begins at the position
determined by the <seek> <command>, or wherever the last 
<read from file> or <write to file> <command> to that <file> left off, 
or at the first <character>, if the <file> has not been accessed since 
being opened, or at the last <character>, if the <file> was opened in 
append mode. 

The until <string> form reads data until the specified string is
encountered. The until end, until EOF, and until empty forms are
synonyms, and read data up to the end of the file. You can read an
entire <file> by opening it and reading until the end:

    open file fileToRead
    read from file fileToRead until EOF
    close file fileToRead


The read from stdin form reads from the standard input (on Unix
systems). The standard input is always open, so you can read from it
without first opening it.

>*Tip:*   As an alternative to the <open file> and  <read from file>
> <command|commands>, you can also use the <URL> <keyword> with <get>
> and other <command|commands> to access the contents of a <file>.

References: write to file (command), close file (command),
open file (command), seek (command), get (command), CRLF (constant),
function (control structure), ticks (function), result (function),
milliseconds (function), platform (glossary), binary file (glossary),
variable (glossary), byte (glossary), case-sensitive (glossary),
keyword (glossary), negative (glossary), expression (glossary),
command (glossary), evaluate (glossary), file (keyword),
characters (keyword), string (keyword), character (keyword),
integer (keyword), it (keyword), URL (keyword)

