Module scan_rules::scanner
[−]
[src]
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 thei32
type, you get ani32
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 theWord
type, you get a&str
orString
result. These are implemented for cases where different rules are desireable, such as scanning particular subsets of a type (seeWord
,Number
,NonSpace
), or non-default encodings (seeBinary
,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 (seemax_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 |
Everything |
Scans all remaining input into a string. |
Hex |
Scans the given |
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 |
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 |
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. |
ScanStr |
This trait defines the interface for runtime scanners. |
Functions
exact_width |
Creates a runtime scanner that forces exactly |
exact_width_a |
Creates a runtime scanner that forces exactly |
max_width |
Creates a runtime scanner that forces at most |
max_width_a |
Creates a runtime scanner that forces at most |
min_width |
Creates a runtime scanner that forces at least |
min_width_a |
Creates a runtime scanner that forces at least |
scan_a |
Returns a runtime scanner that delegates to a static scanner. |