JavaScript client object for Cene interaction
=============================================

When a JavaScript program generated by :ref:`sloppy-javascript-program` or :ref:`picky-javascript-program` is run, it has access to a JavaScript object that acts as a client for calling back to the Cene runtime. The client has several methods:


.. _client.getTopLevelVar():

client.getTopLevelVar( ... )
----------------------------

Call from JavaScript with ``( varName )``

Gets the current value of the top-level JavaScript variable whose name is the given JavaScript string. It must be one of the variables that was captured by the code produced by (:ref:`sloppy-javascript-program` ...) or (:ref:`picky-javascript-program` ...).


.. _client.setTopLevelVar():

client.setTopLevelVar( ... )
----------------------------

Call from JavaScript with ``( varName, val )``

Assigns to the top-level JavaScript variable whose name is the given JavaScript string. It must be one of the variables that was captured by the code produced by (:ref:`sloppy-javascript-program` ...) or (:ref:`picky-javascript-program` ...).


.. _client.wrap():

client.wrap( ... )
------------------

Call from JavaScript with ``( jsVal )``

Wraps the given JavaScript value as a wrapped Cene value. If the JavaScript value is itself a wrapped Cene value, this wraps it again anyway.


.. _client.maybeUnwrap():

client.maybeUnwrap( ... )
-------------------------

Call from JavaScript with ``( wrappedVal )``

Returns ``null`` or ``{ val: jsVal }`` depending on whether the given wrapped Cene value was obtained by wrapping a JavaScript value. If the given value isn't a wrapped Cene value, this raises an exception.


.. _client.done():

client.done( ... )
------------------

Call from JavaScript with ``( result )``

Creates a wrapped Cene JavaScript effects value that does nothing and results in the given value.


.. _client.then():

client.then( ... )
------------------

Call from JavaScript with ``( jsEffects, function ( intermediate ) )``

Creates a wrapped Cene JavaScript effects value that executes the given ``jsEffects`` wrapped Cene JavaScript effects value, calls the given JavaScript callback passing a wrapped version of the intermediate result, and proceeds by running the resulting wrapped Cene JavaScript effects value.


.. _client.giveSync():

client.giveSync( ... )
----------------------

Call from JavaScript with ``( val, cene (fn val) )``

Creates a wrapped Cene JavaScript effects value that synchronously calls the given ``ceneThen`` wrapped Cene function passing the given wrapped Cene value and proceeds by running the resulting JavaScript effects value.


.. _client.giveAsync():

client.giveAsync( ... )
-----------------------

Call from JavaScript with ``( val, cene (fn val) )``

Creates a wrapped Cene JavaScript effects value that asynchronously calls the given ``ceneThen`` wrapped Cene function passing the given wrapped Cene value (taking at least one JavaScript tick) and proceeds by running the resulting JavaScript effects value.


.. _client.defer():

client.defer( ... )
-------------------

Call from JavaScript with ``( function () )``

Schedules the given JavaScript callback to execute in a future JavaScript tick, then executes its resulting wrapped Cene JavaScript effects value in the same JavaScript tick, ignoring the result.