std.prototype 2.1

• Index

Contents

• Functions
• Metamethods
• Module Functions
• Fields

Modules

• std.prototype
• std.prototype.container
• std.prototype.contextmanager
• std.prototype.object
• std.prototype.orderedmap
• std.prototype.scanner
• std.prototype.set
• std.prototype.strbuf
• std.prototype.trie

Module std.prototype.contextmanager

Context Manager Prototype.

This module returns a table of context manager helpers, as well as the prototype for a ContextManager object.

A context manager holds a resource, such as an open file, that has to be released when the code that uses it is finished with it, whatever happens. with runs a function with the managers that it is given and releases them all afterwards, even when the function raises an error, which it raises again once they are released:

local contextmanager = require 'std.prototype.contextmanager'
local File, with = contextmanager.File, contextmanager.with

with(File('input.txt', 'r'), File('output.txt', 'w'), function(input, output)
   output:write(input:read '*a')
end)

A manager passes the methods that it does not have to its resource, so input:read above is the read of the open file. When the resource cannot be acquired, what makes the manager is nil and the reason, as io.open returns them, and with passes the function a nil for it and releases nothing.

In addition to the functionality described here, ContextManager objects also have all the methods and metamethods of the prototype.object.prototype (except where overridden here).

Prototype Chain

table
 `-> Container
      `-> Object
           `-> ContextManager

Functions

prototype (release, acquire, ...)

ContextManager prototype object.

Metamethods

__index (key)

Pass methods that are not the manager's own on to its resource.

Module Functions

File (fname[, mode])	A manager of a file, that is closed when it is released.
Pipe (cmd[, mode])	A manager of a pipe to or from a command, that is closed when it is released.
TmpFile ([fname[, mode='w']])	A manager of a temporary file, that is closed and removed when it is released.
slurp (cm, ...)	Read everything from a manager of a file or pipe, and release it.
with (..., block)	Run a function, and release the managers that it was given after.

Fields

context	The resource that the manager holds.
release ()	The function that releases the resource, called as cm:release().
n	The number of arguments that the resource was acquired with, which are in the list part of the manager.

Functions

prototype (release, acquire, ...)

ContextManager prototype object. Call it, or the module, to make a manager of any resource.

Parameters:

• release callable called with the manager to release the resource
• acquire callable called with the arguments to get the resource
• ... arguments for acquire, which the manager keeps in its list part, with their number in n

Returns:

1. ContextManager or nil a manager of what acquire returns, which is also in its context field, or nil if it returns none
2. the reason, if there is no manager, as acquire gave it

See also:

File

Usage:

local cm = contextmanager(function(cm) cm.context:close() end, io.open, 'file', 'r')

Metamethods

__index (key)

Pass methods that are not the manager's own on to its resource.

Parameters:

• key string a method of the resource

Returns:

function that calls the method of the resource

Module Functions

File (fname[, mode])

A manager of a file, that is closed when it is released. The name of the file is in the manager as filename.

Parameters:

• fname string the name of the file
• mode string how to open it, as for io.open (optional)

Returns:

1. ContextManager or nil a manager of the open file, or nil
2. the reason, if there is no manager

Usage:

with(File('input.txt', 'r'), function(input) return input:read '*a' end)

Pipe (cmd[, mode])

A manager of a pipe to or from a command, that is closed when it is released. The command is in the manager as command.

Parameters:

• cmd string the command to run
• mode string 'r' to read its output, or 'w' to write to its input, as for io.popen (optional)

Returns:

1. ContextManager or nil a manager of the pipe, or nil
2. the reason, if there is no manager

Usage:

local date = slurp(Pipe 'date')

TmpFile ([fname[, mode='w']])

A manager of a temporary file, that is closed and removed when it is released. The name of the file is in the manager as filename.

Parameters:

• fname string the name of the file, which is one that os.tmpname makes by default (optional)
• mode string how to open it, as for io.open (default 'w')

Returns:

1. ContextManager or nil a manager of the open file, or nil
2. the reason, if there is no manager

Usage:

with(TmpFile(), function(tmp) tmp:write 'scratch' end)

slurp (cm, ...)

Read everything from a manager of a file or pipe, and release it. A nil that there is no manager is passed on, with the reason that there is none, so that slurp(File(fname)) is the contents of the file or else nil and why not.

Parameters:

• cm ContextManager or nil a manager of something to read
• ... the reason there is no manager, to return with it

Returns:

string or nil what was read

Usage:

local text, err = slurp(File 'input.txt')

with (..., block)

Run a function, and release the managers that it was given after. The function is called with the managers, and its results are the results of with. The managers are released last first, even if the function raises an error, and that error is raised again afterwards; or else the first error of a release. A nil for a resource that could not be acquired is passed to the function, and not released.

Parameters:

• ... ContextManager or nil the managers to release afterwards
• block callable the function to call with them

Returns:

the results of block

Usage:

with(File('a', 'w'), File('b', 'w'), function(a, b)
   a:write 'to a'
   b:write 'to b'
end)

Fields

context

The resource that the manager holds.

• context

release ()

The function that releases the resource, called as cm:release().

n

The number of arguments that the resource was acquired with, which are in the list part of the manager.

• n integer