Skip to content

iIssue #401 - Document the interactions between READSTOP and context #405

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yoavnir merged 1 commit into from
Jun 1, 2026
Merged

iIssue #401 - Document the interactions between READSTOP and context #405

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 23 additions & 3 deletions manpage
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -228,9 +228,17 @@ Convert printable time format to a number, representing microseconds since the e
.SS "Other Spec Units"
There are also other spec units, that may be used:
.IP "READ" 3
Causes the program to read the next line of input. If we have already read the last line, the read line is taken to be the empty string.
Causes the program to read the next line of input. If we have already read the last line, the read line is taken to be the empty string. When a
.B READ
or
.B READSTOP
spec unit is applied, the context offset is reset to zero (the current record).
.IP "READSTOP" 3
Causes the program to read the next line of input. If we have already read the last line, no more processing is done for this iteration.
Causes the program to read the next line of input. If we have already read the last line, no more processing is done for this iteration. When a
.B READ
or
.B READSTOP
spec unit is applied, the context offset is reset to zero (the current record).
.IP "UNREAD" 3
Causes the program to push back the current active record back to the reader, so that the next iteration of the specification or the next
.I READ
Expand Down Expand Up @@ -367,7 +375,11 @@ resets the working string to the current record,
sets it to the next record,
.B CONTEXT -1
sets it to the previous record, and so on.
The required buffer sizes are computed at parse time from the largest positive and negative offsets used. If the offset refers to a record beyond the beginning or end of the input, the working string is set to the empty string.
The required buffer sizes are computed at parse time from the largest positive and negative offsets used. If the offset refers to a record beyond the beginning or end of the input, the working string is set to the empty string. Note that reading beyond the input with
.B CONTEXT
does not cause processing to stop, even if a
.B READSTOP
token is present in the specification.
.P
.B CONTEXT
must not be abbreviated. It is not supported with threading or multiple input streams.
Expand Down Expand Up @@ -399,6 +411,14 @@ Example:
echo -e "A\\nB\\nC" | specs print @+1 1
.P
produces: "B", "C", "" -- each line shows the next record (empty for the last).
.P
Note that reading beyond the input with
.B @+n
or
.B @-n
does not cause processing to stop, even if a
.B READSTOP
token is present in the specification.

.SS "MainOptions"
These are optional spec units that appear at the beginning of the specification and modify the behavior of the entire specification.
Expand Down
2 changes: 1 addition & 1 deletion specs/docs/alu.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ POSIX (darwin) system using the g++ compiler and Python 3.9.6 - release variatio
```
Others are `@cols`, which contains the number of columns in the terminal screen, and `@rows`, which contains the number of rows on that same screen.

Additionally, the `@@` string stands for the entire input record. When rolling context is in effect (see [Streams and Records](streams.md#rolling-context)), `@@` always refers to the original input record. The `@!` string refers to the current record as affected by `CONTEXT`, which is the same as `@@` when no `CONTEXT` is active. The `@-n` and `@+n` syntax is an alternative to using that is effective within expressions. The following three specifications are equivalent:
Additionally, the `@@` string stands for the entire input record. When rolling context is in effect (see [Streams and Records](streams.md#rolling-context)), `@@` always refers to the original input record. The `@!` string refers to the current record as affected by `CONTEXT`, which is the same as `@@` when no `CONTEXT` is active. The `@-n` and `@+n` syntax is an alternative to using that is effective within expressions. Note that reading beyond the input with `@+n` or `@-n` does not cause processing to stop, even if a `READSTOP` token is present in the specification. The following three specifications are equivalent:

```
# Using @@ syntax # Using the CONTEXT keyword # No expression - just data fields
Expand Down
8 changes: 5 additions & 3 deletions specs/docs/streams.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ So why do we have data fields at all if we don't want to output them? There can
## >1 Input Records in Each Iteration
Sometimes we would like to use more than one input record to produce our output record. We use the `READ` or `READSTOP` keywords for that.

Both `READ` and `READSTOP` read the next record from the input stream to be the new active input record. The difference is what to do if the current line was the last. With `READ` the specification continues to be executed as if we have just read an empty record. With `READSTOP` the execution of the specification stops.
Both `READ` and `READSTOP` read the next record from the input stream to be the new active input record. The difference is what to do if the current line was the last. With `READ` the specification continues to be executed as if we have just read an empty record. With `READSTOP` the execution of the specification stops. When a `READ` or `READSTOP` spec unit is applied, the context offset is reset to zero (the current record).

Below is an example of a specification that handles git log. A git log looks something like this:
```
Expand Down Expand Up @@ -250,7 +250,7 @@ A few things to note:
## Rolling Context
The `SELECT SECOND` mechanism described above lets us peek one record ahead. But what if we need to look further ahead, or look *behind* at records we've already seen? The `CONTEXT` spec unit provides a general way to do this.

`CONTEXT` takes a single integer argument -- a positive number to look forward, a negative number to look backward, or zero to reset to the current record. When **specs** encounters a `CONTEXT` spec unit, it changes the active input record to the one at the given offset from the current record. Any input parts that follow will read from that record instead of the current one.
`CONTEXT` takes a single integer argument -- a positive number to look forward, a negative number to look backward, or zero to reset to the current record. When **specs** encounters a `CONTEXT` spec unit, it changes the active input record to the one at the given offset from the current record. Any input parts that follow will read from that record instead of the current one. Note that reading beyond the input with `CONTEXT` does not cause processing to stop, even if a `READSTOP` token is present in the specification.

Consider the following input:
```
Expand Down Expand Up @@ -294,12 +294,14 @@ gamma
```
The first column comes from `WORD 1` while the *next* record is selected, and the second column comes from `WORD 1` after `CONTEXT 0` resets back to the current record.

Note that when a `READ` or `READSTOP` spec unit is applied, the context offset is automatically reset to zero (the current record). This means that any context offset set by a `CONTEXT` spec unit will be lost when `READ` or `READSTOP` is executed.

### Context in Expressions
In addition to the `CONTEXT` spec unit, **specs** supports the `@+n` and `@-n` syntax in expressions, where *n* is a non-negative integer. These evaluate to the full content of the record at the given offset:
```
specs PRINT "length(@+1)" 1
```
Given the input `AB`, `CDE`, `F`, this outputs `3`, `1`, `0` -- the length of the *next* record in each cycle.
Given the input `AB`, `CDE`, `F`, this outputs `3`, `1`, `0` -- the length of the *next* record in each cycle. Note that reading beyond the input with `@+n` or `@-n` does not cause processing to stop, even if a `READSTOP` token is present in the specification.

Note that `@@` (the current input record) and `@+0` or `@-0` are not quite the same thing when `CONTEXT` is also used: `@@` always returns the real input record, regardless of any `CONTEXT` that may be in effect. To get the context-affected record in an expression, use `@!`:
```
Expand Down
23 changes: 14 additions & 9 deletions specs/src/gdb/specs.gdb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,39 +65,39 @@ define dump_item
end

define dump_data_field
dump-data-field $arg0
dump-data-field ((DataField)($arg0))
end

define dump_token_item
dump-token-item $arg0
dump-token-item ((TokenItem)($arg0))
end

define dump_set_item
dump-set-item $arg0
dump-set-item ((SetItem)($arg0))
end

define dump_skip_item
dump-skip-item $arg0
dump-skip-item ((SkipItem)($arg0))
end

define dump_condition_item
dump-condition-item $arg0
dump-condition-item ((ConditionItem)($arg0))
end

define dump_break_item
dump-break-item $arg0
dump-break-item ((BreakItem)($arg0))
end

define dump_context_item
dump-context-item $arg0
dump-context-item ((ContextItem)($arg0))
end

define dump_select_item
dump-select-item $arg0
dump-select-item ((SelectItem)($arg0))
end

define dump_split_item
dump-split-item $arg0
dump-split-item ((SplitItem)($arg0))
end

# itemGroup
Expand Down Expand Up @@ -156,6 +156,10 @@ define dump_freq_map
dump-frequency-map $arg0
end

define dump_compute_stack
dump-compute-stack $arg0
end

# Python interface
define dump_alu_function
dump-alu-function $arg0
Expand Down Expand Up @@ -279,6 +283,7 @@ echo dump_token <var> - Dump Token\n
echo dump_alu_value <var> - Dump ALUValue\n
echo dump_alu_counters <var> - Dump ALUCounters\n
echo dump_alu_vec <var> - Dump AluVec\n
echo dump_compute_stack <var> - Dump compute stack (std::stack<PValue>)\n
echo dump_alu_function <var> - Dump AluFunction\n
echo dump_external_func_rec <var> - Dump ExternalFunctionRec\n
echo dump_python_func_collection <var> - Dump PythonFunctionCollection\n
Expand Down
Loading
Loading