stringstream.lua

Contents

• Functions
• Fields

Modules

• stringstream

Topics

• README
• UNLICENSE

Module stringstream

An object that loads chunks of strings on demand compatible with a subset of the string API suitable for parsing.

Project URL: https://github.com/gilzoide/stringstream-lua

Example:

local stringstream = require 'stringstream'

-- Streams may be created with callable objects (functions or tables/userdata
-- with __call metamethod) like the ones load expects, or file-like objects
-- that contain a read method, like open files.
local stream = assert(stringstream.new(io.stdin))

-- Alternatively, stringstream.open(filename, ...) may be used to open a file
-- by name in read mode and create a stringstream from it.
--
-- local stream = assert(stringstream.open("README.md"))

-- Now just call the supported string methods =D
while true do
    local token, advance = stream:match("(%S+)()")
    if not token then break end
    -- ... do something with token
    print('TOKEN', token)
    stream = stream:sub(advance)
end

Info:

• License: Public Domain

Functions

new (callable_or_file[, options[, ...]])	Create a new stringstream from callable object or file-like object.
open (filename[, ...])	Creates a new stream from file.
sub (i[, j])	Returns a substring or a new view into stream.
find (pattern[, init[, plain]])	Try finding pattern on loaded contents.
match (pattern[, init])	Try matching pattern on loaded contents.
gmatch (pattern[, init])	Returns an iterator function that, each time it is called, returns the next match from loaded contents.
__tostring ()	Returns the current loaded content string.
__len ()	Returns the current loaded content length.
len ()	Alias for stringstream:__len

Fields

readsize	Default read size of streams created with file objects.
max_find_lookahead	Default maximum number of bytes that stringstream:find may load.
_VERSION	Module version.

Functions

new (callable_or_file[, options[, ...]])

Create a new stringstream from callable object or file-like object.

Both functions and tables or userdata with a __call metamethod are accepted as callables. Just like load, each call must return a string that concatenates with previous results and a return of an empty string or a falsey value signals the end of the stream.

File-like objects are tables or userdata with a read method. Chunks will be read calling the read method as in object:read(...).

Parameters:

• callable_or_file function, table or userdata Callable or file-like object which chunks will be read from
• options Table of stream options. Currently the only supported option is max_find_lookahead. (optional)
• ... Arguments to be forwarded to the reading function. If callable_or_file is a file and no extra arguments are passed, stringstream.readsize will be used (optional)

Returns:

stringstream object

Or

1. nil
2. error message

Usage:

-- stream that reads chunks of 1024 bytes from opened file
-- and retries find as many times as necessary
stream = stringstream.new(io.open('file'))

-- stream that reads lines from stdin and fails a search after
-- having more than 4096 bytes loaded
stream = stringstream.new(io.stdin, { max_find_lookahead = 4096 }, '*l')

-- stream that generates digits from 1 to 10
local gen_numbers = coroutine.wrap(function()
    for i = 1, 10 do
        coroutine.yield(tostring(i))
    end
end)
stream = stringstream.new(gen_numbers)

open (filename[, ...])

Creates a new stream from file.

Opens the file with io.open in read mode and forward parameters to stringstream.new.

Parameters:

• filename string Name of the file to open
• ... Arguments forwarded to stringstream:new (optional)

Returns:

stringstream object

Or

1. nil
2. string Error message
3. number Error code on io.open failure

See also:

stringstream.new

Usage:

-- stream that reads chunks of 1024 bytes from 'file.txt'
-- and loads the entire contents on a call to find, if necessary
stream = stringstream.open('file.txt')

-- stream that reads lines from 'file.txt'
-- and loads the entire contents on a call to find, if necessary
stream = stringstream.open('file.txt', nil, '*l')

sub (i[, j])

Returns a substring or a new view into stream.

If both i and j are passed, returns the substring that starts at i and continues until j or until the end of stream. Otherwise, returns a new stringstream object with starting index i.

Parameters:

• i number Starting index
• j number Starting index (optional)

Returns:

stringstream If j is not passed and i is not past the end of the stream

Or

string Empty if j is not passed in and i is past the end of the stream

Or

string Substring if j is passed in

Raises:

If either i or j are non-positive, as reading from the end of stream is not supported.

find (pattern[, init[, plain]])

Try finding pattern on loaded contents.

Upon failure or if match spans the entire loaded content, loads new chunks, bailing out after having more than max_find_lookahead bytes loaded counting from init, returning nil afterwards.

Notice that the default value for max_find_lookahead makes the whole stream be loaded in case of failures or big matches. This is to have consistent output between stringstream and the string API by default.

Parameters:

• pattern string Pattern string to search
• init number Where to start the search from (optional)
• plain If truthy, turns off the pattern matching facilities (optional)

Returns:

1. number Starting index of found pattern
2. number Ending index of found pattern
3. ... Aditional captures of found pattern

Or

fail If pattern is not found

Raises:

If init is a negative number.

See also:

string.find

match (pattern[, init])

Try matching pattern on loaded contents.

Uses stringstream:find for searching, so the same caveats apply.

Parameters:

• pattern string Pattern string to search
• init number Where to start the search from (optional)

Returns:

... Captures of the found pattern

Or

string The whole match, if pattern specifies no captures

Or

fail If pattern is not found

Raises:

If init is a negative number.

See also:

• string.match
• stringstream:find

gmatch (pattern[, init])

Returns an iterator function that, each time it is called, returns the next match from loaded contents.

Uses stringstream:find for searching, so the same caveats apply.

Parameters:

• pattern string Pattern string to search
• init number Where to start the search from (optional)

Returns:

function Iterator function over matches

Raises:

If init is a negative number.

See also:

• string.gmatch
• stringstream:match

__tostring ()

Returns the current loaded content string.

Be careful that it almost never reflects the entire content string.

__len ()

Returns the current loaded content length.

Be careful that it almost never reflects the entire content length.

len ()

Alias for stringstream:__len

Fields

readsize

Default read size of streams created with file objects.

Change this to configure defaults module-wise. Default value is 1024.

max_find_lookahead

Default maximum number of bytes that stringstream:find may load.

Change this to configure defaults module-wise. Default value is math.huge, that is, load until stream is completely consumed, if necessary.

See also:

stringstream:find

_VERSION

Module version.