Module scan_rules::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.