balsoft/ligo
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Change LIGO documentation introduction to be about LIGO

Browse Source
This commit is contained in:
John David Pressman 2020-02-26 03:27:11 -08:00
parent f39ff186d6
commit f2bff77ffd
4 changed files with 176 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

139
gitlab-pages/docs/intro/what-and-why.md → gitlab-pages/docs/advanced/michelson.md
View File

@ -1,19 +1,19 @@
--- ---
id: what-and-why id: michelson-and-ligo
title: Michelson and LIGO title: Michelson and LIGO
--- ---
Before we get into what LIGO is and why LIGO needs to exist, let us Currently LIGO compiles to [Michelson](https://tezos.gitlab.io/whitedoc/michelson.html),
take a look at what options the Tezos blockchain offers us out of the the native smart contract language supported by Tezos. This page explains the
box. If you want to implement smart contracts natively on Tezos, you relationship between LIGO and the underlying Michelson it compiles to. Understanding
have to learn Michelson is not a requirement to use LIGO, but it does become important if you want
[Michelson](https://tezos.gitlab.io/whitedoc/michelson.html). to formally verify contracts using [Mi-Cho-Coq](https://gitlab.com/nomadic-labs/mi-cho-coq/)
or tune the performance of contracts outputted by the LIGO compiler.
**The rationale and design of Michelson** **The rationale and design of Michelson**
The language native to the Tezos blockchain for writing smart Michelson is a Domain-Specific Language (DSL) for writing Tezos smart contracts
contracts is *Michelson*, a Domain-Specific Language (DSL) inspired by inspired by Lisp and Forth. This unusual lineage aims at satisfying unusual
Lisp and Forth. This unusual lineage aims at satisfying unusual
constraints, but entails some tensions in the design. constraints, but entails some tensions in the design.
First, to measure stepwise gas consumption, *Michelson is interpreted*. First, to measure stepwise gas consumption, *Michelson is interpreted*.
@ -135,124 +135,3 @@ We cannot run Javascript on the Tezos blockchain, but we can choose
LIGO, which will abstract the stack management and allow us to create LIGO, which will abstract the stack management and allow us to create
readable, type-safe, and efficient smart contracts. readable, type-safe, and efficient smart contracts.
## LIGO for Programming Smart Contracts on Tezos
Perhaps the most striking feature of LIGO is that it comes in
different concrete syntaxes, and even different programming
paradigms. In other words, LIGO is not defined by one syntax and one
paradigm, like imperative versus functional.
- There is **PascaLIGO**, which is inspired by Pascal, hence is an
imperative language with lots of keywords, where values can be
locally mutated after they have been annotated with their types
(declaration).
- There is **CameLIGO**, which is inspired by the pure subset of
[OCaml](https://ocaml.org/), hence is a functional language with
few keywords, where values cannot be mutated, but still require
type annotations (unlike OCaml, whose compiler performs almost
full type inference).
- There is **ReasonLIGO**, which is inspired by the pure subset of
[ReasonML](https://reasonml.github.io/), which is based upon
OCaml.
Let us decline the same LIGO contract in the three flavours above. Do
not worry if it is a little confusing at first; we will explain all
the syntax in the upcoming sections of the documentation.
<!--DOCUSAURUS_CODE_TABS-->
<!--PascaLIGO-->
```pascaligo group=a
type storage is int
type parameter is
Increment of int
| Decrement of int
| Reset
type return is list (operation) * storage
function main (const action : parameter; const store : storage) : return is
((nil : list (operation)),
case action of
Increment (n) -> store + n
| Decrement (n) -> store - n
| Reset -> 0
end)
```
<!--CameLIGO-->
```cameligo group=a
type storage = int
type parameter =
Increment of int
| Decrement of int
| Reset
type return = operation list * storage
let main (action, store : parameter * storage) : return =
([] : operation list),
(match action with
Increment n -> store + n
| Decrement n -> store - n
| Reset -> 0)
```
<!--ReasonLIGO-->
```reasonligo group=a
type storage = int;
type parameter =
Increment (int)
| Decrement (int)
| Reset;
type return = (list (operation), storage);
let main = ((action, store): (parameter, storage)) : return => {
(([] : list (operation)),
(switch (action) {
| Increment (n) => store + n
| Decrement (n) => store - n
| Reset => 0}));
};
```
<!--END_DOCUSAURUS_CODE_TABS-->
<!--
> 💡 You can find the Michelson compilation output of the contract -->
<!--above in **`ligo-counter.tz`** -->
This LIGO contract behaves almost exactly* like the Michelson
contract we saw first, and it accepts the following LIGO expressions:
`Increment(n)`, `Decrement(n)` and `Reset`. Those serve as
`entrypoint` identification, same as `%add` `%sub` or `%default` in
the Michelson contract.
**The Michelson contract also checks if the `AMOUNT` sent is `0`*
---
## Runnable code snippets & exercises
Some of the sections in this documentation will include runnable code snippets and exercises. Sources for those are available at
the [LIGO Gitlab repository](https://gitlab.com/ligolang/ligo).
### Snippets
For example **code snippets** for the *Types* subsection of this doc, can be found here:
`gitlab-pages/docs/language-basics/src/types/**`
### Exercises
Solutions to exercises can be found e.g. here: `gitlab-pages/docs/language-basics/exercises/types/**/solutions/**`
### Running snippets / exercise solutions
In certain cases it makes sense to be able to run/evaluate the given snippet or a solution, usually there'll be an example command which you can use, such as:
```shell
ligo evaluate-value -s pascaligo gitlab-pages/docs/language-basics/src/variables-and-constants/const.ligo age
# Outputs: 25
```

163
gitlab-pages/docs/intro/ligo-intro.md Normal file
View File

@ -0,0 +1,163 @@
---
id: introduction
title: Introduction To LIGO
---
LIGO is a programming language for writing [Tezos](https://tezos.com/) smart contracts.
If we had to describe the philosophy of LIGO in a few sentences, it would be this:
1. Design a clean, simple language with no extraneous parts or additions.
2. Give that language multiple syntaxes borrowed from other languages so users don't
have to clutter their brain with Yet Another Notation for the same programming
concepts we've been using since the 1980's.
3. Have that simple language encourage people to write simple code, so that it's
easy to formally verify the compiled output using a project like [Mi-Cho-Coq](https://gitlab.com/nomadic-labs/mi-cho-coq/).
4. Stop waking up in the morning to find that your smart contract lost all its money
to some [stupid exploit](https://www.wired.com/2016/06/50-million-hack-just-showed-dao-human/).
We can elaborate on each:
* **Clean and simple** — Programming languages for making video games or websites
tend to prioritize accumulating a vast number of features, they're big languages for
making big projects. You use an army of mediocre programmers to write thousands
and thousands of lines of code, and then accelerate development by including dozens
or hundreds of unvetted dependencies; each of which provides an opportunity to
introduce a security exploit or insert malicious code. That's fine for a game, but
we don't think that's a very intelligent way to write a smart contract. Most useful
smart contracts can express their core functionality in under a thousand lines of
code, and the problem domain necessitates that you get as close as possible to
the minimal code size and resource use. LIGO is a functional language designed
to include the features you need, avoiding patterns that make formal verification
hard.
* **Multiple Syntaxes** — LIGO provides three syntaxes for users which express the
same underlying language semantics. PascaLIGO is an imperative syntax based on
[Pascal](https://en.wikipedia.org/wiki/Pascal_%28programming_language%29), CameLIGO
is a syntax which closely mimics the look and feel of [OCaml](https://en.wikipedia.org/wiki/OCaml),
and ReasonLIGO is based on Facebook's JavaScript-flavored [ReasonML](https://reasonml.github.io/) syntax.
* **Simple Code & Formal Verification** — LIGO doesn't use an object oriented paradigm,
currently code is organized using functions. While LIGO plans to have a module system
in the future, it's not the intent that this be used to create npm style cathedrals
of logical mystery meat. Once a contract is put on the blockchain, it's not possible
to change it. A new version can be uploaded, but the original contract remains
available. This makes formal verification of contract logic attractive. When the
cost of bugs is extreme and patches aren't possible it pays to get things right
the first time.
## LIGO for Programming Smart Contracts on Tezos
Perhaps the most striking feature of LIGO is that it comes in
different concrete syntaxes, and even different programming
paradigms. In other words, LIGO is not defined by one syntax and one
paradigm, like imperative versus functional.
- There is **PascaLIGO**, which is inspired by Pascal, hence is an
imperative language with lots of keywords, where values can be
locally mutated after they have been annotated with their types
(declaration).
- There is **CameLIGO**, which is inspired by the pure subset of
[OCaml](https://ocaml.org/), hence is a functional language with
few keywords, where values cannot be mutated, but still require
type annotations (unlike OCaml, whose compiler performs almost
full type inference).
- There is **ReasonLIGO**, which is inspired by the pure subset of
[ReasonML](https://reasonml.github.io/), which is based upon
OCaml.
Let's define some LIGO contract in the three flavours above. Do
not worry if it is a little confusing at first; we will explain all
the syntax in the upcoming sections of the documentation.
<!--DOCUSAURUS_CODE_TABS-->
<!--PascaLIGO-->
```pascaligo group=a
type storage is int
type parameter is
Increment of int
| Decrement of int
| Reset
type return is list (operation) * storage
function main (const action : parameter; const store : storage) : return is
((nil : list (operation)),
case action of
Increment (n) -> store + n
| Decrement (n) -> store - n
| Reset -> 0
end)
```
<!--CameLIGO-->
```cameligo group=a
type storage = int
type parameter =
Increment of int
| Decrement of int
| Reset
type return = operation list * storage
let main (action, store : parameter * storage) : return =
([] : operation list),
(match action with
Increment n -> store + n
| Decrement n -> store - n
| Reset -> 0)
```
<!--ReasonLIGO-->
```reasonligo group=a
type storage = int;
type parameter =
Increment (int)
| Decrement (int)
| Reset;
type return = (list (operation), storage);
let main = ((action, store): (parameter, storage)) : return => {
(([] : list (operation)),
(switch (action) {
| Increment (n) => store + n
| Decrement (n) => store - n
| Reset => 0}));
};
```
<!--END_DOCUSAURUS_CODE_TABS-->
This LIGO contract accepts the following LIGO expressions:
`Increment(n)`, `Decrement(n)` and `Reset`. Those serve as
`entrypoint` identification.
---
## Runnable code snippets & exercises
Some of the sections in this documentation will include runnable code snippets and exercises. Sources for those are available at
the [LIGO Gitlab repository](https://gitlab.com/ligolang/ligo).
### Snippets
For example **code snippets** for the *Types* subsection of this doc, can be found here:
`gitlab-pages/docs/language-basics/src/types/**`
### Exercises
Solutions to exercises can be found e.g. here: `gitlab-pages/docs/language-basics/exercises/types/**/solutions/**`
### Running snippets / exercise solutions
In certain cases it makes sense to be able to run/evaluate the given snippet or a solution, usually there'll be an example command which you can use, such as:
```shell
ligo evaluate-value -s pascaligo gitlab-pages/docs/language-basics/src/variables-and-constants/const.ligo age
# Outputs: 25
```

5
gitlab-pages/website/sidebars.json
View File

@ -1,6 +1,6 @@
{ {
"docs": { "docs": {
"Intro": ["intro/what-and-why", "intro/installation", "intro/editor-support"], "Intro": ["intro/introduction", "intro/installation", "intro/editor-support"],
"Language Basics": [ "Language Basics": [
"language-basics/types", "language-basics/types",
"language-basics/constants-and-variables", "language-basics/constants-and-variables",
@ -18,7 +18,8 @@
"advanced/timestamps-addresses", "advanced/timestamps-addresses",
"advanced/entrypoints-contracts", "advanced/entrypoints-contracts",
"advanced/include", "advanced/include",
"advanced/first-contract" "advanced/first-contract",
"advanced/michelson-and-ligo"
], ],
"API & Reference": [ "API & Reference": [
"api/cli-commands", "api/cli-commands",

2
gitlab-pages/website/siteConfig.js
View File

@ -23,7 +23,7 @@ const siteConfig = {
headerLinks: [ headerLinks: [
{ href: 'https://ide.ligolang.org/', label: 'Try Online' }, { href: 'https://ide.ligolang.org/', label: 'Try Online' },
{ doc: 'intro/installation', label: 'Install' }, { doc: 'intro/installation', label: 'Install' },
{ doc: 'intro/what-and-why', label: 'Docs' }, { doc: 'intro/introduction', label: 'Docs' },
{ {
doc: 'tutorials/get-started/tezos-taco-shop-smart-contract', doc: 'tutorials/get-started/tezos-taco-shop-smart-contract',
label: 'Tutorials' label: 'Tutorials'