read-from-string

read-from-string Function

Syntax:

read-from-string string &optional eof-error-p eof-value

&key start end preserve-whitespace

→ object, position

Arguments and Values:

string—a string.

eof-error-p—a generalized boolean. The default is true.

eof-value—an object. The default is nil.

start, end—bounding index designators of string. The defaults for start and end are 0 and nil, respectively.

preserve-whitespace—a generalized boolean. The default is false.

object—an object (parsed by the Lisp reader ) or the eof-value.

position—an integer greater than or equal to zero, and less than or equal to one more than the length of the string.

Description:

Parses the printed representation of an object from the subsequence of string bounded by start and end, as if read had been called on an input stream containing those same characters.

If preserve-whitespace is true, the operation will preserve whitespace₂ as read-preserving-whitespace would do.

If an object is successfully parsed, the primary value, object, is the object that was parsed. If eof-error-p is false and if the end of the substring is reached, eof-value is returned.

The secondary value, position, is the index of the first character in the bounded string that was not read. The position may depend upon the value of preserve-whitespace. If the entire string was read, the position returned is either the length of the string or one greater than the length of the string.

Examples:

(read-from-string " 1 3 5" t nil :start 2) → 3, 5 
(read-from-string "(a b c)") → (A B C), 7 

Exceptional Situations:

If the end of the supplied substring occurs before an object can be read, an error is signaled if eof-error-p is true. An error is signaled if the end of the substring occurs in the middle of an incomplete object.

See Also:

read, read-preserving-whitespace

Notes:

The reason that position is allowed to be beyond the length of the string is to permit (but not require) the implementation to work by simulating the effect of a trailing delimiter at the end of the bounded string. When preserve-whitespace is true, the position might count the simulated delimiter.

Expanded Reference: read-from-string

Basic usage

read-from-string parses a Lisp object from a string and returns two values: the object read and the position in the string where reading stopped.

(read-from-string "(a b c)")
=> (A B C)
=> 7

(read-from-string "42 rest-of-string")
=> 42
=> 3

Using :start and :end to read a substring

The :start and :end keyword arguments select a substring to read from.

(read-from-string " 1 3 5" t nil :start 2)
=> 3
=> 5

(read-from-string "xxxHELLOxxx" t nil :start 3 :end 8)
=> HELLO
=> 8

Handling end-of-string

When the string contains no readable object (or is empty), the eof-error-p and eof-value arguments control the behavior.

(read-from-string "" nil :no-more)
=> :NO-MORE
=> 0

(read-from-string "   " nil :empty)
=> :EMPTY
=> 3

Reading multiple objects from a string

Use the returned position as the :start for the next call to read successive objects.

(let ((str "(a b) (c d) (e f)"))
  (multiple-value-bind (obj1 pos1) (read-from-string str)
    (multiple-value-bind (obj2 pos2) (read-from-string str t nil :start pos1)
      (multiple-value-bind (obj3 pos3) (read-from-string str t nil :start pos2)
        (list obj1 obj2 obj3)))))
=> ((A B) (C D) (E F))

Using :preserve-whitespace

When preserve-whitespace is true, the behavior is like read-preserving-whitespace -- trailing whitespace that terminates a token is not consumed. This can affect the returned position.

(read-from-string "foo bar")
=> FOO
=> 4

(read-from-string "foo bar" t nil :preserve-whitespace t)
=> FOO
=> 3