# Module `pl.sip`

Simple Input Patterns (SIP).

SIP patterns start with '$', then a one-letter type, and then an optional variable in curly braces.

    sip.match('$v=$q','name="dolly"',res)
    ==> res=={'name','dolly'}
    sip.match('($q{first},$q{second})','("john","smith")',res)
    ==> res=={second='smith',first='john'}

Type names:

    v     identifier
    i     integer
    f     floating-point
    q     quoted string
    ([{<  match up to closing bracket

See the Guide

## Functions

create_pattern (spec, options) | convert a SIP pattern into the equivalent Lua string pattern.
compile (spec, options) | convert a SIP pattern into a matching function.
match (spec, line, res, options) | match a SIP pattern against a string.
match_at_start (spec, line, res) | match a SIP pattern against the start of a string.
fields (spec, f) | given a pattern and a file object, return an iterator over the results
pattern (spec, fun) | register a match which will be used in the read function.
read (f, matches) | enter a loop which applies all registered matches to the input file.

## Functions

create_pattern (spec, options)
  convert a SIP pattern into the equivalent Lua string pattern.

  ### Parameters:

  - spec a SIP pattern
  - options a table; only the `at_start` field is currently meaningful and ensures that the pattern is anchored at the start of the string.

  ### Returns:

  a Lua string pattern.
compile (spec, options)
  convert a SIP pattern into a matching function. The returned function takes two arguments, the line and an empty table. If the line matched the pattern, then this function returns true and the table is filled with field-value pairs.

  ### Parameters:

  - spec a SIP pattern
  - options optional table; {at_start=true} ensures that the pattern is anchored at the start of the string.

  ### Returns:

  a function if successful, or nil,error
match (spec, line, res, options)
  match a SIP pattern against a string.

  ### Parameters:

  - spec a SIP pattern
  - line a string
  - res a table to receive values
  - options (optional) option table

  ### Returns:

  true or false
match_at_start (spec, line, res)
  match a SIP pattern against the start of a string.

  ### Parameters:

  - spec a SIP pattern
  - line a string
  - res a table to receive values

  ### Returns:

  true or false
fields (spec, f)
  given a pattern and a file object, return an iterator over the results

  ### Parameters:

  - spec a SIP pattern
  - f a file-like object.
pattern (spec, fun)
  register a match which will be used in the read function.

  ### Parameters:

  - spec string a SIP pattern
  - fun function a function to be called with the results of the match

  ### See also:

  read
read (f, matches)
  enter a loop which applies all registered matches to the input file.

  ### Parameters:

  - f a file-like object
  - matches array optional list of `{spec,fun}` pairs, as for pattern above.

generated by LDoc 1.5.0