#current-input

built-in shelf

Purpose

#current-input is a built-in string source which represents the unconsumed part of the input currently being processed by a submit, do scan, repeat scan, or using input as.

#current-input can be used like any other built-in string source such as #main-output, so long as it is attached. #current-input is attached if an input has been established by a submit, a do scan, a repeat scan, or a using input as. It is also attached in the body of a string sink function. In contrast, #current-input is not attached in

a string source function,
a process rule, a process-start rule, or a process-end rule,
a markup rule, or
a pattern.

In all of these cases, #current-input can be attached by processing an input using one of the methods discussed previously.

Using #current-input has the effect of consuming the remaining data from the source, unless

it is used in a scanning context (submit, do scan, or repeat scan), or on the left-hand side of drop, take, and matches,
it is used as the argument to using input as, or
it is passed to a function as a value string source argument.

In any of these cases, if the processing in question terminates before consuming all of #current-input, the original processing resumes and continues until #current-input is completely consumed.

The following code shows what happens when #current-input is output or assigned to a variable:

  process
     submit "Mary had a little lamb."
     
  
  find "Mary" white-space+
     output #current-input
     
  
  find "lamb"
     output "Baa baa black sheep."

The program will output had a little lamb.. It will not output Baa baa black sheep., because after the pattern "Mary" whitespace+ succeeds, the rest of the input is consumed by output #current-input, so the rule find "lamb" never fires.

Meanwhile, the following code shows what happens when #current-input is used as the source for a scanning context:

  process
     submit "Mary had a little lamb."
     
  
  find "Mary" white-space+
     output "David "
     repeat scan #current-input
     match "had" white-space+
        output "stole "
     match "a" white-space+
        output "my "
     again   
     
  
  find "lamb"
     output "sheep"

This program will output David stole my little sheep.. The characters Mary and little lamb. were processed by the find rules invoked by the original submit. The characters had a were processed by the repeat scan of #current-input. That repeat scan exited when it failed to match little lamb., leaving those characters unconsumed, and available for processing by the original find rules.