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,web,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.
portname: 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 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.

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>.

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: file (keyword), characters (keyword), string (keyword), character (keyword), integer (keyword), it (keyword), URL (keyword), CRLF (constant), write to file (command), close file (command), open file (command), seek (command), get (command), 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), function (control_st)
