From 576c43330c0f5f90c8d895699d809d680ef5778e Mon Sep 17 00:00:00 2001 From: "Meredith L. Patterson" Date: Sat, 16 Nov 2013 00:55:41 +0100 Subject: [PATCH] First cut at PHP bindings; no tests yet. --- src/bindings/php/hammer.xml | 604 ++++++++++++++++++++++++++++++++++++ 1 file changed, 604 insertions(+) create mode 100644 src/bindings/php/hammer.xml diff --git a/src/bindings/php/hammer.xml b/src/bindings/php/hammer.xml new file mode 100644 index 0000000..2172292 --- /dev/null +++ b/src/bindings/php/hammer.xml @@ -0,0 +1,604 @@ + + + + A library for defining parsers (character- or binary-oriented) inline. + ... + + + + mlp + Meredith L. Patterson + mlp@upstandinghackers.com + lead + + + + LGPL + + + 0.1 + 2013-11-15 + alpha + First cut of extension. + + + + Hammer C library +
+
+
+ + + + + + + + + void free() + Deallocate a parse result + + Free the memory allocated to a parse result when the result is no longer needed. + + + + + + + + + void report() + Output benchmarking results in a human-readable format + + + + + + + + + + HParseResult parse(string input) + Parse an input + Top-level function to call a parser that has been built over some piece of input. + + + + + int compile(string backend, array params) + Generate parse tables for the given parsing backend + + Some of the parsing backends must transform a parser into a set of parse tables before they can be used. See the documentation for the parser backend in question for information about the [params] parameter, or pass in NULL for the defaults. + + Returns -1 if the grammar cannot be compiled with the specified options; 0 otherwise. + + + + + + object benchmark(array testcases) + Benchmark this parser using all the applicable parsing backends against a set of test cases you provide + + + + + + + + + HParseResult hammer_token(string token) + Parse a token (primitive) + + Given a string, returns a parser that parses that string value. + + Result token type: string + + + + + + + HParseResult hammer_ch(string ch) + Parse a character (primitive) + + Given a single character, returns a parser that parses that character. + + Result token type: string + + + + + + + HParseResult hammer_ch_range(string lower, string upper) + Parse a character within the given range (primitive) + + Given two single-character bounds, lower and upper, returns a parser that parses a single character within the range [lower, upper] (inclusive). + + Result token type: string + + + + + + + HParseResult hammer_int_range(HParser p, int lower, int upper) + Parse an integer within the given range (primitive) + + Given an integer parser, p, and two integer bounds, lower and upper, returns a parser that parses an integral value within the range [lower, upper] (inclusive). + + Result token type: int + + + + + + + HParseResult hammer_bits(int len, bool sign) + Parse a specified number of bits (primitive) + + Returns a parser that parses the specified number of bits. sign == true if signed, false if unsigned. + + Result token type: int + + + + + + + HParseResult hammer_int64() + Parse a 64-bit signed integer (primitive) + + Returns a parser that parses a signed 8-byte integer value. + + Result token type: int + + + + + + + HParseResult hammer_int32() + Parse a 32-bit signed integer (primitive) + + Returns a parser that parses a signed 4-byte integer value. + + Result token type: int + + + + + + + HParseResult hammer_int16() + Parse a 16-bit signed integer (primitive) + + Returns a parser that parses a signed 2-byte integer value. + + Result token type: int + + + + + + + HParseResult hammer_int8() + Parse an 8-bit signed integer (primitive) + + Returns a parser that parses a signed 1-byte integer value. + + Result token type: int + + + + + + + HParseResult hammer_uint64() + Parse a 64-bit unsigned integer (primitive) + + Returns a parser that parses an unsigned 8-byte integer value. + + Result token type: int + + + + + + + HParseResult hammer_uint32() + Parse a 32-bit unsigned integer (primitive) + + Returns a parser that parses an unsigned 4-byte integer value. + + Result token type: int + + + + + + + HParseResult hammer_uint16() + Parse a 16-bit unsigned integer (primitive) + + Returns a parser that parses an unsigned 2-byte integer value. + + Result token type: int + + + + + + + HParseResult hammer_uint8() + Parse an 8-bit unsigned integer (primitive) + + Returns a parser that parses an unsigned 1-byte integer value. + + Result token type: int + + + + + + + HParseResult hammer_whitespace(HParser p) + Parse something preceded by whitespace (higher-order) + + Given a parser, p, returns a parser that skips any whitespace and then applies p. + + Result token type: p's result type + + + + + + + HParseResult hammer_left(HParser p, HParser q) + Take the leftmost result of two parsers (higher-order) + + Given two parsers, p and q, returns a parser that parses them in sequence but only returns p's result. + + Result token type: p's result type + + + + + + + HParseResult hammer_right(HParser p, HParser q) + Take the rightmost result of two parsers (higher-order) + + Given two parsers, p and q, returns a parser that parses them in sequence but only returns q's result. + + Result token type: q's result type + + + + + + + HParseResult hammer_middle(HParser p, HParser x, HParser q) + Take the middle result of three parsers (higher-order) + + Given three parsers, p, x, and q, returns a parser that parses them in sequence but only returns x's result. + + Result token type: x's result type + + + + + + + HParseResult hammer_action(HParser p, callable f) + Attach a semantic action to a parser (higher-order) + + Given another parser, p, and a function, f, returns a parser that applies p, then applies f to everything in the AST of p's result. + + Result token type: any + + + + + + + HParseResult hammer_in(string charset) + Parse a character that appears in charset (primitive) + + Parse a single character in the given charset. + + Result token type: string + + + + + + + HParseResult hammer_not_in(string charset) + Parse a character that does not appear in charset (primitive) + + Parse a single character *not* in the given charset. + + Result token type: string + + + + + + + HParseResult hammer_end_p() + Recognize the end-of-input (primitive) + + A no-argument parser that succeeds if there is no more input to parse. + + Result token type: none. + + + + + + + HParseResult hammer_nothing_p() + This parser always fails (primitive) + + hammer_nothing_p is primarily useful when stubbing out a larger parser. If you define a rule as hammer_nothing_p(), the top-level parser will run, but if a rule containing hammer_nothing_p is invoked, the parse will fail. + + Result token type: there is no result token for this parser. + + + + + + + HParseResult hammer_sequence(array p_array) + Apply a list of parsers sequentially (higher-order) + + Given an array of parsers, p_array, apply each parser in order. The parse succeeds only if all parsers succeed. + + Result token type: array + + + + + + + HParseResult hammer_choice(array p_array) + Apply any one of a list of parsers (higher-order) + + Given an array of parsers, p_array, apply each parser in order. The first parser to succeed produces the result; if no parsers succeed, the parse fails. + + Result token type: the type of the first successful parser's result + + + + + + + HParseResult hammer_butnot(HParser p1, HParser p2) + Parse p1 but not p2 (higher-order) + + Given two parsers, p1 and p2, this parser succeeds in the following cases: + + * if p1 succeeds and p2 fails (starting from the same place in the input stream) + * if both succeed but p1's result is as long as or longer than p2's + + Result token type: p1's result type. + + + + + + + HParseResult hammer_difference(HParser p1, HParser p2) + Parse p1 but not p2 (higher-order) + + Given two parsers, p1 and p2, this parser succeeds in the following cases: + + * if p1 succeeds and p2 fails (starting from the same place in the input stream) + * if both succeed but p2's result is *strictly* shorter than p1's + + Result token type: p1's result type. + + + + + + + HParseResult hammer_xor(HParser p1, HParser p2) + Parse p1 or p2 but not both (higher-order) + + Given two parsers, p1 and p2, this parser suceeds if *either* p1 or p2 succeed, but not if they both do. + + Result token type: the result type of whichever parser succeeded + + + + + + + HParseResult hammer_many(HParser p) + Parse zero or more instances of p (higher-order) + + Given a parser, p, this parser succeeds for zero or more repetitions of p. + + Result token type: array + + + + + + + HParseResult hammer_many1(HParser p) + Parse one or more instances of p (higher-order) + + Given a parser, p, this parser succeeds for one or more repetitions of p. + + Result token type: array + + + + + + + HParseResult hammer_repeat_n(HParser p, int n) + Parse exactly n instances of p (higher-order) + + Given a parser, p, this parser succeeds for exactly N repetitions of p. + + Result token type: array + + + + + + + HParseResult hammer_optional(HParser p) + Mark a parser as optional, like ? in regular expressions (higher-order) + + Given a parser, p, this parser succeeds with the value p parsed or with an empty result. + + Result token type: If p succeeded, the type of its result; if not, nothing. + + + + + + + HParseResult hammer_ignore(HParser p) + Apply p but leave its result out of the final AST (higher-order) + + Given a parser, p, this parser succeeds if p succeeds, but doesn't include p's result in the final result. + + Result token type: none. + + + + + + + HParseResult hammer_sepBy(HParser p, HParser sep) + Parse a (possibly empty) sequence of values separated by a separator (higher-order) + + Given a parser, p, and a parser for a separator, sep, this parser matches a (possibly empty) list of things that p can parse, separated by sep. For example, if p is hammer_many1(hammer_ch_range('0', '9')) and sep is hammer_ch(','), hammer_sepBy(p, sep) will match a comma-separated list of integers. + + Result token type: array + + + + + + + HParseResult hammer_sepBy1(HParser p, HParser sep) + Parse a sequence of values separated by a separator (higher-order) + + Given a parser, p, and a parser for a separator, sep, this parser matches a list of things that p can parse, separated by sep. Unlike hammer_sepBy, this ensures that the result has at least one element. For example, if p is hammer_many(hammer_ch_range('0', '9')), hammer_sepBy1(p, sep) will match a comma-separated list of integers. + + Result token type: array + + + + + + + HParseResult hammer_epsilon_p() + Parse the empty string (primitive) + + This parser always returns a zero-length match, i.e., the empty string. + + Result token type: none + + + + + + + HParseResult hammer_length_value(HParser length, HParser value) + Parse (length) repetitions of (value) (higher-order) + + This parser applies its first argument to read an unsigned integer value, then applies its second argument that many times. length should produce an integer value; this is checked at runtime. Specifically, length's token type must be int. + + Result token type: array + + + + + + + HParseResult hammer_attr_bool(HParser p, callable pred) + Ensure that some property holds for the AST (higher-order) + + This parser attaches a predicate function, which returns true or false, to a parser. The function is evaluated over the parser's result. The parse only succeeds if pred returns true. + + hammer_attr_bool will check whether p's result exists and whether p's result AST exists; you do not need to check for this in your predicate function. + + Result token type: p's result type if pred succeeds, otherwise the parse fails. + + + + + + + HParseResult hammer_and(HParser p) + Verify that p succeeds, but don't actually apply it (higher-order) + + This parser asserts that a conditional syntax is satisfied, but doesn't consume that conditional syntax. This is useful for lookahead. As an example: + + Suppose you already have a parser, hex_p, that parses numbers in hexadecimal format (including the leading "0x"). Then + + hammer_sequence(hammer_and(hammer_token("0x")), hex_p) + + checks to see whether there is a leading "0x", does not consume the "0x", then applies hex_p to parse the hexadecimal number. + + This parser succeeds if p succeeds, and fails if p fails. + + Result token type: none + + + + + + + HParseResult hammer_not(HParser p) + Verify that p does not succeed, and don't consume any input (higher-order) + + This parser asserts that a conditional syntax is *not* satisfied, and doesn't consume the additional syntax. As a somewhat contrived example: + + Since hammer_choice applies its arguments in order, the following parser: + + hammer_sequence(hammer_ch('a'), hammer_choice(hammer_ch('+'), hammer_token('++')), hammer_ch('b')) + + will not parse "a++b", because once hammer_choice has succeeded, it will not backtrack and try other alternatives if a later parser in the sequence fails. Instead, you can force the use of the second alternative by turning the hammer_ch('+') alternative into a sequence with hammer_not: + + hammer_sequence(hammer_ch('a'), hammer_choice(hammer_sequence(hammer_ch('+'), hammer_not('+')), hammer_token('++')), hammer_ch('b')) + + If the input string is "a+b", the first alternative is applied; if the input string is "a++b", the second alternative is applied. + + Result token type: none + + + + + + + HParseResult hammer_indirect() + Forward-declare a parser to be used recursively (higher-order) + + Create a parser that calls out to another, as yet unknown, parser. Note that the inner parser must be bound later, using hammer_bind_indirect(). This can be used to create recursive parsers. + + Result token type: the type of whatever parser is bound to it with hammer_bind_indirect(). + + + + + + + void hammer_bind_indirect(HParser p) + Set the inner parser of an indirect parser. + + See hammer_indirect() for details. + + + + + +