# Introduction
This is the in-development version of `chinillaclvm_tools` for chinillaclvm, which implements, a LISP-like language for encumbering and releasing funds with smart-contract capabilities.
# Set up
Set up your virtual environments
$ python3 -m venv venv
$ . ./venv/bin/activate (windows: venv\Scripts\activate.bat)
$ pip install -e .
If you run into any issues, be sure to check out [this section of the wiki](https://github.com/chinilla/chinilla-blockchain/wiki/Help-with-chinillaclvm_tools)
Optionally, run unit tests for a sanity check.
$ pip install pytest
$ py.test tests
# Quick examples
The language has two components: the higher level language and the compiled lower level language which runs on the chinillaclvm.
To compile the higher level language into the lower level language use:
$ run '(mod ARGUMENT (+ ARGUMENT 3))'
(+ 1 (q . 3))
To execute this code:
$ brun '(+ 1 (q . 3))' '2'
5
# The Compiler
## Basic example
The high level language is a superset of [chinillaclvm](https://github.com/chinilla/chinillaclvm), adding several operators. The main supported operator is `mod` which lets you define a set of macros and functions, and an entry point that calls them. Here's an example.
(mod (INDEX)
(defun factorial (VALUE) (if (= VALUE 1) 1 (* VALUE (factorial (- VALUE 1)))))
(factorial INDEX)
)
You can copy this to a file `fact.chinillaclvm`, then compile it with `run fact.chinillaclvm` and you'll see output like
`(a (q 2 2 (c 2 (c 5 ()))) (c (q 2 (i (= 5 (q . 1)) (q 1 . 1) (q 18 5 (a 2 (c 2 (c (- 5 (q . 1)) ()))))) 1) 1))`
You can then run this code with `brun`, passing in a parameter. Or pipe it using this `bash` quoting trick:
$ brun "`run fact.chinillaclvm`" "(5)"
120
This affirms that 5! = 120.
### Auto-quoting of literals
Note that the `1` is not quoted. The compiler recognizes and auto-quotes constant values.
$ run 15
15
$ brun 15
FAIL: not a list 15
## Known operators
Besides `mod` and `defun`, the compiler has a few more built-in operators:
### @
Instead of evaluating `1` to return the arguments, you should use `@` in the higher level language.
This is easier for humans to read, and calling `(f @)` will be compiled to 2, etc.
```
$ run '@' '("example" 200)'
("example" 200)
$ run '(mod ARGS (f (r @)))'
5
```
You generally won't need to use `@`; it's better to use `mod` and named arguments.
### (if)
`(if A B C)`
This operator is similar to lone condition in chinillaclvm `i`, except it actually does a lazy evaluation of either B or C (depending upon A). This allows you to put expensive or failing (like `x`) operator within branches, knowing they won't be executed unless required.
This is implemented as a macro, and expands out to `((c (i A (q B) (q C)) (a)))`.
### (qq) and (unquote)
`(qq EXPR)` for expanding templates. This is generally for creating your own operators that end up being inline functions.
Everything in `EXPR` is quoted literally, unless it's wrapped by a unary `unquote` operator, in which case, it's evaluated. So
`(qq (+ 5 (a)))` would expand to `(+ 5 (a))`
But `(qq (+ 5 (unquote (+ 9 10))))` would expand to `(+ 5 19)` because `(+ 9 10)` is `19`.
And `(qq (+ 5 (unquote (+ 1 (a)))))` expands to something that depends on what `(a)` is in the context it's evaluated. (It'd better be a number so 1 can be added to it!)
If you have a template expression and you want to substitute values into it, this is what you use.
## Macros
You can also define macros within a module, which act as inline functions. When a previously defined macro operator is encountered, it "rewrites" the existing statement using the macro, passing along the arguments as literals (ie. they are not evaluated).
### A Simple Example
(mod (VALUE1 VALUE2)
(defmacro sum (A B) (qq (+ (unquote A) (unquote B))))
(sum VALUE1 VALUE2)
)
When `run`, this produces the following output:
`(+ 2 5)`
Compare to the function version:
(mod (VALUE1 VALUE2)
(defun sum (A B) (+ A B))
(sum VALUE1 VALUE2)
)
which produces
`(a (q 2 2 (c 2 (c 5 (c 11 ())))) (c (q 16 5 11) 1))`
There's a lot more going on here, setting up an environment where sum would be allowed to call itself recursively.
### Inline functions
If you want to write a function that is always inlined, use `defun-inline`.
(mod (VALUE1 VALUE2)
(defun-inline sum (A B) (+ A B))
(sum VALUE1 VALUE2)
)
This produces the much more compact output `(+ 2 5)`.
Inline functions *must not* be recursive.
### A More Complex Example
Here's an example, demonstrating how `if` is defined.
(mod (VALUE1 VALUE2)
(defmacro my_if (A B C)
(qq ((c
(i (unquote A)
(function (unquote B))
(function (unquote C)))
(a)))))
(my_if (= (+ VALUE1 VALUE2) 10) "the sum is 10" "the sum is not 10")
)
This produces
`((c (i (= (+ 2 5) (q 10)) (q (q "the sum is 10")) (q (q "the sum is not 10"))) 1))`
which is not much code, for how much source there is. This also demonstrates the general notion that macros (and inline functions) cause much less code bloat than functions. The main disadvantages is that macros are not recursive (since they run at compile time) and they're messier to write.
Raw data
{
"_id": null,
"home_page": "https://github.com/chinilla",
"name": "chinillaclvm-tools",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Chinilla Network, Inc.",
"author_email": "kiss@chinilla.net",
"download_url": "",
"platform": null,
"description": "# Introduction\n\nThis is the in-development version of `chinillaclvm_tools` for chinillaclvm, which implements, a LISP-like language for encumbering and releasing funds with smart-contract capabilities.\n\n\n# Set up\n\nSet up your virtual environments\n\n $ python3 -m venv venv\n $ . ./venv/bin/activate (windows: venv\\Scripts\\activate.bat)\n $ pip install -e .\n\nIf you run into any issues, be sure to check out [this section of the wiki](https://github.com/chinilla/chinilla-blockchain/wiki/Help-with-chinillaclvm_tools)\n\nOptionally, run unit tests for a sanity check.\n\n $ pip install pytest\n $ py.test tests\n\n\n# Quick examples\n\nThe language has two components: the higher level language and the compiled lower level language which runs on the chinillaclvm.\nTo compile the higher level language into the lower level language use:\n\n $ run '(mod ARGUMENT (+ ARGUMENT 3))'\n (+ 1 (q . 3))\n\nTo execute this code:\n\n $ brun '(+ 1 (q . 3))' '2'\n 5\n\n\n# The Compiler\n\n\n## Basic example\n\nThe high level language is a superset of [chinillaclvm](https://github.com/chinilla/chinillaclvm), adding several operators. The main supported operator is `mod` which lets you define a set of macros and functions, and an entry point that calls them. Here's an example.\n\n (mod (INDEX)\n (defun factorial (VALUE) (if (= VALUE 1) 1 (* VALUE (factorial (- VALUE 1)))))\n (factorial INDEX)\n )\n\nYou can copy this to a file `fact.chinillaclvm`, then compile it with `run fact.chinillaclvm` and you'll see output like\n\n`(a (q 2 2 (c 2 (c 5 ()))) (c (q 2 (i (= 5 (q . 1)) (q 1 . 1) (q 18 5 (a 2 (c 2 (c (- 5 (q . 1)) ()))))) 1) 1))`\n\nYou can then run this code with `brun`, passing in a parameter. Or pipe it using this `bash` quoting trick:\n\n $ brun \"`run fact.chinillaclvm`\" \"(5)\"\n 120\n\nThis affirms that 5! = 120.\n\n\n### Auto-quoting of literals\n\nNote that the `1` is not quoted. The compiler recognizes and auto-quotes constant values.\n\n $ run 15\n 15\n $ brun 15\n FAIL: not a list 15\n\n## Known operators\n\nBesides `mod` and `defun`, the compiler has a few more built-in operators:\n\n### @\n\nInstead of evaluating `1` to return the arguments, you should use `@` in the higher level language.\nThis is easier for humans to read, and calling `(f @)` will be compiled to 2, etc.\n\n```\n $ run '@' '(\"example\" 200)'\n (\"example\" 200)\n \n $ run '(mod ARGS (f (r @)))'\n 5\n```\n\nYou generally won't need to use `@`; it's better to use `mod` and named arguments.\n\n\n### (if)\n\n`(if A B C)`\nThis operator is similar to lone condition in chinillaclvm `i`, except it actually does a lazy evaluation of either B or C (depending upon A). This allows you to put expensive or failing (like `x`) operator within branches, knowing they won't be executed unless required.\n\nThis is implemented as a macro, and expands out to `((c (i A (q B) (q C)) (a)))`.\n\n\n### (qq) and (unquote)\n\n`(qq EXPR)` for expanding templates. This is generally for creating your own operators that end up being inline functions.\n\nEverything in `EXPR` is quoted literally, unless it's wrapped by a unary `unquote` operator, in which case, it's evaluated. So\n\n`(qq (+ 5 (a)))` would expand to `(+ 5 (a))`\n\nBut `(qq (+ 5 (unquote (+ 9 10))))` would expand to `(+ 5 19)` because `(+ 9 10)` is `19`.\n\nAnd `(qq (+ 5 (unquote (+ 1 (a)))))` expands to something that depends on what `(a)` is in the context it's evaluated. (It'd better be a number so 1 can be added to it!)\n\nIf you have a template expression and you want to substitute values into it, this is what you use.\n\n\n## Macros\n\nYou can also define macros within a module, which act as inline functions. When a previously defined macro operator is encountered, it \"rewrites\" the existing statement using the macro, passing along the arguments as literals (ie. they are not evaluated).\n\n\n### A Simple Example\n\n (mod (VALUE1 VALUE2)\n (defmacro sum (A B) (qq (+ (unquote A) (unquote B))))\n (sum VALUE1 VALUE2)\n )\n\nWhen `run`, this produces the following output:\n\n`(+ 2 5)`\n\nCompare to the function version:\n\n (mod (VALUE1 VALUE2)\n (defun sum (A B) (+ A B))\n (sum VALUE1 VALUE2)\n )\n\nwhich produces\n\n`(a (q 2 2 (c 2 (c 5 (c 11 ())))) (c (q 16 5 11) 1))`\n\nThere's a lot more going on here, setting up an environment where sum would be allowed to call itself recursively.\n\n### Inline functions\n\nIf you want to write a function that is always inlined, use `defun-inline`.\n\n\n (mod (VALUE1 VALUE2)\n (defun-inline sum (A B) (+ A B))\n (sum VALUE1 VALUE2)\n )\n\nThis produces the much more compact output `(+ 2 5)`.\n\nInline functions *must not* be recursive.\n\n\n### A More Complex Example\n\nHere's an example, demonstrating how `if` is defined.\n\n (mod (VALUE1 VALUE2)\n (defmacro my_if (A B C)\n (qq ((c\n \t (i (unquote A)\n \t (function (unquote B))\n \t (function (unquote C)))\n \t (a)))))\n (my_if (= (+ VALUE1 VALUE2) 10) \"the sum is 10\" \"the sum is not 10\")\n )\n\nThis produces\n\n`((c (i (= (+ 2 5) (q 10)) (q (q \"the sum is 10\")) (q (q \"the sum is not 10\"))) 1))`\n\nwhich is not much code, for how much source there is. This also demonstrates the general notion that macros (and inline functions) cause much less code bloat than functions. The main disadvantages is that macros are not recursive (since they run at compile time) and they're messier to write.\n",
"bugtrack_url": null,
"license": "https://opensource.org/licenses/Apache-2.0",
"summary": "CHINILLACLVM compiler.",
"version": "0.4.7",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "b9749bc728f43db7c77c153ddb4660c8",
"sha256": "aae099d82c8ba659f257d5ee563104f57c6830960ac5f30c478c0b833ca7383a"
},
"downloads": -1,
"filename": "chinillaclvm_tools-0.4.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b9749bc728f43db7c77c153ddb4660c8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 36037,
"upload_time": "2022-12-10T04:44:31",
"upload_time_iso_8601": "2022-12-10T04:44:31.675673Z",
"url": "https://files.pythonhosted.org/packages/c6/53/261c22c20d941d42194c1b0631151a617306fdf9a8e5c026502eaa0f05f8/chinillaclvm_tools-0.4.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-10 04:44:31",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "chinillaclvm-tools"
}
JSON