1 # Lua Bindings
   2 
   3 This directory contains Lua bindings for bp. The bindings are intended to be
   4 roughly equivalent in usefulness to LPEG, but with a smaller codebase (roughly
   5 3/4 the size, as of this writing).
   6 
   7 ## API
   8 
   9 The Lua `bp` bindings provide the following methods:
  10 
  11 ```lua
  12 bp.match(pattern, text, [start_index]) --> match / nil
  13 bp.replace(pattern, replacement, text, [start_index]) --> text_with_replacements, num_replacements
  14 bp.compile(pattern) --> pattern_object
  15 for m in bp.matches(pattern, text, [start_index]) do ... end
  16 
  17 pattern_object:match(text, [start_index]) --> match / nil
  18 pattern_object:replace(replacement, text, [start_index]) --> text_with_replacements, num_replacements
  19 for m in pattern_object:matches(text, [start_index]) do ... end
  20 ```
  21 
  22 Match objects returned by `bp.match()` are tables whose `__tostring` will
  23 return the text of the match. Additionally, match objects store the text of the
  24 match at index `0`, the match's starting index in the source string as
  25 `.start`, the first index after the match as `.after`, and any captures stored
  26 as match objects with a key corresponding to the capture's identifier (e.g.
  27 `@"a" @foo="bc"` will be encoded as `{[0]="abc", [1]="a", foo={[0]="bc"}}`. If
  28 multiple captures within a match share the same identifier, it is unspecified
  29 which captured match will be stored at that key, so it's best to be
  30 unambiguous.
  31 
  32 Pattern objects returned by `bp.compile()` are pre-compiled patterns that are
  33 slightly faster to reuse than just calling `bp.match()` repeatedly. They have
  34 `:match()`, `:replace()`, and `:matches()` methods as described above, as well
  35 as a `:getsource()` method that returns the original source used to make the
  36 pattern.
  37 
  38 All methods will raise an error with a descriptive message if the given pattern
  39 has a syntax error.
  40 
  41 ## Example Usage
  42 
  43 ```lua
  44 local bp = require("bp")
  45 local m = bp.match('"n" @Es=+`e "dle"', "like finding a needle in a haystack")
  46 --> {[0]="needle", Es={[0]="ee", start=17, after=19}, start=16, after=22}
  47 --> tostring(m) == "needle", tostring(m.Es) == "ee"
  48 local replaced, nreplacements = bp.match('"n" +`e "dle"', "cat", "like finding a needle in a haystack")
  49 --> "like finding a cat in a haystack", 1
  50 
  51 for word in bp.matches("+`A-Z,a-z", "one, two three... four!") do
  52     print(word) --> prints "one" "two" "three" "four"
  53 end
  54 
  55 local pat = bp.compile("word parens")
  56 for _,s in ipairs(my_strings) do
  57     for fncall in pat:matches(s) do
  58         print(fncall)
  59     end
  60 end
  61 ```