cp.rx.go.Statement.md

docs » cp.rx.go.Statement

---

A Statement is defined to enable processing of asynchronous resolvable values such as cp.rx.Observable values.

To define a new Statement, you call the named constructor, assigning the result to a constant value and calling the define method.

Definine a new Statement

To define a new Statement implementation, we use the Statement.named constructor. This gives us a Statement.Definition which allows us to set the rules for the statement before finally "defining" it.

Statements may have an onInit, and must have an onObservable provided, and then the define method must be called.

For example, the First statement is defined like so:

local First = Statement.named("First")
:onInit(function(context, resolvable)
    assert(resolvable ~= nil, "The First `resolveable` may not be `nil`.")
    context.resolvable = resolvable
end)
:onObservable(function(context)
    return toObservable(context.resolvable):first()
end)
:define()

Once you've defined a statement, you then execute it by calling the statement directly, passing in any parameters.

For example:

local First = require("cp.rx.go").First
First(Observable.of(1, 2, 3))
:Now(
    function(value) print("Received: "..tostring(value)) end,
    function(message) print("Error: "..tostring(message)) end,
    function() print("Completed") end
)

This will output:

Received: 1
Completed

The Observable as passed to the onInit function handler as the second parameter. context is always the first parameter, followed by any values passed to the constructor call.

The onObservable function handler is called once the statement is actually executing, typically by calling the Now or After methods.

It is recommended that any conversion of input parameters are converted to Observables as late as possible, typically in the onObservable function handler. Otherwise, input values may get resolved before the user intends.

Submodules

• cp.rx.go.Statement.Definition
• cp.rx.go.Statement.Modifier

API Overview

• Functions - API calls offered directly by the extension
• defaultObserverFactory
• is
• toObservable
• toObservables
• Constructors - API calls which return an object, typically one that offers API methods
• named
• Methods - API calls which can only be made on an object returned by a constructor
• After
• Catch
• Debug
• Finally
• fullName
• Label
• name
• Now
• ThenDelay
• ThenYield
• TimeoutAfter
• toObservable

API Documentation

Functions

defaultObserverFactory

Signature	cp.rx.go.Statement.defaultObserverFactory([factoryFn]) -> nil
Type	Function
Description	Gets/sets the factory function which creates a new Observer for Statements which are executed without one being provided.
Parameters	factoryFn - if provided, replaces the current default factory function.
Returns	A new Observer, or the previous factory function if a new one was provided.
Notes	The factory function has no arguments provided and must return a new Observer instance.

is

Signature	cp.rx.go.Statement.is(thing) -> boolean
Type	Function
Description	Checks if the thing is a Statement.
Parameters	thing - The thing to test.
Returns	true if the thing is a Statement.

toObservable

Signature	cp.rx.go.Statement.toObservable(thing[, params]) -> cp.rx.Observable
Type	Function
Description	Converts the thing into an Observable. It converts the following:
Parameters	thing - The thing to convert. params - Optional table list to pass as parameters for the thing if it's a function.
Returns	The Observable.

toObservables

Signature	cp.rx.go.Statement.toObservables(things[, params]) -> table
Type	Function
Description	Converts a list of things into a list of Observables of those things.
Parameters	things - a table list of things to convert to Observables. params - an optional table list of parameters to pass to any function things.
Returns	A table list of the things, converted to Observable.

Constructors

named

Signature	cp.rx.go.Statement.named(name) -> Statement.Definition
Type	Constructor
Description	Starts the definition of a new Statement with the specified names.
Parameters	name - The name of the Statement.
Returns	A Statement.Definition.

Methods

After

Signature	cp.rx.go.Statement:After(millis[, observer][, scheduler]) -> nil
Type	Method
Description	Requests the statement to be executed after the specified amount of time in seconds.
Parameters	millis - The number of milliseconds to delay the execution. observer - The observer to subscribe to the final result. scheduler - (optional) the cp.rx.Scheduler to use. Uses the cp.rx.util.defaultScheduler() if none is provided.
Returns	Nothing.

Catch

Signature	cp.rx.go.Statement:Catch(handler) -> cp.rx.go.Statement
Type	Method
Description	Assigns a handler which will be applied at the end of the Statement.
Parameters	handler - The handler function
Returns	The same Statement.

Debug

Signature	cp.rx.go.Statement:Debug([label]) -> Statement
Type	Method
Description	Indicates that the results of the Statement should be output to the Error Log.
Parameters	label - If specified, this is output in the log.
Returns	The same Statement instance.

Finally

Signature	cp.rx.go.Statement:Finally(handler) -> Statement
Type	Method
Description	Provides a function handler to get called when the statement is done, either via an onError or onComplete signal.
Parameters	handler - The handler function.
Returns	The same Statement instance.

fullName

Signature	cp.rx.go.Statement:fullName()
Type	Method
Description	Returns the Statement's full name.
Returns	The full Statement name.

Label

Signature	cp.rx.go.Statement:Label(label) -> Statement
Type	Method
Description	Sets the custom label for the Statement. This will
Parameters	label - Optional new value for the label. If provided, the Statement is returned.
Returns	The Statement if a new lable is specified, otherwise the current label value.

name

Signature	cp.rx.go.Statement:name()
Type	Method
Description	Returns the Statement name.
Returns	The Statement name.

Now

Signature	cp.rx.go.Statement:Now([observer]) -> nil
Type	Method
Description	Executes the statment immediately.
Parameters	observer - An observer to watch the resulting Observable. Defaults to the default observer factory.
Returns	Nothing.

ThenDelay

Signature	cp.rx.go.Statement:ThenDelay(millis) -> cp.rx.go.Statement
Type	Method
Description	Indicates that there will be a delay after this statement by the
Parameters	millis - the amount of time to delay, in millisecods.
Returns	The same Statement.

ThenYield

Signature	cp.rx.go.Statement:ThenYield() -> cp.rx.go.Statement
Type	Method
Description	Indicates that the Statement will "yield" to allow other pending operations to happen,
Parameters	None
Returns	The same Statement.

TimeoutAfter

Signature	cp.rx.go.Statement:TimeoutAfter(millis[, next][, scheduler]) -> cp.rx.go.Statement
Type	Method
Description	Indicates that this statement should time out after the specified number of milliseconds.
Parameters	millis - A number or a function returning the number of milliseconds to wait before timing out. next - Optional string or resolvable value indicating how to handle it. scheduler - The cp.rx.Scheduler to use when timing out. Defaults to cp.rx.defaultScheduler().
Returns	The same Statement.

toObservable

Signature	cp.rx.go.Statement:toObservable([preserveTimer]) -> cp.rx.Observable
Type	Method
Description	Returns a new Observable instance for the Statement. Unless preserveTimer is true, this will
Parameters	preserveTimer - If a timer has been set via After, don't cancel it. Defaults to false.
Returns	The Observable.