drop

operator

Return type: String
Returns: The specified source with the data matched by the specified pattern consumed.

Syntax

source drop pattern

Purpose

The drop operator returns the specified source with the data matched by the specified pattern consumed.

You can use the drop operator to perform substring operations:

  process
     output "abcdef" drop any{3}

This program will output "def".

You can use drop with any OmniMark source and as part of a nested pattern matching operation. The following code uses drop to get the extra-path information in a CGI program:

  do scan cgi-data{"PATH_INFO"} drop ~cgi-data{"SCRIPT_NAME"}
        match "/login" =|
           login-page
        match "/guess" =|
           guess-page
        else
           new-page
     done

Here the do scan is scanning the source returned by the drop operation. Note that drop returns a true source, so the unmatched data is not read by the drop operator. The data remains in the source until acted on by the action that uses the drop operator. This makes drop appropriate for use on large data sources.

It is an error if the pattern in a drop does not match. The following program includes an error in the data that causes the drop pattern not to match. This results in a program error, which is caught and processed by the program:

  process
     local stream local-number
     using input as "My telephone number is (1234) 555-7890"
     repeat scan #current-input
        match any** lookahead "("
           set local-number
            to #current-input drop ("(" digit{3} ")" white-space*)
     again
     output local-number
     catch #program-error code c
        do when c = 6131
           output "Invalid number in data."
        else
           rethrow
        done

If you want to ensure that a take operation always succeeds, write your pattern so that it can match zero characters. In the following program, this is achieved by adding a "?" to the end of the drop pattern. Since any pattern with a ? or * occurrence indicator can match zero times, such a pattern will always match (though it may match zero characters):

  process
     local stream local-number
     using input as "My telephone number is (1234) 555-7890"
     repeat scan #current-input
        match any** lookahead "("
           set local-number
            to #current-input drop ("(" digit{3} ")" white-space*)?
     again
     output local-number

Since the data error still exists, the drop pattern will match zero characters and the drop operator will return its source with zero characters consumed. The program will therefore output "(1234) 555-7890".

Notice that the pattern used in a drop must be a simple pattern. If you need more than one pattern element in a drop, you must wrap the whole pattern in parentheses. Thus the take pattern in the code above is written ("(" digit{3} ")").

Related Syntax

take