REPL-only functions
begin-tx
Use begin-tx
to begin a new transaction with an optional name.
Basic syntax
To begin a transaction without a name, use the following syntax:
(begin-tx)
(begin-tx)
To begin a transaction with a specific name, use the following syntax:
(begin-tx name)
(begin-tx name)
Arguments
Use the following argument to specify an optional name for the transaction when using the begin-tx
Pact function.
Argument | Type | Description |
---|---|---|
name | string | (Optional) Specifies the name of the transaction. |
Return value
The begin-tx
function returns a string indicating the transaction identifier and the optional name (if provided).
Examples
The following examples demonstrate the usage of the begin-tx
function within a Pact REPL:
- Beginning a transaction without a name:
pact> (begin-tx)"Begin Tx 0"
pact> (begin-tx)"Begin Tx 0"
- Beginning a transaction with a name:
pact> (begin-tx "load module")"Begin Tx 0: load module"
pact> (begin-tx "load module")"Begin Tx 0: load module"
By using begin-tx
, you can initiate a new transaction in Pact and optionally assign a name to it for better organization and tracking purposes.
commit-tx
Use commit-tx
to commit the current transaction.
Basic syntax
(commit-tx)
Arguments
The commit-tx
function does not take any arguments.
Return value
The commit-tx
function returns a string indicating the transaction identifier that has been committed.
Example
The following example demonstrates the usage of the commit-tx
function within a Pact REPL:
pact> (begin-tx) (commit-tx)"Commit Tx 0"
pact> (begin-tx) (commit-tx)"Commit Tx 0"
In this example, a new transaction is started using (begin-tx)
, and then (commit-tx)
is called to commit the transaction. The function returns a string indicating that "Tx 0" has been committed.
Note that commit-tx
should be used after performing the necessary operations within a transaction. Once commit-tx
is called, the transaction is finalized, and any changes made during the transaction are persisted.
It's important to ensure that commit-tx
is called after begin-tx
and any other transaction-related operations to properly commit the transaction. If commit-tx
is not called, the transaction will remain open and may lead to unexpected behavior or inconsistencies in the system.
continue-pact
Use continue-pact
to continue a previously-initiated pact identified by a specific step, with optional parameters for rollback, pact ID, and yielded value.
Basic syntax
To continue a pact with the specified step, use the following syntax:
(continue-pact step)
(continue-pact step)
To continue a pact with the specified step and rollback option, use the following syntax:
(continue-pact step rollback)
(continue-pact step rollback)
To continue a pact with the specified step, rollback option, and pact ID, use the following syntax:
(continue-pact step rollback pact-id)
(continue-pact step rollback pact-id)
To continue a pact with the specified step, rollback option, pact ID, and yielded value, use the following syntax:
(continue-pact step rollback pact-id yielded)
(continue-pact step rollback pact-id yielded)
Arguments
Use the following arguments to customize the behavior of the continue-pact
Pact function.
Argument | Type | Description |
---|---|---|
step | integer | Specifies the step of the pact to continue. |
rollback | bool | (Optional) Specifies whether to perform a rollback. Default is false . |
pact-id | string | (Optional) Specifies the ID of the pact to continue. Defaults to the pact initiated in the current transaction, if one is present. |
yielded | object | (Optional) Specifies the yielded value to be read with 'resume'. If not specified, uses the yield from the most recent pact execution, if any. The schema of the yielded object is object:<{y}> . |
Return value
The continue-pact
function returns a string indicating the result of continuing the pact.
Examples
The following examples demonstrate the usage of the continue-pact
function:
- Continue a pact with step 1:
(continue-pact 1)
(continue-pact 1)
- Continue a pact with step 1 and perform a rollback:
(continue-pact 1 true)
(continue-pact 1 true)
- Continue a pact with step 1, without rollback, and specify the pact ID:
(continue-pact 1 false "[pact-id-hash]")
(continue-pact 1 false "[pact-id-hash]")
- Continue a pact with step 2, without rollback, specify the pact ID, and provide a yielded value:
(continue-pact 2 false "[pact-id-hash]" { "rate": 0.9 })
(continue-pact 2 false "[pact-id-hash]" { "rate": 0.9 })
describe-module
Use describe-module
to get metadata for a specified MODULE
. This function returns an object with fields including name
, hash
, blessed
, code
, and keyset
.
Basic syntax
To get metadata for a MODULE
, use the following syntax:
(describe-module MODULE)
Arguments
Use the following argument to specify the MODULE
for the describe-module
Pact function.
Argument | Type | Description |
---|---|---|
module | string | Specifies the name of the module to describe. |
Return values
The describe-module
function returns an object with metadata for the specified MODULE
.
Examples
The following example demonstrates the describe-module
function:
pact>(module m G (defcap G () true))pact>(describe-module 'm){"hash":"0RpFOMAZ2787-fNFO6DokGf_V5WiSLMK10v4xnOymX0", "interfaces":[ ], "name":"m"}
pact>(module m G (defcap G () true))pact>(describe-module 'm){"hash":"0RpFOMAZ2787-fNFO6DokGf_V5WiSLMK10v4xnOymX0", "interfaces":[ ], "name":"m"}
In this example, (describe-module 'm)
is used to get metadata for the module named 'm'. The function returns an object providing detailed information about the module.
env-data
Use env-data
to set transaction JSON data, either as an encoded string or as Pact types coerced to JSON.
Basic syntax
(env-data json)
Arguments
Use the following argument to specify the JSON data when using the env-data
Pact function.
Argument | Type | Description |
---|---|---|
json | <a[integer,string,time,decimal,bool,[<l>],object:<{o}>,keyset]> | Specifies the JSON data to be set for the transaction. The data can be provided as an encoded string or as Pact types that will be coerced to JSON. |
Return value
The env-data
function returns a string indicating that the transaction data is being set.
Example
The following example demonstrates the usage of the env-data
function within a Pact REPL:
pact> (env-data { "keyset": { "keys": ["my-key" "admin-key"], "pred": "keys-any" } })"Setting transaction data"
pact> (env-data { "keyset": { "keys": ["my-key" "admin-key"], "pred": "keys-any" } })"Setting transaction data"
env-enable-repl-natives
Use env-enable-repl-natives
to control whether REPL native functions are allowed in module code.
Basic syntax
(env-enable-repl-natives enable)
Arguments
Use the following argument to specify whether to enable or disable REPL native functions in module code.
Argument | Type | Description |
---|---|---|
enable | bool | Specifies whether to enable or disable REPL native functions in module code. Set to true to enable, or false to disable. |
Return value
The env-enable-repl-natives
function returns a string indicating the status of REPL natives.
- If
enable
is set totrue
, it returns"Repl natives enabled"
. - If
enable
is set tofalse
, it returns"Repl natives disabled"
.
Behavior
When REPL native functions are enabled (enable
is set to true
), fixture functions like env-sigs
are allowed in module code. This means that you can use these functions within your module definitions.
On the other hand, when REPL native functions are disabled (enable
is set to false
), fixture functions are not allowed in module code, and attempting to use them will result in an error.
Example
The following example demonstrates enabling REPL native functions within a Pact REPL:
pact> (env-enable-repl-natives true)"Repl natives enabled"
pact> (env-enable-repl-natives true)"Repl natives enabled"
After enabling REPL natives, you can use fixture functions like env-sigs
within your module code.
It's important to note that enabling REPL native functions in module code should be done with caution, as it allows access to functions that are typically intended for use in the REPL environment only. Enable this feature only when necessary and ensure that the usage of REPL native functions in module code is properly controlled and validated.
env-events
Use env-events
to retrieve any accumulated events and optionally clear the event state.
Basic syntax
(env-events clear)
Arguments
Use the following argument to specify whether to clear the event state after retrieving the events.
Argument | Type | Description |
---|---|---|
clear | bool | Specifies whether to clear the event state after retrieving the events. Set to true to clear the event state, or false to keep the event state. |
Return value
The env-events
function returns an array of objects representing the accumulated events. Each object in the array has the following fields:
name
: The fully-qualified name of the event.params
: The parameters associated with the event.module-hash
: The hash of the module that emitted the event.
env-gas
Use env-gas
to query the current gas state or set it to a specific value.
Basic syntax
To query the current gas state, use the following syntax:
(env-gas)
To set the gas state to a specific value, use the following syntax:
(env-gas gas)
Arguments
Use the following argument to set the gas state when using the env-gas
Pact function.
Argument | Type | Description |
---|---|---|
gas | integer | (Optional) Specifies the value to set the gas state to. |
Return value
When called without arguments, env-gas
returns an integer representing the current gas state.
When called with the gas
argument, env-gas
returns a string indicating that the gas state has been set to the specified value.
Example
The following example demonstrates querying and setting the gas state within a Pact REPL:
pact> (env-gasmodel "table") (env-gaslimit 10) (env-gas 0) (map (+ 1) [1 2 3]) (env-gas)7
pact> (env-gasmodel "table") (env-gaslimit 10) (env-gas 0) (map (+ 1) [1 2 3]) (env-gas)7
env-gaslimit
Use env-gaslimit
to set the environment gas limit to a specific value.
Basic syntax
(env-gaslimit limit)
Arguments
Use the following argument to set the gas limit when using the env-gaslimit
Pact function.
Argument | Type | Description |
---|---|---|
limit | integer | Specifies the gas limit to set for the environment. |
Return value
The env-gaslimit
function returns a string indicating that the gas limit has been set to the specified value.
Examples
pact>(env-gaslimit 10)"Set gas limit to 10"
pact>(env-gaslimit 10)"Set gas limit to 10"
env-gasmodel
Use env-gasmodel
to update or query the current gas model.
Basic syntax
To update the gas model to a table-based cost model, use the following syntax:
(env-gasmodel model)
(env-gasmodel model)
To update the gas model to a fixed-rate model with a specific rate, use the following syntax:
(env-gasmodel model rate)
(env-gasmodel model rate)
To query the current gas model, use the following syntax:
(env-gasmodel)
(env-gasmodel)
Arguments
Use the following arguments when using the env-gasmodel
Pact function.
Argument | Type | Description |
---|---|---|
model | string | Specifies the gas model to set. Supported values are "table" and "fixed". |
Return value
When called with the model
argument, env-gasmodel
returns a string indicating the updated gas model.
When called without arguments, env-gasmodel
returns a string describing the current gas model.
Examples
The following examples demonstrate updating and querying the gas model within a Pact REPL:
- Querying the current gas model:
pact> (env-gasmodel)"Current gas model is 'unitGasModel': GasModel with constant cost MilliGas 0"
pact> (env-gasmodel)"Current gas model is 'unitGasModel': GasModel with constant cost MilliGas 0"
- Updating the gas model to a table-based cost model:
pact> (env-gasmodel 'table)"Set gas model to table-based cost model"
pact> (env-gasmodel 'table)"Set gas model to table-based cost model"
env-hash
Use env-hash
to set the current transaction hash.
Basic syntax
(env-hash hash)
(env-hash hash)
Arguments
Use the following argument when using the env-hash
Pact function.
Argument | Type | Description |
---|---|---|
hash | string | Specifies the hash value to set as the current transaction hash. The hash must be an unpadded base64-url encoded BLAKE2b 256-bit hash. |
Return value
The env-hash
function returns a string indicating that the transaction hash has been set to the specified value.
Example
The following example demonstrates setting the transaction hash within a Pact REPL:
pact> (env-hash (hash "hello"))"Set tx hash to Mk3PAn3UowqTLEQfNlol6GsXPe-kuOWJSCU0cbgbcs8"
pact> (env-hash (hash "hello"))"Set tx hash to Mk3PAn3UowqTLEQfNlol6GsXPe-kuOWJSCU0cbgbcs8"
env-keys (DEPRECATED)
Note: The env-keys
function is deprecated in favor of env-sigs
. It is recommended to use env-sigs
for setting transaction signer keys with associated capabilities.
Use env-keys
to set the transaction signer keys.
Basic syntax
(env-keys keys)
(env-keys keys)
Arguments
Use the following argument when using the env-keys
Pact function.
Argument | Type | Description |
---|---|---|
keys | [string] | Specifies the list of keys to set as transaction signer keys. |
Return value
The env-keys
function returns a string indicating that the transaction keys have been set.
Example
The following example demonstrates setting the transaction signer keys within a Pact REPL using env-keys
:
pact> (env-keys ["my-key" "admin-key"])"Setting transaction keys"
pact> (env-keys ["my-key" "admin-key"])"Setting transaction keys"
In this example, env-keys
is called with a list of two keys: "my-key" and "admin-key". The function sets these keys as the current transaction signer keys.
The function returns a string indicating that the transaction keys have been set.
env-namespace-policy
Use env-namespace-policy
to install a managed namespace policy.
Basic syntax
(env-namespace-policy allow-root ns-policy-fun)
(env-namespace-policy allow-root ns-policy-fun)
Arguments
Use the following arguments when using the env-namespace-policy
Pact function.
Argument | Type | Description |
---|---|---|
allow-root | bool | Specifies whether to allow root-level namespace creation. If set to true , root-level namespaces can be created. If set to false , root-level namespace creation is restricted. |
ns-policy-fun | ns:string ns-admin:guard -> bool | Specifies the namespace policy function. This function takes two arguments: ns (the namespace string) and ns-admin (the namespace admin guard), and returns a boolean value indicating whether the namespace is allowed based on the policy. The function should return true if the namespace is allowed, and false otherwise. |
Return value
The env-namespace-policy
function returns a string indicating that the namespace policy has been installed.
Example
The following example demonstrates installing a namespace policy within a Pact REPL:
(env-namespace-policy (my-ns-policy-fun))
(env-namespace-policy (my-ns-policy-fun))
env-sigs
Use env-sigs
to set transaction signature keys and their associated capabilities.
Basic syntax
(env-sigs sigs)
(env-sigs sigs)
Arguments
Use the following argument when using the env-sigs
Pact function.
Argument | Type | Description |
---|---|---|
sigs | [object] | Specifies the list of signature objects. Each object represents a signer key and its associated caps capabilities. |
Return value
The env-sigs
function returns a string indicating that the transaction signature keys and capabilities have been set.
Example
The following example demonstrates setting transaction signature keys and capabilities within a Pact REPL:
(env-sigs [{'key: "my-key", 'caps: [(accounts.USER_GUARD "my-account")]}, {'key: "admin-key", 'caps: []}])
(env-sigs [{'key: "my-key", 'caps: [(accounts.USER_GUARD "my-account")]}, {'key: "admin-key", 'caps: []}])
expect-failure
Use expect-failure
to evaluate an expression and succeed only if it throws an error.
Basic syntax
To expect a failure without specifying the error message, use the following syntax:
(expect-failure doc exp)
(expect-failure doc exp)
To expect a failure with a specific error message, use the following syntax:
(expect-failure doc err exp)
(expect-failure doc err exp)
Arguments
Use the following arguments when using the expect-failure
Pact function.
Argument | Type | Description |
---|---|---|
doc | string | Specifies the documentation string describing the expected failure. |
err | string | (Optional) Specifies the expected error message. |
exp | <a> | Specifies the expression to evaluate. The expression can be of any Pact type. |
Return value
The expect-failure
function returns a string indicating the success or failure of the expected failure.
- If the expression
exp
throws an error, the function returns a string indicating the success of the expected failure, e.g.,"Expect failure: success: Enforce fails on false"
. - If the expression
exp
does not throw an error, the function itself throws an error, indicating that the expected failure did not occur.
Examples
The following examples demonstrate the usage of expect-failure
within a Pact REPL:
- Expecting a failure without specifying the error message:
pact> (expect-failure "Enforce fails on false" (enforce false "Expected error"))"Expect failure: success: Enforce fails on false"
pact> (expect-failure "Enforce fails on false" (enforce false "Expected error"))"Expect failure: success: Enforce fails on false"
- Expecting a failure with a specific error message:
pact> (expect-failure "Enforce fails with message" "Expected error" (enforce false "Expected error"))"Expect failure: success: Enforce fails with message"
pact> (expect-failure "Enforce fails with message" "Expected error" (enforce false "Expected error"))"Expect failure: success: Enforce fails with message"
expect-that
Use expect-that
to evaluate an expression and succeed if the resulting value passes a predicate function.
Basic syntax
(expect-that doc pred exp)
(expect-that doc pred exp)
Arguments
Use the following arguments when using the expect-that
Pact function.
Argument | Type | Description |
---|---|---|
doc | string | Specifies the documentation string describing the expectation. |
pred | value:<a> -> bool | Specifies the predicate function that takes the result of exp and returns a boolean. |
exp | <a> | Specifies the expression to evaluate. The expression can be of any Pact type. |
Return value
The expect-that
function returns a string indicating the success or failure of the expectation.
Examples
The following examples demonstrate the usage of expect-that
within a Pact REPL:
- Expectation passes:
pact> (expect-that "addition" (< 2) (+ 1 2))"Expect-that: success: addition"
pact> (expect-that "addition" (< 2) (+ 1 2))"Expect-that: success: addition"
- Expectation fails:
pact> (expect-that "addition" (> 2) (+ 1 2))"FAILURE: addition: did not satisfy (> 2) : 3:integer"
pact> (expect-that "addition" (> 2) (+ 1 2))"FAILURE: addition: did not satisfy (> 2) : 3:integer"
expect
Use expect
to evaluate an expression and verify that the result equals an expected value.
Basic syntax
(expect doc expected actual)
(expect doc expected actual)
Arguments
Use the following arguments when using the expect
Pact function.
Argument | Type | Description |
---|---|---|
doc | string | Specifies the documentation string describing the expectation. |
expected | <a> | Specifies the expected value to compare against the result of actual . |
actual | <a> | Specifies the expression to evaluate. The expression can be of any Pact type. |
Return value
The expect
function returns a string indicating the success or failure of the expectation.
Example
The following example demonstrates the usage of expect
within a Pact REPL:
pact> (expect "Sanity prevails." 4 (+ 2 2))"Expect: success: Sanity prevails."
pact> (expect "Sanity prevails." 4 (+ 2 2))"Expect: success: Sanity prevails."