Read from file

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

Built-in Message handler

Syntax:

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

Examples:

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

read from file "COM1:" at 20 until EOF

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

read from stdin for 1 line

Use the read from file command to get data from a file.

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 (:).

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

commands, you can also use the URL keyword with get and other commands to access the contents of a file.

Parameters:

• pathName: The pathName specifies the name and location of the file you want toread from. It must be the same as the path you used with the open filecommand.]]*Important:* The pathName is case-sensitive, even on platformswhere file names are not case-sensitive. It must be exactly thesame--including the case of characters--as the name you used with theopen file command. If you specify the name of a serial port on Mac OS orWindows systems, LiveCode reads from the specified port. The names ofserial ports end in a colon (:).
• start: The start specifies the character or byte position in the file where youwant to begin reading. A positive number begins start characters afterthe beginning of the file; a negative number begins start charactersbefore the end of the file.
• string (string): When LiveCode encounters the string in the file, it stops reading. Ifthe string is not encountered, the read from file command continuesreading 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 specifiedchunkType. If you don't specify a chunkType, amount characters are readfrom 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 readinguntil it reaches the end of the file. (If you're reading from a serialport, you must use the form read from file portname until empty.)
• It: The data is placed in the it variable after reading. If you specifieda binary data chunkType (int1, uInt1, int2, uint2, int4,or uint4), the data consists of a comma-separated list of numbers, onefor the numerical value of each chunk that was read. Otherwise, the datais 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 filecommand, and the mode the file was opened in must be either read orupdate. If the file is not open or is open write-only, the resultfunction is set to "File is not open for read.". If the read fromfile command encounters the end of the file, the resultfunction is set to "eof". If the command was successful and did notencounter the end of the file, the result function is set to empty.

See also: open file (command),seek (command),get (command),CRLF (constant),function (control structure),ticks (function),result (function),milliseconds (function),