Module scanner

This module defines various scanners that can be used to extract values from input text.

Kinds of Scanner

Scanners can be classified as “static self scanners”, “static abstract scanners”, and “runtime abstract scanners”.

• “Static self scanners” are types which implement the ScanFromStr trait and output an instance of themselves. For example, if you scan using the i32 type, you get an i32 result. These are implemented for types which have an obvious “default” scanning syntax.

  As a consequence of outputting an instance of themselves, they also automatically implement the ScanSelfFromStr trait.

• “Static abstract scanners” are types which implement the ScanFromStr trait and output an instance of some other type. For example, if you scan using the Word type, you get a &str or String result. These are implemented for cases where different rules are desireable, such as scanning particular subsets of a type (see Word, Number, NonSpace), or non-default encodings (see Binary, Octal, Hex).

• “Runtime abstract scanners” implement the ScanStr trait and serve the same overall function as static abstract scanners, except that the scanner itself must be constructed. In other words, static scanners are types, runtime scanners are values. This makes them a little less straightforward to use, but they are significantly more flexible. They can be parameterised at runtime, to perform arbitrary manipulations of both the text input and scanned values (see max_width, re_str).

Bridging Between Static and Runtime Scanners

A scanner of interest is ScanA<Type>. This is a runtime scanner which takes a static scanner as a type parameter. This allows you to use a static scanner in a context where a runtime scanner is needed.

For example, these two bindings are equivalent in terms of behaviour:

    // Scan a u32.
    let _: u32
    let _ <| scan_a::<u32>()

Creating Runtime Scanners

Runtime scanners are typically constructed using functions, rather than dealing with the implementing type itself. For example, to get an instance of the ExactWidth runtime scanner, you would call either the exact_width or exact_width_a functions.

The reason for two functions is that most runtime scanners accept a second runtime scanner for the purposes of chaining. This allows several transformations to be applied outside-in. For example, you can combine runtime scanners together like so:

    // Scan a word of between 2 and 5 bytes.
    let _ <| min_width(2, max_width(5, scan_a::<Word>()))

Functions ending in _a are a shorthand for the common case of wrapping a runtime scanner around a static scanner. For example, the following two patterns are equivalent:

    // Scan a u32 that has, at most, four digits.
    let _ <| max_width(4, scan_a::<u32>())
    let _ <| max_width_a::<u32>(4)

Modules

runtime

Types and constructors for various runtime scanners.

std

Scanner implementations for standard library (and other “official” crates) types.

Structs

Binary

Scans the given Output type from its binary representation.

Everything

Scans all remaining input into a string.

Hex

Scans the given Output type from its hexadecimal representation.

HorSpace

Scans a sequence of horizontal (non-newline) space characters into a string.

Ident

Scans a single identifier into a string.

Inferred

Explicitly infer the type of a scanner.

KeyValuePair

An abstract scanner that scans a (K, V) value using the syntax K: V.

Line

Scans everything up to the end of the current line, or the end of the input, whichever comes first. The scanned result does not include the line terminator.

Newline

Scans a single newline into a string.

NonSpace

Scans a sequence of non-space characters into a string.

Number

Scans a single number into a string.

Octal

Scans the given Output type from its octal representation.

Space

Scans a sequence of space characters into a string.

Word

Scans a single word into a string.

Wordish

Scans a single word-ish thing into a string.

Enums

QuotedString

Scans a quoted string.

Traits

ScanFromBinary

This trait defines scanning a type from a binary representation.

ScanFromHex

This trait defines scanning a type from a hexadecimal representation.

ScanFromOctal

This trait defines scanning a type from an octal representation.

ScanFromStr

This trait defines the interface to a type which can be scanned.

ScanSelfFromStr

This is a convenience trait automatically implemented for all scanners which result in themselves (i.e. ScanFromStr::Output = Self).

ScanStr

This trait defines the interface for runtime scanners.

Functions

exact_width

Creates a runtime scanner that forces exactly width bytes to be consumed.

exact_width_a

Creates a runtime scanner that forces exactly width bytes to be consumed by the static scanner S.

max_width

Creates a runtime scanner that forces at most width bytes to be consumed.

max_width_a

Creates a runtime scanner that forces at most width bytes to be consumed by the static scanner S.

min_width

Creates a runtime scanner that forces at least width bytes to be consumed.

min_width_a

Creates a runtime scanner that forces at least width bytes to be consumed by the static scanner S.

scan_a

Returns a runtime scanner that delegates to a static scanner.