~mna/tulip-wiki

9331642581867113ded0d336284d8c56150746a9 — Martin Angers 3 years ago 3790482 v0.1.15-1
Document the new xstring functions
1 files changed, 77 insertions(+), 0 deletions(-)

M xstring.md
M xstring.md => xstring.md +77 -0
@@ 9,11 9,88 @@ Assuming `local xstring = require 'tulip.xstring'`.
Make each first letter of each word in s uppercase, the rest
lowercase.

## `t = xstring.decode_header(h, name)`

Decodes header value h into an array where each entry is a table
with a field "value" set to that entry's value, and an arbitrary
number of other fields corresponding to that header value's
directive (a semicolon-separated series of key=value after the
header's value). If a directive appears without a value (e.g. key
only), it is set as a key on the table with the value set to true.

It returns an array because headers can specify multiple values
using a comma-separated list.

For example (Accept):
```
  text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8
```
Would return:
```
  {
    {value = 'text/html'},
    {value = 'application/xhtml+xml'},
    {value = 'application/xml', q = '0.9'},
    {value = 'image/webp', q = '0.9'},
    {value = '*/*', q = '0.8'},
  }
```

Another example (Content-Type):
```
  multipart/form-data; boundary=something
```
Would return:
```
  {
    {value = 'multipart/form-data', boundary = 'something'},
  }
```

Finally (Accept-Encoding):
```
  deflate, gzip;q=1.0, *;q=0.5
```
Would return:
```
  {
    {value = 'deflate'},
    {value = 'gzip', q = '1.0'},
    {value = '*', q = '0.5'},
  }
```

If the optional name parameter is provided, it is set as the field
name on the array itself, to keep track of what header this table
represents.

## `s = xstring.escapefile(s)`

Escape s to return a valid file name, replacing potentially unsafe characters
with underscores.

## `indices, ht = xstring.header_directive_matches(h, d, v, plain)`

Tests if header value h (which may have multiple values) has a directive d
that matches value v. If h is a string, it is first decoded by calling
decode\_header. If v is a table, it is considered an array of string values
to test. If plain is falsy, v is considered a Lua pattern.

If at least one match is found, it returns a table that is an array of indices
where a match was found, in the decoded header's array. The second return
value is the decoded header's array. Returns nil if no match is found.

## `indices, ht = xstring.header_value_matches(h, v, plain)`

Tests if header value h (which may have multiple values) matches value v. If
h is a string, it is first decoded by calling decode\_header. If v is a
table, it is considered an array of string values to test. If plain is
falsy, v is considered a Lua pattern.

If at least one match is found, it returns a table that is an array of indices
where a match was found in the decoded header's array. The second return
value is the decoded header's array. Returns nil if no match is found.

## `s = xstring.ipat(pat)`

Turn pat into a case-insensitive pattern. It throws an error if pat contains