ReadItem

Read a single argument/name from the command line, a file/stream or a user-supplied buffer (V36)

ReadItem() reads text from either the current Input() source or the csource buffer parameter. The text read is considered an "item", or, in more modern terms, a "token". The input may contain more than one token and these tokens need to be separated by whitespace characters (' ' and '\t'). A token can take two different forms. It can either be a sequence of non-whitespace characters, or it can be text enclosed in double quote characters.

The following are valid tokens:

The following are invalid tokens:

The following text is equivalent and will be processed as two consecutive tokens; ReadItem() will first return a quoted token "foo bar" and the next use of ReadItem() will return an unquoted token "baz":

If both tokens are quoted, the following text is equivalent, too, i.e. two consecutive quoted tokens will be returned as "foo bar" and "baz":

The text read will be processed and stored as a NUL-terminated string referenced by the buffer parameter. For quoted text, the text will be stored without the enclosing double quote characters.

ReadItem() will stop reading further data if there is no more data, e.g. reading from Input() indicates that the end of the file or stream has been reached, or a ';' (semicolon), '\0' (NUL), or '\n' (line feed) character has been read.

If a token is enclosed in double quote characters, it can contain whitespace characters as well as ';' and double quote characters. In order to use double quote characters in a token enclosed in double quotes, the '*' (asterisk) character must be prepended to the double quote character, like so:

The '*' acts as an escape character and either removes the special meaning of the character which follows it, or replaces it with a control character:

ReadItem() may unread the last character read before it returns, depending on the circumstances. For example, if ReadItem() reads a '\n' (line feed) or ';' (semicolon) character, it will unread this character before it returns. The client can then check which character made ReadItem() stop and return.

buffer

String buffer to store the item in. If ReadItem() returns ITEM_EQUAL, ITEM_UNQUOTED or ITEM_QUOTED, the item string will always be NUL-terminated.

size

Total size of the buffer, including the space available for storing the item and a NUL byte. The total size must be > 1.

csource

Pointer to "struct CSource" input or NULL; if you use NULL, ReadItem() will call FGetC(Input()) to read the next character from the source.

If the csource CS_Buffer member is NULL, ReadItem() will fall back onto calling FGetC(Input()), as if the csource pointer had been NULL all along.

If the csource parameter is not NULL, the "struct CSource" must be correctly initialized (see the "Notes" section below).

ITEM_UNQUOTED

The item was read successfully. It was not surrounded by double quotes and does not contain whitespace, '\n', '\x1B', ';' or '=' characters. The contents of the buffer will be NUL-terminated.

ITEM_QUOTED

The item was read successfully. It was surrounded by double quotes and may contain whitespace or '\n', '\x1B', '*', '"', ';' and '=' characters. The contents of the buffer will be NUL-terminated.

ITEM_EQUAL

A single '=' character was found, typically at the beginning or the end of the input and/or surrounded by whitespace. The buffer will be empty and NUL-terminated. The single '=' character can be part of a key/value expression such as this:

foo=bar foo = bar

ReadItem() will return the tokens "foo" (ITEM_QUOTED), followed by an empty string (ITEM_EQUAL), followed by the token "bar" (ITEM_QUOTED).

ITEM_ERROR

The following conditions may produce this result:

• There is not enough room in the buffer to store another character, plus a NUL terminator to follow it.
  
  
• When reading a quoted item, no more data could be read, or a '\n' (line feed) character was found. Hence, the expected closing double quote character is missing.
  
  
• When reading a quoted item, no more data could be read after a '*' character had been found. Hence, the character to follow the '*' is missing.
  
  

ITEM_NOTHING

No further text could be read and turned into a token. ReadItem() may have encountered a ';' and/or '\n' (line feed) character.

ReadItem() is not generally useful outside its primary field of use, which is the shell (CLI) and a handful of shell commands such as "Execute", "Skip" or "Lab". ReadItem() is not a simpler alternative to ReadArgs(). Use ReadArgs() if you can, which requires more setup effort, but it spares you from having to deal with the handful of conditions under which ReadItem() will unread the last character read.

Initializing the CSource data is straightforward. You need to fill in a pointer to the string to be processed, the length of the string and set the current string read position to 0, like so:

If you use the CSource data parameter, you should check after each ReadItem() call if the buffer has been completely read. This will be the case if cs.CS_CurChr >= cs.CS_Length, i.e. subsequent calls to ReadItem() will return no more tokens.

If you let ReadItem() make use of Input(), it will read one character at a time through FGetC(Input()) until it reaches the end of the file or stream.

When it finds a character that it makes it stop, ReadItem() will unread that character. For example, a '\n' character indicates that the entire text for this line has been read. This "stop character" will then be unread, for you to look at it, or for the next ReadItem() call to make use of it. If any of the following result values are returned by ReadItem(), the stop character may have been unread:

Caution:

The ReadItem() behaviour with regard to unreading the last character read is inconsistent.

If ReadItem() returned ITEM_NOTHING, you should try to read the next character because it might just be a '\n' (line feed) which the next call to ReadItem() will read, unread and then return ITEM_NOTHING again, leading to an endless loop. If you found a '\n', discard it. If you found a different character, unread it and call ReadItem() again, if necessary. For a file/stream, unreading the last character involves calling UnGetC(file, -1).

If you make use of the CSource data parameter, ReadItem() will "unread" the last character read by decrementing the CSource.CS_CurChr value.

It is, generally, a good idea to stop calling ReadItem() if it returned ITEM_ERROR. Before you can call ReadItem() again, proceed by reading every single remaining character until you find a '\n' (line feed) character, discarding the remainder of the line. Stop if you reach the end of the buffer or file/stream.

Compare the return value of the ReadItem() function against ITEM_ERROR first, rather than assuming that a negative value indicates an error condition. ITEM_EQUAL is a negative value, too, but does not indicate an error.

Keep in mind that ReadItem() is foremost a helper function which is used by the shell to read input entered by the user, as well as instructions from a script file. This is why it stops reading from a line when it finds a ';' (semicolon) character, which for the shell indicates that the remainder of the line contains a comment which should be ignored.

ReadItem() expects its input to be in a certain format, which so happens to match the general syntax of the AmigaDOS shell and its batch script files. It is not a general token processing function. It actually constitutes the fundamental behaviour of the shell.

The line terminator is the '\n' (line feed) character. A '\r' (carriage return) character preceding the line feed character will be retained as is. If you expect to process lines terminated by "\r\n", you may want to remove the '\r' before you submit the line to the ReadItem() function.

If the caller is a Task and either the csource parameter is NULL, or the csource parameter CS_Buffer member is NULL, then ReadItem() will call FGetC(Input()) and may subsequently crash.

ReadArgs(), FindArg(), UnGetC(), FGetC(), Input(), <dos/dos.h>, <dos/rdargs.h>, FreeArgs()