@ -71,6 +71,26 @@ The `_data/cliRef.json` file is generated from the `blockstack-cli` subcommand `
3. Make sure the generated docs are clean.
## Clarity Command Line
As of 8/19 Clarity is in the [develop](https://github.com/blockstack/blockstack-core/tree/develop) branch of core. You can build the Clarity command line from the Docker image.
"description":"The `let` function accepts a list of `variable name` and `expression` pairs,\nevaluating each expression and _binding_ it to the corresponding variable name. The _context_\ncreated by this set of bindings is used for evaluating and return the value of `expr-body`.",
"description":"The `let` function accepts a list of `variable name` and `expression` pairs,\nevaluating each expression and _binding_ it to the corresponding variable name. The _context_\ncreated by this set of bindings is used for evaluating its body expressions. The let expression returns the value of the last such body expression.",
"example":"(let ((a 2) (b (+ 5 6 7))) (print a) (print b) (+ a b)) ;; Returns 20"
},
{
"name":"fetch-var",
@ -177,23 +178,23 @@
},
{
"name":"fetch-entry",
"input_type":"MapName, Tuple",
"output_type":"Optional(Tuple)",
"input_type":"MapName, tuple",
"output_type":"(optional (tuple))",
"signature":"(fetch-entry map-name key-tuple)",
"description":"The `fetch-entry` function looks up and returns an entry from a contract's data map.\nThe value is looked up using `key-tuple`.\nIf there is no value associated with that key in the data map, the function returns a (none) option. Otherwise,\nit returns (some value)",
"example":"(expects! (fetch-entry names-map (tuple (name \"blockstack\"))) (err 1)) ;; Returns (tuple (id 1337))\n(expects! (fetch-entry names-map ((name \"blockstack\"))) (err 1)) ;; Same command, using a shorthand for constructing the tuple\n"
"description":"The `fetch-contract-entry` function looks up and returns an entry from a\ncontract other than the current contract's data map. The value is looked up using `key-tuple`.\nIf there is no value associated with that key in the data map, the function returns a (none) option. Otherwise,\nit returns (some value).",
"example":"(expects! (fetch-contract-entry names-contract names-map (tuple (name \"blockstack\")) (err 1))) ;; Returns (tuple (id 1337))\n(expects! (fetch-contract-entry names-contract names-map ((name \"blockstack\")) (err 1)));; Same command, using a shorthand for constructing the tuple\n"
"description":"The `set-entry!` function sets the value associated with the input key to the \ninputted value. This function performs a _blind_ update; whether or not a value is already associated\nwith the key, the function overwrites that existing association.",
"description":"The `insert-entry!` function sets the value associated with the input key to the \ninputted value if and only if there is not already a value associated with the key in the map.\nIf an insert occurs, the function returns `true`. If a value already existed for\nthis key in the data map, the function returns `false`.",
@ -209,7 +210,7 @@
},
{
"name":"delete-entry!",
"input_type":"MapName, Tuple",
"input_type":"MapName, tuple",
"output_type":"bool",
"signature":"(delete-entry! map-name key-tuple)",
"description":"The `delete-entry!` function removes the value associated with the input key for\nthe given map. If an item exists and is removed, the function returns `true`.\nIf a value did not exist for this key in the data map, the function returns `false`.",
@ -217,16 +218,16 @@
},
{
"name":"tuple",
"input_type":"(list (KeyName AnyType))",
"output_type":"Tuple",
"input_type":"(key-name A), (key-name-2 B), ...",
"output_type":"(tuple (key-name A) (key-name-2 B) ...)",
"description":"The `tuple` function constructs a typed tuple from the supplied key and expression pairs.\nA `get` function can use typed tuples as input to select specific values from a given tuple.\nKey names may not appear multiple times in the same tuple definition. Supplied expressions are evaluated and\nassociated with the expressions' paired key name.",
"example":"(tuple (name \"blockstack\") (id 1337))"
},
{
"name":"get",
"input_type":"KeyName and Tuple | Optional(Tuple)",
"description":"The `get` function fetches the value associated with a given key from the supplied typed tuple.\nIf an `Optional` value is supplied as the inputted tuple, `get` returns an `Optional` type of the specified key in\nthe tuple. If the supplied option is a `(none)` option, get returns `(none)`.",
"example":"(get id (tuple (name \"blockstack\") (id 1337))) ;; Returns 1337\n(get id (fetch-entry names-map (tuple (name \"blockstack\")))) ;; Returns (some 1337)\n(get id (fetch-entry names-map (tuple (name \"non-existent\")))) ;; Returns (none)\n"
"description":"The `contract-call!` function executes the given public function of the given contract.\nYou _may not_ this function to call a public function defined in the current contract. If the public\nfunction returns _err_, any database changes resulting from calling `contract-call!` are aborted.\nIf the function returns _ok_, database changes occurred.",
"example":"(contract-call! tokens transfer 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 19) ;; Returns (ok 1)"
@ -284,7 +285,7 @@
"input_type":"A",
"output_type":"A",
"signature":"(as-contract expr)",
"description":"The `as-contract` function switches the current context's `tx-sender` value to the _contract's_ \nprincipal and executes `expr` with that context. It returns the resulting value of `expr`.",
"description":"The `as-contract` function switches the current context's `tx-origin` value to the _contract's_ \nprincipal and executes `expr` with that context. It returns the resulting value of `expr`.",
"description":"The `ok` function constructs a response type from the input value. Use `ok` for\ncreating return values in public functions. An _ok_ value indicates that any database changes during\nthe processing of the function should materialize.",
"example":"(ok 1) ;; Returns (ok 1)"
@ -306,14 +307,22 @@
{
"name":"err",
"input_type":"A",
"output_type":"Response(A,B)",
"output_type":"(response A B)",
"signature":"(err value)",
"description":"The `err` function constructs a response type from the input value. Use `err` for\ncreating return values in public functions. An _err_ value indicates that any database changes during\nthe processing of the function should be rolled back.",
"example":"(err 'true) ;; Returns (err 'true)"
},
{
"name":"some",
"input_type":"A",
"output_type":"(optional A)",
"signature":"(some value)",
"description":"The `some` function constructs a `optional` type from the input value.",
"description":"The `default-to` function attempts to 'unpack' the second argument: if the argument is\na `(some ...)` option, it returns the inner value of the option. If the second argument is a `(none)` value,\n`default-to` it returns the value of `default-value`.",
"description":"The `expects!` function attempts to 'unpack' the first argument: if the argument is\nan option type, and the argument is a `(some ...)` option, `expects!` returns the inner value of the\noption. If the argument is a response type, and the argument is an `(ok ...)` response, `expects!` returns\n the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value,\n`expects!` _returns_ `thrown-value` from the current function and exits the current control-flow.",
"description":"The `expects-err!` function attempts to 'unpack' the first argument: if the argument\nis an `(err ...)` response, `expects-err!` returns the inner value of the `err`.\nIf the supplied argument is an `(ok ...)` value,\n`expects-err!` _returns_ `thrown-value` from the current function and exits the current control-flow.",
@ -337,7 +346,7 @@
},
{
"name":"is-ok?",
"input_type":"Response(A,B)",
"input_type":"(response A B)",
"output_type":"bool",
"signature":"(is-ok? value)",
"description":"`is-ok?` tests a supplied response value, returning `true` if the response was `ok`,\nand `false` if it was an `err`.",
@ -345,7 +354,7 @@
},
{
"name":"is-none?",
"input_type":"Optional(A)",
"input_type":"(optional A)",
"output_type":"bool",
"signature":"(is-none? value)",
"description":"`is-none?` tests a supplied option value, returning `true` if the option value is `(none)`,\nand `false` if it is a `(some ...)`.",
@ -359,6 +368,70 @@
"description":"The `filter` function applies the input function `func` to each element of the\ninput list, and returns the same list with any elements removed for which the `func` returned `false`.",
"description":"`nft-mint!` is used to instantiate an asset and set that asset's owner to the `recipient` principal.\nThe asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in\nthat definition.\n\nIf an asset identified by `asset-identifier` _already exists_, this function will return an error with the following error code:\n\n`(err 1)`\n\nOtherwise, on successfuly mint, it returns `(ok 'true)`.\n",
"description":"`ft-mint!` is used to increase the token balance for the `recipient` principal for a token\ntype defined using `define-fungible-token`. The increased token balance is _not_ transfered from another principal, but\nrather minted.\n\nIf a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfuly mint, it\nreturns `(ok 'true)`.\n",
"description":"`nft-transfer!` is used to change the owner of an asset identified by `asset-identifier`\nfrom `sender` to `recipient`. The `asset-class` must have been defined by `define-non-fungible-token` and `asset-identifier`\nmust be of the type specified in that definition.\n\nThis function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns\none of the following error codes:\n\n`(err 1)` -- `sender` does not own the asset\n`(err 2)` -- `sender` and `recipient` are the same principal\n`(err 3)` -- asset identified by asset-identifier does not exist\n",
"description":"`ft-transfer!` is used to increase the token balance for the `recipient` principal for a token\ntype defined using `define-fungible-token` by debiting the `sender` principal.\n\nThis function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns\none of the following error codes:\n\n`(err 1)` -- `sender` does not have enough balance to transfer\n`(err 2)` -- `sender` and `recipient` are the same principal\n`(err 3)` -- amount to send is non-positive\n",
"description":"`ft-get-balance` returns `token-name` balance of the principal `principal`.\nThe token type must have been defined using `define-fungible-token`.",
"description":"`nft-get-owner` returns the owner of an asset, identified by `asset-identifier`, or `none` if the asset does not exist.\nThe asset type must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in\nthat definition.",
"description":"`define-non-fungible-token` is used to define a new non-fungible token class for use in the current contract.\nIndividual assets are identified by their asset identifier, which must be of the type `asset-identifier-type`. Asset\nidentifiers are _unique_ identifiers.\n\nLike other kinds of definition statements, `define-non-fungible-token` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).\n\nAssets defined using `define-non-fungible-token` may be used in `nft-transfer!`, `nft-mint!`, and `nft-get-owner` functions",
"description":"`define-fungible-token` is used to define a new fungible token class for use in the current contract.\n\nThe second argument, if supplied, defines the total supply of the fungible token. This ensures that all calls to the `ft-mint!`\nfunction will never be able to create more than `total-supply` tokens. If any such call were to increase the total supply\nof tokens passed that amount, that invocation of `ft-mint!` will result in a runtime error and abort.\n\nLike other kinds of definition statements, `define-fungible-token` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).\n\nTokens defined using `define-fungible-token` may be used in `ft-transfer!`, `ft-mint!`, and `ft-get-balance` functions",
"description":"`define-read-only` is used to define a _public read-only_ function for a smart contract. Such\nfunctions are callable from other smart contracts.\n\nLike other kinds of definition statements, `define-read-only` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).\n\nRead-only functions may return any type. However, read-only functions\nmay not perform any datamap modifications, or call any functions which\nperform such modifications. This is enforced both during type checks and during\nthe execution of the function. Public read-only functions may\nbe invoked by other contracts via `contract-call!`.",
"description":"Returns the caller of the current contract context. If this contract is the first one called by a signed transaction, \nthe caller will be equal to the signing principal. If `contract-call!` was used to invoke a function from a new contract, `contract-caller`\nchanges to the _calling_ contract's principal. If `as-contract` is used to change the `tx-sender` context, `contract-caller` _also_ changes\nto the same contract principal.",
"example":"(print contract-caller) ;; Will print out a Stacks address of the transaction sender"
},
{
"name":"tx-sender",
"output_type":"principal",
"description":"Returns the original sender of the current transaction, or if `as-contract` was called to modify the sending context, it returns that\ncontract principal.",
"example":"(print tx-sender) ;; Will print out a Stacks address of the transaction sender"
},
{
"name":"block-height",
"output_type":"int",
"description":"Returns the current block height of the Stacks blockchain as an int",
"example":"(> block-height 1000) ;; returns true if the current block-height has passed 1000 blocks."
},
{
"name":"none",
"output_type":"(optional ?)",
"description":"Represents the _none_ option indicating no value for a given optional (analogous to a null value).",
Mary Anthony
5 years ago