Eclector

https://s-expressionists.github.io/Eclector/
Admin
Eclector is a portable Common Lisp reader implementation featuring detailed error reporting, syntax...
Tokens:36,846
Snippets:297
Trust Score:8.3
Update:8 months ago
Show doc for...
Tokens:
Raw
### Package Prefix Syntax Extension Example

Source: https://s-expressionists.github.io/Eclector/eclector

Demonstrates the extended package prefix syntax, allowing an expression to be prefixed with a package designator. This causes the expression to be read with the designated package as the current package.

```common-lisp
;; Input:
;; my-package::(a b)

;; Read as:
;; (my-package::a my-package::b)
```

--------------------------------

### Structure Instance Creation with Side Effects (Common Lisp)

Source: https://s-expressionists.github.io/Eclector/eclector

Demonstrates how defining structure slot initforms can lead to side effects when creating structure instances using the #S reader macro. The example shows a counter being incremented each time a new instance of the 'foo' structure is created.

```common-lisp
(defvar *counter* 0)
(defstruct foo (bar (incf *counter*)))
#S(foo)
*counter* ⇒ 1
#S(foo)
*counter* ⇒ 2
```

--------------------------------

### fixup-graph [eclector.reader]

Source: https://s-expressionists.github.io/Eclector/eclector

This generic function is called after an object graph is constructed to fix circular references before the object is returned. It handles the initial setup for the fixup process.

```APIDOC
## Generic Function: fixup-graph [eclector.reader]

### Description
Potentially called after the reader has constructed an object graph reachable from `root-labeled-object` to fix circular references before the object is returned. `object-key` is a function that accepts a labeled object and returns its object.

### Method
Generic Function

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "No request body for this function."
}
```

### Response
#### Success Response (200)
This function is called for side effects; its return value is ignored.

#### Response Example
```json
{
  "example": "No specific return value documented."
}
```

### Notes
- If `root-labeled-object` has a parent, it should not be fixed up immediately.
- If `root-labeled-object` has no parent but has children, it should be fixed up immediately.
- If `root-labeled-object` has no parent and is in state `:final/circular`, it should be fixed up immediately.
- The default method creates a hash table for tracking processed objects and calls `eclector.reader:fixup`.
```

--------------------------------

### Readtable Initialization

Source: https://s-expressionists.github.io/Eclector/eclector

This section details functions for initializing standard readtable configurations.

```APIDOC
## Readtable Initialization

### Description
Functions to set up standard dispatch macro characters, macro characters, syntax types, and macros for readtables.

### Functions

- `set-standard-dispatch-macro-characters [eclector.reader]`
- `set-standard-macro-characters [eclector.reader]`
- `set-standard-syntax-and-macros [eclector.reader]`
- `set-standard-syntax-types [eclector.reader]`
```

--------------------------------

### Reading S-expressions from a String

Source: https://s-expressionists.github.io/Eclector/eclector

The `read-from-string` function from `eclector.concrete-syntax-tree` parses an S-expression from a given string. It offers options for specifying the start and end of the string to parse and whether to preserve whitespace, mirroring `cl:read-from-string` but with CST output.

```common-lisp
 (require :eclector.concrete-syntax-tree)

 (let ((cst (eclector.concrete-syntax-tree:read-from-string "(a b c)" :preserve-whitespace t))) 
   (print cst))
```

--------------------------------

### Readtable Initialization API

Source: https://s-expressionists.github.io/Eclector/eclector

Functions for setting up standard syntax types and macro character associations for readtables.

```APIDOC
## Function: set-standard-syntax-types [eclector.reader] readtable

### Description
This function sets the standard syntax types in readtable.

### Method
Function

### Endpoint
N/A (Internal function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(set-standard-syntax-types readtable)
```

### Response
#### Success Response (200)
Sets the standard syntax types in the provided readtable.

#### Response Example
None

## Function: set-standard-macro-characters [eclector.reader] readtable

### Description
This function sets the standard macro characters in readtable.

### Method
Function

### Endpoint
N/A (Internal function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(set-standard-macro-characters readtable)
```

### Response
#### Success Response (200)
Sets the standard macro characters in the provided readtable.

#### Response Example
None

## Function: set-standard-dispatch-macro-characters [eclector.reader] readtable

### Description
This function sets the standard dispatch macro characters, that is sharpsign and its sub-characters, in readtable.

### Method
Function

### Endpoint
N/A (Internal function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(set-standard-dispatch-macro-characters readtable)
```

### Response
#### Success Response (200)
Sets the standard dispatch macro characters in the provided readtable.

#### Response Example
None

## Function: set-standard-syntax-and-macros [eclector.reader] readtable

### Description
This function sets the standard syntax types and macro characters in readtable by calling the above three functions.

### Method
Function

### Endpoint
N/A (Internal function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(set-standard-syntax-and-macros readtable)
```

### Response
#### Success Response (200)
Sets the standard syntax types and macro characters in the provided readtable.

#### Response Example
None
```

--------------------------------

### Get Labeled Object State

Source: https://s-expressionists.github.io/Eclector/eclector

Determines the state of a given object. Returns nil if the object is not labeled. If labeled, it returns two values: a keyword indicating the state (:defined, :circular, :final, :final/circular) and the final object if the state is :final or :final/circular, otherwise nil. This function is crucial for distinguishing labeled objects and managing graph fixups.

```Common Lisp
eclector.reader:labeled-object-state
;; Returns nil for non-labeled objects.
;; Returns (:defined | :circular | :final | :final/circular) and final-object (or nil).
```

--------------------------------

### Concrete Syntax Tree (CST) Reader Functions

Source: https://s-expressionists.github.io/Eclector/eclector

Documentation for the core CST reader functions: `read`, `read-preserving-whitespace`, and `read-from-string`. These functions are largely compatible with Common Lisp's equivalents but return CST instances.

```APIDOC
## Function: read

### Description
This function is the main entry point for the CST reader. It is mostly compatible with the standard Common Lisp function `cl:read`. The differences are: the return value, unless eof-value is returned, is an instance of a subclass of `concrete-syntax-tree:cst`; and the function does not accept a recursive parameter since it sets up a dynamic environment in which calls to `eclector.reader:read` behave suitably.

### Parameters
#### Arguments
- **input-stream** (`&optional`, defaults to `*standard-input*`) - The input stream to read from.
- **eof-error-p** (`&optional`, defaults to `t`) - Whether to signal an error on end-of-file.
- **eof-value** (`&optional`, defaults to `nil`) - The value to return on end-of-file if `eof-error-p` is false.

### Return Value
An instance of a subclass of `concrete-syntax-tree:cst`, or `eof-value` if end-of-file is reached.

## Function: read-preserving-whitespace

### Description
This function is similar to the standard Common Lisp function `cl:read-preserving-whitespace`. The differences are the same as described above for `eclector.concrete-syntax-tree:read` compared to `cl:read`.

### Parameters
#### Arguments
- **input-stream** (`&optional`, defaults to `*standard-input*`) - The input stream to read from.
- **eof-error-p** (`&optional`, defaults to `t`) - Whether to signal an error on end-of-file.
- **eof-value** (`&optional`, defaults to `nil`) - The value to return on end-of-file if `eof-error-p` is false.

### Return Value
An instance of a subclass of `concrete-syntax-tree:cst`, or `eof-value` if end-of-file is reached.

## Function: read-from-string

### Description
This function is similar to the standard Common Lisp function `cl:read-from-string`. The differences are the same as described above for `eclector.concrete-syntax-tree:read` compared to `cl:read`.

### Parameters
#### Arguments
- **string** - The string to read from.
- **eof-error-p** (`&optional`, defaults to `t`) - Whether to signal an error on end-of-file.
- **eof-value** (`&optional`, defaults to `nil`) - The value to return on end-of-file if `eof-error-p` is false.
- **start** (`&key`, defaults to `0`) - The starting index in the string.
- **end** (`&key`, defaults to `nil`) - The ending index in the string.
- **preserve-whitespace** (`&key`, defaults to `nil`) - Whether to preserve whitespace.

### Return Value
An instance of a subclass of `concrete-syntax-tree:cst`, or `eof-value` if end-of-file is reached.
```

--------------------------------

### Define Custom Reader Macro for Circular References in Common Lisp

Source: https://s-expressionists.github.io/Eclector/eclector

This Common Lisp code defines a custom reader macro '#' followed by '_' that recursively calls `eclector.reader:read`. It demonstrates a potential issue where the referenced object might not be defined yet, leading to undefined behavior. The example shows how to create a custom readtable and use it to read a string containing a circular reference.

```common-lisp
(defun custom-macro-readtable ()
  (let ((readtable (eclector.readtable:copy-readtable
                    eclector.reader:*readtable*)))
    (eclector.readtable:set-dispatch-macro-character
     readtable ## #_ (lambda (stream char sub-char)
                         (declare (ignore char sub-char))
                         (second (eclector.reader:read stream t nil t))))
    readtable))

(let ((eclector.reader:*readtable* (custom-macro-readtable)))
  (eclector.reader:read-from-string "#1=(:a #_#1#)"))
```

--------------------------------

### Efficient Reader Macros (Lisp)

Source: https://s-expressionists.github.io/Eclector/eclector

The default `eclector.reader:read-token` method and the functions `eclector.reader::sharpsign-colon` and `eclector.reader::sharpsign-backslash` have been made more efficient and less redundant. This optimization reduces repeated code and improves performance.

```common-lisp
The default `eclector.reader:read-token` method and the functions `eclector.reader::sharpsign-colon` and `eclector.reader::sharpsign-backslash` are now more efficient as well as less redundant in terms of repeated code.
```

--------------------------------

### Reader State Protocol (Lisp)

Source: https://s-expressionists.github.io/Eclector/eclector

Introduces a new protocol for querying and binding behavior-changing aspects of the reader's state, such as the current package, readtable, and read base. This allows for more flexible control over the reader's behavior beyond traditional Common Lisp variable bindings.

```common-lisp
; Eclector provides a new protocol for querying and binding behavior-changing aspects
;; of the current state of the reader such as the current package, the current readtable
;; and the current read base (See Reader state protocol).
;;
;; Clients can use this protocol to control the reader state in other ways than binding
;; the Common Lisp variables, for example by storing the values of reader state aspects
;; in context objects.
;;
;; Furthermore, implementations which use Eclector as the Common Lisp reader can use
;; this protocol to tie the `cl:*readtable*` aspect to the `cl:*readtable*` variable
;; instead of the `eclector.reader:*readtable*` variable.
;;
;; The new protocol subsumes the purpose of the generic function `eclector.reader:call-with-current-package`
;; which is deprecated as of this Eclector version.
```

--------------------------------

### Improved Concrete Syntax Tree for `(0 . 0)`

Source: https://s-expressionists.github.io/Eclector/eclector

The `concrete-syntax-tree` module now generates a more accurate tree structure for inputs like `(0 . 0)`. Previously, the CST had the same atom object for `first` and `rest`. Now, `first` points to the CST for the first `0`, and `rest` points to the CST for the second `0`.

```common-lisp
;; Input: (0 . 0)
;; Previous CST structure:
;; (cons-cst :first (atom-cst "0") :rest (atom-cst "0")) - where both atom-cst are the same object.

;; New CST structure:
;; (cons-cst :first (atom-cst "0") :rest (atom-cst "0")) - where atom-cst objects are distinct.
```

--------------------------------

### Concrete Syntax Tree (CST) Fixup Processing (Lisp)

Source: https://s-expressionists.github.io/Eclector/eclector

Demonstrates how fixup processing is now performed in parse result objects, ensuring that CST objects correctly represent relationships, such as self-references. This change improves the integrity of the concrete syntax tree representation.

```common-lisp
; Before this change, something like
;; (eclector.concrete-syntax-tree:read-from-string "#1=(#1#)")
;;
;; produced a CST object, say `cst`, which failed to satisfy
;;
;; (eq (cst:first cst)       cst)
;; (eq (cst:raw (first cst)) (cst:raw cst))
;;
;; The properties now hold.
```

--------------------------------

### Common Lisp Reader Compatible Interface

Source: https://s-expressionists.github.io/Eclector/eclector

Provides functions that replicate the interface of the standard Common Lisp reader, allowing for seamless integration and familiar usage patterns. These functions can have their behavior customized via the `eclector.base:*client*` variable.

```APIDOC
## Common Lisp Reader Compatible Interface

### Description
These functions are compatible with their standard Common Lisp counterparts but reside in the `eclector.reader` package. Their behavior can be influenced by the `eclector.base:*client*` variable.

### Method
GET

### Endpoint
`/`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **output** (any) - The result of the read operation.

#### Response Example
```json
{
  "output": "(some s-expression)"
}
```

---

## read [eclector.reader]

### Description
Reads an S-expression from an input stream. Compatible with `cl:read`.

### Method
GET

### Endpoint
`/read`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **input-stream** (stream) - Optional. The input stream to read from. Defaults to `*standard-input*`.
- **eof-error-p** (boolean) - Optional. Whether to signal an error on EOF. Defaults to `t`.
- **eof-value** (any) - Optional. The value to return on EOF if `eof-error-p` is false. Defaults to `nil`.
- **recursive-p** (boolean) - Optional. Indicates if this is a recursive call. Defaults to `nil`.

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **result** (any) - The S-expression read from the stream.

#### Response Example
```json
{
  "result": "(a b c)"
}
```

---

## read-preserving-whitespace [eclector.reader]

### Description
Reads an S-expression from an input stream, preserving whitespace. Compatible with `cl:read-preserving-whitespace`.

### Method
GET

### Endpoint
`/read-preserving-whitespace`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **input-stream** (stream) - Optional. The input stream to read from. Defaults to `*standard-input*`.
- **eof-error-p** (boolean) - Optional. Whether to signal an error on EOF. Defaults to `t`.
- **eof-value** (any) - Optional. The value to return on EOF if `eof-error-p` is false. Defaults to `nil`.
- **recursive-p** (boolean) - Optional. Indicates if this is a recursive call. Defaults to `nil`.

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **result** (any) - The S-expression read from the stream.

#### Response Example
```json
{
  "result": "(a b c)"
}
```

---

## read-from-string [eclector.reader]

### Description
Reads an S-expression from a string. Compatible with `cl:read-from-string`.

### Method
GET

### Endpoint
`/read-from-string`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **string** (string) - The string to read from.
- **eof-error-p** (boolean) - Optional. Whether to signal an error on EOF. Defaults to `t`.
- **eof-value** (any) - Optional. The value to return on EOF if `eof-error-p` is false. Defaults to `nil`.
- **start** (integer) - Optional. The starting index in the string. Defaults to `0`.
- **end** (integer) - Optional. The ending index in the string. Defaults to `nil`.
- **preserve-whitespace** (boolean) - Optional. Whether to preserve whitespace. Defaults to `nil`.

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **result** (any) - The S-expression read from the string.

#### Response Example
```json
{
  "result": "(a b c)"
}
```

---

## read-delimited-list [eclector.reader]

### Description
Reads a list of S-expressions from an input stream, delimited by a character. Compatible with `cl:read-delimited-list`.

### Method
GET

### Endpoint
`/read-delimited-list`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **char** (character) - The delimiter character.
- **input-stream** (stream) - Optional. The input stream to read from. Defaults to `*standard-input*`.
- **recursive-p** (boolean) - Optional. Indicates if this is a recursive call. Defaults to `nil`.

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **result** (list) - The list of S-expressions read from the stream.

#### Response Example
```json
{
  "result": [
    "(a b)",
    "(c d)"
  ]
}
```
```

--------------------------------

### Reading S-expressions with eclector.concrete-syntax-tree:read

Source: https://s-expressionists.github.io/Eclector/eclector

The `read` function from `eclector.concrete-syntax-tree` is the primary entry point for parsing S-expressions into a concrete syntax tree (CST). It is largely compatible with `cl:read` but returns CST objects instead of arbitrary read objects.

```common-lisp
 (require :eclector.concrete-syntax-tree)

 (let ((cst (eclector.concrete-syntax-tree:read))) 
   (print cst))
```

--------------------------------

### Handling Circular Objects in Hash Tables (Lisp)

Source: https://s-expressionists.github.io/Eclector/eclector

Fixes issues in the `eclector.reader:fixup` method for hash tables where keys were not checked for circular structures and circular structures in values were not fixed up. This ensures proper handling of complex object graphs.

```common-lisp
; Before this change, cases like
;; #1=(1 #1# #2=(2 #2# ... #100=(100 #100#)))
;;
;; or 
;; #1=(1 #2=(2 ... #2#) ... #1#)
;;
;; led to unnecessary and/or repeated traversals during fixup processing.
;; Fixup processing is now performed in parse result objects.
```

--------------------------------

### call-with-label-tracking

Source: https://s-expressionists.github.io/Eclector/eclector

Establishes a context for tracking labeled object definitions ('#=') and references ('##') around a given thunk. This is crucial for managing the state of labeled objects during parsing.

```APIDOC
## CALL-WITH-LABEL-TRACKING [eclector.reader]

### Description
This generic function is called by the default method on `eclector.reader:call-as-top-level-read` to establish a context for tracking `#=` label definitions and `##` label references around a call to `thunk`. The default method on this generic function establishes a context in which the default `#=` and `##` reader macro functions can make the appropriate calls to `eclector.reader:note-labeled-object`, `eclector.reader:forget-labeled-object`, and `eclector.reader:find-labeled-object`.

### Method
GENERIC FUNCTION

### Endpoint
N/A (Internal function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```lisp
(eclector.reader:call-with-label-tracking
  (lambda () (read)))
```

### Response
#### Success Response (200)
Returns the result of the `thunk`.

#### Response Example
```
<result of thunk>
```
```

--------------------------------

### Eclector Syntax Interpretation Options

Source: https://s-expressionists.github.io/Eclector/eclector

Demonstrates how Eclector provides both relaxed and strict syntax interpretations for certain reader macros, such as '#c' and '#'. The strict versions are available for custom readtable configurations.

```lisp
;; Default relaxed syntax for sharpsign-c
; eclector.reader::sharpsign-c

;; Strict version available separately
eclector.reader:strict-sharpsign-c

;; Default relaxed syntax for sharpsign-single-quote
; eclector.reader::sharpsign-single-quote

;; Strict version available separately
eclector.reader:strict-sharpsign-single-quote
```

--------------------------------

### Basic Features

Source: https://s-expressionists.github.io/Eclector/eclector

This section covers fundamental features and utilities in Eclector.

```APIDOC
## Basic Features

### Description
Core utilities and features used across the Eclector library.

### Variables

- `*client* [eclector.base]`

### Functions

- `make-source-range [eclector.base]`
- `position-offset [eclector.base]`
- `range-length [eclector.base]`
- `source-position [eclector.base]`
- `stream-position [eclector.base]`
- `stream-position-condition [eclector.base]`
```

--------------------------------

### Make Labeled Object Representation

Source: https://s-expressionists.github.io/Eclector/eclector

Creates and returns a representation of a labeled object. It can optionally take a parent labeled object for deferred fixup processing. The default method returns an object of an unspecified type, and clients should interact with it via other generic functions.

```Common Lisp
eclector.reader:make-labeled-object
;; Default method returns an object of unspecified type.
```

--------------------------------

### Parse Result Client and Generic Functions

Source: https://s-expressionists.github.io/Eclector/eclector

Details on the `parse-result-client` class and the generic functions `make-expression-result` and `make-skipped-input-result` used for constructing custom parse results.

```APIDOC
## Class: parse-result-client

### Description
This class should generally be used as a superclass for client classes using this package.

## Generic Function: make-expression-result

### Description
This generic function is called in order to construct a parse result object. The value of the result parameter is the raw object read. The value of the children parameter is a list of already constructed parse result objects representing objects read by recursive `read` calls. The value of the source parameter is a source range, as returned by `eclector.base:make-source-range` and `eclector.base:source-position` delimiting the range of characters from which result has been read.

This generic function does not have a default method since the purpose of the package is the construction of _custom_ parse results. Thus, a client must define a method on this generic function.

### Parameters
#### Arguments
- **client** - The client class instance.
- **result** - The raw object read.
- **children** - A list of already constructed parse result objects.
- **source** - A source range delimiting the read characters.

## Generic Function: make-skipped-input-result

### Description
This generic function is called after the reader skipped over a range of characters in stream. It returns either `nil` if the skipped input should not be represented or a client-specific representation of the skipped input. The value of the children parameter is a list of already constructed parse result objects which represent object read by recursive `read` calls. The value of the source parameter designates the skipped range using a source range representation.

Reasons for skipping input include comments, the `#+` and `#-` reader macros and `*read-suppress*`. The aforementioned reasons are reflected by the value of the reason parameter as follows:
Input| Value of the reason parameter  
---|---
Comment starting with `;`| `(:line-comment . 1)`  
Comment starting with `;;`| `(:line-comment . 2)`  
Comment starting with _n_ `;`| `(:line-comment . _n_)`  
Comment delimited by `#|` `|#`| `:block-comment`  
`#+_false-expression_`| `(:sharpsign-plus . _false-expression_)`  
`#-_true-expression_`| `(:sharpsign-minus . _true-expression_)`  
`*read-suppress*` is true| `*read-suppress*`  
A reader macro returns no values| `:reader-macro`  

The default method returns `nil`, that is the skipped input is not represented as a parse result.

### Parameters
#### Arguments
- **client** - The client class instance.
- **stream** - The input stream.
- **reason** - The reason for skipping input.
- **children** - A list of already constructed parse result objects.
- **source** - A source range designating the skipped range.
```

--------------------------------

### Concrete Syntax Tree for Labeled Objects

Source: https://s-expressionists.github.io/Eclector/eclector

For inputs like `(#1=0 . #1#)`, the `concrete-syntax-tree` module continues to produce a single `concrete-syntax-tree:atom-cst` object in both the `concrete-syntax-tree:first` and `concrete-syntax-tree:rest` slots of the outer `concrete-syntax-tree:cons-cst` object, correctly representing the shared reference.

```common-lisp
;; Input: (#1=0 . #1#)
;; CST structure:
;; (cons-cst :first (atom-cst "0") :rest (atom-cst "0")) - where both atom-cst objects refer to the same labeled object.
```

--------------------------------

### Handling Skipped Input with make-skipped-input-result

Source: https://s-expressionists.github.io/Eclector/eclector

The `make-skipped-input-result` generic function handles cases where the reader skips characters in the input stream. It can return a client-specific representation of the skipped input or `nil`. The `reason` parameter indicates why the input was skipped, and `children` and `source` provide context.

```common-lisp
 (defmethod make-skipped-input-result ((client my-client) stream reason children source)
   (declare (ignore stream children))
   (case reason
     (:block-comment (format nil "Skipped block comment: ~a" source))
     ((:reader-macro) (format nil "Skipped input due to reader macro at ~a" source))
     (t nil)))
```

--------------------------------

### Call with Reader State Value (eclector.reader)

Source: https://s-expressionists.github.io/Eclector/eclector

Calls a thunk with a specific reader state aspect bound to a given value. For the `cl:*package*` aspect, string designators are coerced to package objects.

```common-lisp
(eclector.reader:call-with-state-value client thunk aspect value)
```

--------------------------------

### Customizing Labeled Object Replacement with Generic Functions

Source: https://s-expressionists.github.io/Eclector/eclector

Introduces the `eclector.reader:new-value-for-fixup` generic function, which allows clients to define custom replacement logic for labeled object markers. This is primarily useful when processing parse results, as ordinary object processing has limited flexibility.

```common-lisp
 (defgeneric eclector.reader:new-value-for-fixup (labeled-object state) "Compute the replacement value for a labeled object marker.")

 (defmethod eclector.reader:new-value-for-fixup ((labeled-object eclector.parse-result:definition) state)
   ;; Custom logic for definitions
   (let ((value (eclector.reader:labeled-object-state-value state)))
     (declare (ignore value))
     ;; ... custom replacement logic ...
     labeled-object))

 (defmethod eclector.reader:new-value-for-fixup ((labeled-object eclector.parse-result:reference) state)
   ;; Custom logic for references
   (let ((value (eclector.reader:labeled-object-state-value state)))
     (declare (ignore value))
     ;; ... custom replacement logic ...
     labeled-object))
```

--------------------------------

### Constructing Labeled Object Parse Results

Source: https://s-expressionists.github.io/Eclector/eclector

The protocol for constructing parse results representing labeled objects has been updated. Clients must now specialize `eclector.parse-result:make-expression-result` to `eclector.parse-result:definition` and `eclector.parse-result:reference` classes for the `result` parameter, receiving the labeled object in `result` and child parse results in `children`.

```common-lisp
;; Old mechanism (undocumented):
;; (defmethod eclector.parse-result:make-expression-result :before ((result (eql eclector.parse-result:**definition**)) (children list))
;;   ...)

;; New mechanism:
(defmethod eclector.parse-result:make-expression-result ((result eclector.parse-result:definition) (children list))
  ;; 'result' now contains the labeled object
  ;; 'children' contains child parse results
  ;; ... construct and return the parse result ...
  (make-instance 'eclector.parse-result:definition-result :object result :children children))
```

--------------------------------

### Common Lisp Reader Compatible Interface

Source: https://s-expressionists.github.io/Eclector/eclector

This section provides functions that offer a Common Lisp reader compatible interface.

```APIDOC
## Common Lisp Reader Compatible Interface

### Description
Provides an interface that mimics the behavior of the standard Common Lisp reader.

### Functions

- `read [eclector.reader]`
- `read-delimited-list [eclector.reader]`
- `read-from-string [eclector.reader]`
- `read-preserving-whitespace [eclector.reader]`
```

--------------------------------

### Read-time Evaluation

Source: https://s-expressionists.github.io/Eclector/eclector

Handles read-time evaluation of expressions, called by the default #. reader macro.

```APIDOC
## Generic Function: read-eval [eclector.reader]

### Description
This generic function is called by the default `#.` reader macro function to perform read-time evaluation. The `expression` is evaluated, potentially influenced by the `client`. The function must return the result of evaluating `expression` or signal an error.

### Method
Generic Function

### Endpoint
N/A (Internal function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```lisp
(eclector.reader:read-eval client expression)
```

### Response
#### Success Response
- **result** (any) - The result of evaluating the expression.

#### Response Example
```lisp
;; Example depends on the evaluated expression
42
```

### Error Handling
Signals an error if the expression cannot be evaluated.
```

--------------------------------

### Control Quasiquotation State (eclector.reader)

Source: https://s-expressionists.github.io/Eclector/eclector

A macro to control whether backquote and unquote syntax are allowed within a given context during read operations. It allows specifying which syntax to forbid or to keep unchanged.

```common-lisp
(eclector.reader:with-quasiquotation-state client context quasiquote-forbidden-p unquote-forbidden-p &body body)
```

--------------------------------

### Labeled Objects and References

Source: https://s-expressionists.github.io/Eclector/eclector

This section covers features related to handling labeled objects and references within Eclector.

```APIDOC
## Labeled Objects and References

### Description
Manages the creation, tracking, and resolution of labeled objects and references.

### Functions

- `call-with-label-tracking [eclector.reader]`
- `finalize-labeled-object [eclector.reader]`
- `find-labeled-object [eclector.reader]`
- `fixup [eclector.reader]`
- `fixup-graph [eclector.reader]`
- `fixup-graph-p [eclector.reader]`
- `forget-labeled-object [eclector.reader]`
- `labeled-object-state [eclector.reader]`
- `make-labeled-object [eclector.reader]`
- `new-value-for-fixup [eclector.reader]`
- `note-labeled-object [eclector.reader]`
- `reference-labeled-object [eclector.reader]`
```

--------------------------------

### read-common

Source: https://s-expressionists.github.io/Eclector/eclector

Called by `eclector.reader:read` to handle the common reading logic after initial parameter processing. It takes the client and input stream, along with EOF parameters, and returns the read object.

```APIDOC
## Generic Function: read-common [eclector.reader]

### Description
This generic function is called by `eclector.reader:read`, passing it the value of the variable `eclector.base:*client*` and the corresponding parameters. By default, this generic function returns the objects as its sole value.

> **Note:** This generic function may return more values in addition to the one described above. Clients may use this feature to communicate additional information between methods (see Parse result construction features). Client defined methods on this generic function should accept such additional values when calling a next method or `read-maybe-nothing` and themselves return the additional values.

Client code can add methods on this function, specializing them to the client class of its choice. The actions that `eclector.reader:read` needs to take for different values of the parameter recursive-p have already been taken before `read` calls this generic function.

### Method
Generic Function

### Parameters
- **client** - The client object.
- **input-stream** - The input stream to read from.
- **eof-error-p** - A boolean indicating whether to signal an error on end-of-file.
- **eof-value** - The value to return on end-of-file.

### Request Example
(Not applicable for generic functions, typically invoked internally or via method specialization)

### Response
#### Success Response
- **object** - The object read from the input stream.

#### Response Example
(Depends on the specific method implementation and input)
```

--------------------------------

### Symbol Token Checking and Error Recovery (Lisp)

Source: https://s-expressionists.github.io/Eclector/eclector

The `eclector.reader:check-symbol-token` generic function has been fixed. The default `eclector.reader:interpret-symbol` method now signals specific conditions and offers restarts for handling non-existent packages/symbols and non-exported symbols. The error recovery strategy now defaults to constructing an uninterned symbol instead of `cl:nil`.

```common-lisp
The incorrectly committed generic function `eclector.reader:check-symbol-token` has been fixed.
Empty escape ranges like `||` are no longer interpreted as potential numbers.
The default `eclector.reader:interpret-symbol` method now signals specific conditions and offers restarts for recovering from situations related to non-existent packages and symbols as well as non-exported symbols.
The default error recovery strategy for invalid symbols now constructs an uninterned symbol of the given name instead of using `cl:nil`.
```

--------------------------------

### Controlling Reader Variable Definitions (Lisp)

Source: https://s-expressionists.github.io/Eclector/eclector

The feature `:eclector-define-cl-variables` now controls whether the file `code/reader/variables.lisp` is loaded, which in turn determines if variables like `eclector.reader:*package*` and `eclector.reader:*read-eval*` are defined. This allows users to manage the definition of these reader-related variables.

```common-lisp
The feature `:eclector-define-cl-variables` now controls whether the file `code/reader/variables.lisp` is loaded and thus whether the variables `eclector.reader:*package*`, `eclector.reader:*read-eval*`, etc. are defined.
```

--------------------------------

### make-labeled-object

Source: https://s-expressionists.github.io/Eclector/eclector

Creates a representation of a labeled object. This is a lower-level function called by `note-labeled-object`.

```APIDOC
## MAKE-LABELED-OBJECT [eclector.reader]

### Description
This generic function creates a representation of a labeled object. It is called by the default method on `eclector.reader:note-labeled-object` with `client`, `input-stream`, and `label` to create an object of an unspecified type. Methods specialized to certain client classes could return unexpected objects, so client code should manipulate the object only via the generic functions described in this section.

### Method
GENERIC FUNCTION

### Endpoint
N/A (Internal function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```lisp
;; Called internally by note-labeled-object
(eclector.reader:make-labeled-object client input-stream "1" nil)
```

### Response
#### Success Response (200)
Returns a representation of the labeled object.

#### Response Example
```
#<labeled-object "1">
```
```

--------------------------------

### S-expression Creation API

Source: https://s-expressionists.github.io/Eclector/eclector

Functions for constructing representations of quoted, quasiquoted, and function forms.

```APIDOC
## Generic Function: wrap-in-quote [eclector.reader] client material

### Description
This generic function is called by the default `'`-reader macro function to construct a quotation form in which material is the quoted material.

### Method
Generic Function

### Endpoint
N/A (Internal function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(wrap-in-quote client material)
```

### Response
#### Success Response (200)
Returns a representation of a quoted form.

#### Response Example
```
(common-lisp:quote material)
```

## Generic Function: wrap-in-quasiquote [eclector.reader] client form

### Description
This generic function is called by the default ```-reader macro function to construct a quasiquotation form in which form is the quasiquoted material.

### Method
Generic Function

### Endpoint
N/A (Internal function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(wrap-in-quasiquote client form)
```

### Response
#### Success Response (200)
Returns a representation of a quasiquoted form.

#### Response Example
```
(eclector.reader:quasiquote form)
```

## Generic Function: wrap-in-unquote [eclector.reader] client form

### Description
This generic function is called by the default `,`-reader macro function to construct an unquote form in which form is the unquoted material.

### Method
Generic Function

### Endpoint
N/A (Internal function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(wrap-in-unquote client form)
```

### Response
#### Success Response (200)
Returns a representation of an unquote form.

#### Response Example
```
(eclector.reader:unquote form)
```

## Generic Function: wrap-in-unquote-splicing [eclector.reader] client form

### Description
This generic function is called by the default `,@`-reader macro function to construct a splicing unquote form in which form is the unquoted material.

### Method
Generic Function

### Endpoint
N/A (Internal function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(wrap-in-unquote-splicing client form)
```

### Response
#### Success Response (200)
Returns a representation of a splicing unquote form.

#### Response Example
```
(eclector.reader:unquote-splicing form)
```

## Generic Function: wrap-in-function [eclector.reader] client name

### Description
This generic function is called by the default `#'`-reader macro function to construct a form that applies the `function` special operator to the name expression.

### Method
Generic Function

### Endpoint
N/A (Internal function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
(wrap-in-function client name)
```

### Response
#### Success Response (200)
Returns a representation of a function form.

#### Response Example
```
(common-lisp:function form)
```
```

--------------------------------

### Relaxed Sharpsign-S Reader Macro (Lisp)

Source: https://s-expressionists.github.io/Eclector/eclector

Eclector now provides and uses by default a relaxed version of the `#S` reader macro. This macro requires the input following `#S` to be read as a list but does not strictly enforce the literal format `(TYPE INITARG₁ VALUE₁ …)`. This offers more flexibility in defining structures.

```common-lisp
; Eclector now provides and uses by default a relaxed version of the `eclector.reader::sharpsign-s`
;; reader macro function which requires the input following `#S` to be read as a list but
;; not necessarily be literally written as `(TYPE INITARG₁ VALUE₁ …)`.
;;
;; A detailed discussion of the topic has been added to the manual (See Interpretation of Sharpsign C and Sharpsign S).
```

--------------------------------

### Workaround for make-skipped-input-result children parameter (Common Lisp)

Source: https://s-expressionists.github.io/Eclector/eclector

Provides a workaround for clients needing to support Eclector versions with and without the 'children' parameter in `eclector.parse-result:make-skipped-input-result`. It uses `eval-when` and feature checks to conditionally include the new parameter.

```common-lisp
(eval-when (:compile-toplevel :load-toplevel :execute)
  (let* ((generic-function #'eclector.parse-result:make-skipped-input-result)
         (lambda-list      (c2mop:generic-function-lambda-list
                            generic-function)))
    (when (= (length lambda-list) 5)
      (pushnew 'skipped-input-children *features*))))
(defmethod eclector.parse-result:make-skipped-input-result
    ((client client)
     (stream t)
     (reason t)
     #+PACKAGE-THIS-CODE-IS-READ-IN::skipped-input-children (children t)
     (source t))
  ...
  #+PACKAGE-THIS-CODE-IS-READ-IN::skipped-input-children (use children)
  ...)
```

--------------------------------

### Eclector Reader Function Call Chain

Source: https://s-expressionists.github.io/Eclector/eclector

Illustrates the sequence of function calls within the Eclector reader for a top-level read operation. It highlights the new entry points `read-maybe-nothing` and `call-as-top-level-read` and their position in the call chain.

```lisp
eclector.reader:read
  eclector.reader:call-as-top-level-read
    eclector.reader:read-common
      eclector.reader:read-maybe-nothing
        ...
          eclector.reader:read-char
          eclector.reader:peek-char
```
Tokens:
Raw