From 15ab06bb66996a1862c925031e5bb44be8e02e67 Mon Sep 17 00:00:00 2001 From: Matej Sima Date: Tue, 11 Jun 2019 03:37:12 +0200 Subject: [PATCH] Added a lot of docs --- .../docs/language-basics-entrypoints.md | 44 ------------ .../docs/language-basics-functions.md | 22 ------ .../docs/language-basics-variables.md | 18 ----- .../docs/language-basics/cheat-sheet.md | 37 ++++++++++ .../docs/language-basics/entrypoints.md | 46 ++++++++++++ .../docs/language-basics/functions.md | 43 +++++++++++ .../operators.md} | 4 +- gitlab-pages/docs/language-basics/types.md | 72 +++++++++++++++++++ .../docs/language-basics/variables.md | 40 +++++++++++ gitlab-pages/docs/setup/editor-support.md | 8 +++ .../installation.md} | 7 +- gitlab-pages/website/pages/en/index.js | 4 +- gitlab-pages/website/pages/en/versions.js | 6 +- gitlab-pages/website/sidebars.json | 4 +- gitlab-pages/website/siteConfig.js | 2 +- gitlab-pages/website/static/css/custom.css | 35 ++++++--- .../language-basics-entrypoints.md | 4 +- .../version-next/setup-installation.md | 39 ---------- .../version-next-sidebars.json | 13 ++-- 19 files changed, 293 insertions(+), 155 deletions(-) delete mode 100644 gitlab-pages/docs/language-basics-entrypoints.md delete mode 100644 gitlab-pages/docs/language-basics-functions.md delete mode 100644 gitlab-pages/docs/language-basics-variables.md create mode 100644 gitlab-pages/docs/language-basics/cheat-sheet.md create mode 100644 gitlab-pages/docs/language-basics/entrypoints.md create mode 100644 gitlab-pages/docs/language-basics/functions.md rename gitlab-pages/docs/{language-basics-operators.md => language-basics/operators.md} (80%) create mode 100644 gitlab-pages/docs/language-basics/types.md create mode 100644 gitlab-pages/docs/language-basics/variables.md create mode 100644 gitlab-pages/docs/setup/editor-support.md rename gitlab-pages/docs/{setup-installation.md => setup/installation.md} (97%) delete mode 100644 gitlab-pages/website/versioned_docs/version-next/setup-installation.md diff --git a/gitlab-pages/docs/language-basics-entrypoints.md b/gitlab-pages/docs/language-basics-entrypoints.md deleted file mode 100644 index 303cc88e7..000000000 --- a/gitlab-pages/docs/language-basics-entrypoints.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -id: language-basics-entrypoints -title: Entrypoints ---- - -## Defining an entry point - - - -```Pascal -function main (const p : int ; const s : int) : (list(operation) * int) is - block {skip} with ((nil : list(operation)), s + 1) -``` - - -## Multiple entry points - -Multiple entrypoints are currently not supported in Michelson, however with Ligo, you can work that around by using variants. - - - -```Pascal -// variant defining pseudo multi-entrypoint actions -type action is -| Increment of int -| Decrement of int - -function add (const a : int ; const b : int) : int is - block { skip } with a + b - -function subtract (const a : int ; const b : int) : int is - block { skip } with a - b - -// real entrypoint that re-routes the flow based on the action provided -function main (const p : action ; const s : int) : (list(operation) * int) is - block {skip} with ((nil : list(operation)), - case p of - | Increment n -> add(s, n) - | Decrement n -> subtract(s, n) - end) -``` - - - diff --git a/gitlab-pages/docs/language-basics-functions.md b/gitlab-pages/docs/language-basics-functions.md deleted file mode 100644 index b082b69b1..000000000 --- a/gitlab-pages/docs/language-basics-functions.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -id: language-basics-functions -title: Functions ---- - -## Defining a function - - - -```Pascal -// multiply(1, 2) = 2 -function multiply (const a : int ; const b : int) : int is - begin - const result : int = a * b ; - end with result - -// add(1, 2) = 3 -function add (const a : int ; const b : int) : int is - block { skip } with a + b -``` - - \ No newline at end of file diff --git a/gitlab-pages/docs/language-basics-variables.md b/gitlab-pages/docs/language-basics-variables.md deleted file mode 100644 index 4f222e5b1..000000000 --- a/gitlab-pages/docs/language-basics-variables.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -id: language-basics-variables -title: Variables ---- - -## Defining a variable - - - -```Pascal -// int -const four : int = 4; - -// string -const name : string = "John Doe"; -``` - - \ No newline at end of file diff --git a/gitlab-pages/docs/language-basics/cheat-sheet.md b/gitlab-pages/docs/language-basics/cheat-sheet.md new file mode 100644 index 000000000..1e0e7aaef --- /dev/null +++ b/gitlab-pages/docs/language-basics/cheat-sheet.md @@ -0,0 +1,37 @@ +--- +id: cheat-sheet +title: Cheat Sheet +--- + + + + +|Primitive |Example| +|--- |---| +|Strings | `"Tezos"`| +|Characters | `"t"`| +|Integers | `42`, `7`| +|Natural numbers | `42n`, `7n`| +|Unit| `unit`| +|Boolean|
const hasDriversLicense: bool = False;
const adult: bool = True;
| +|Mutez (micro tez)| `42mtz`, `7mtz` | +|Address | `"tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx"`, `"KT1JepfBfMSqkQyf9B1ndvURghGsSB8YCLMD"`| +|Addition |`3 + 4`, `3n + 4n`| +|Multiplication & Division| `3 * 4`, `3n * 4n`, `10 / 5`, `10n / 5n`| +|Modulo| `10 mod 3`| +|Tuples| 
type name is (string * string);
const winner: name = ("John", "Doe");
const firstName: string = winner.0;
const lastName: string = winner.1;
| +|Types|`type age is int`, `type name is string` | +|Includes|```#include "library.ligo"```| +|Functions (short form)|
function add (const a : int ; const b : int) : int is
  block { skip } with a + b
| +|Functions (long form)|
function add (const a : int ; const b : int) : int is
  block { 
    const result: int = a + b;
  } with result
| +|Options|
type middleName is option(string);
const middleName : middleName = Some("Foo");
const middleName : middleName = None;
| +|Assignment| ```const age: int = 5;```| +|Assignment on an existing variable

*⚠️ This feature is not supported at the top-level scope, you can use it e.g. within functions. Works for Records and Maps as well.*| ```age := 18;```, ```p.age := 21``` | +|Annotations| ```("tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx" : address)```| +|Variants|
type action is
| Increment of int
| Decrement of int
| +|Variant *(pattern)* matching|
const a: action = Increment(5);
case a of
| Increment n -> n + 1
| Decrement n -> n - 1
end
| +|Records|
type person is record
  age: int ;
  name: string ;
end

const john : person = record
  age = 18;
  name = "John Doe";
end

const name: string = john.name;
| +|Maps|
type prices is map(nat, tez);

const prices : prices = map
  10n -> 60mtz;
  50n -> 30mtz;
  100n -> 10mtz;
end

const price: option(tez) = prices[50n];
| + + + \ No newline at end of file diff --git a/gitlab-pages/docs/language-basics/entrypoints.md b/gitlab-pages/docs/language-basics/entrypoints.md new file mode 100644 index 000000000..3f17189b7 --- /dev/null +++ b/gitlab-pages/docs/language-basics/entrypoints.md @@ -0,0 +1,46 @@ +--- +id: entrypoints +title: Entrypoints +--- + +Entrypoints serve as a gate to our smart contracts. In LIGO each entrypoint is a function that accepts two arguments - first one is the parameter used to invoke the contract, and the second is the current storage of the contract. Each entrypoint has to return a list of operations to apply as a result of the smart contract call, and a new storage value. + +> If you don't want to update the storage, don't worry, just re-cycle your last storage value. + +## Defining an entry point + +Contract below is effectively an empty contract, that takes a `unit` as a parameter, and returns a `unit` as well. + + + +```Pascal +function main (const p : unit ; const s : unit) : (list(operation) * unit) is + block {skip} with ((nil : list(operation)), s) +``` + + +## Multiple entry points + +Multiple entrypoints are currently not supported in Michelson yet, however with Ligo, you can work that around by using variants & pattern matching. + +In the example below we have a simple counter contract, that can be either `Increment(int)`-ed, or `Decrement(int)`-ed. + + + +```Pascal +// variant defining pseudo multi-entrypoint actions +type action is +| Increment of int +| Decrement of int + +// real entrypoint that re-routes the flow based on the action (parameter) provided +function main (const action: action ; const counter: int) : (list(operation) * int) is + block {skip} with ((nil : list(operation)), + case action of + | Increment number -> counter + number + | Decrement number -> counter - number + end) +``` + + + diff --git a/gitlab-pages/docs/language-basics/functions.md b/gitlab-pages/docs/language-basics/functions.md new file mode 100644 index 000000000..fc6895383 --- /dev/null +++ b/gitlab-pages/docs/language-basics/functions.md @@ -0,0 +1,43 @@ +--- +id: functions +title: Functions +--- + +## Defining a function + +Body of a function consists of two parts, the first part (**`block {}`** or **`begin ... end`**) - normally consists of logic *(flow conditions, variable declarations, etc.)*, and the second part (**`with ...`**) usually defines the return value of your function. + + + +```Pascal +const availableSupply: nat = 15n; +const totalSupply: nat = 100n; + +function calculatePrice(const available: nat; const total: nat): nat is + begin + const price: nat = total / available + end with price + +const price: nat = calculatePrice(availableSupply, totalSupply); +``` + + + + +### Functions without an explicit body (shorter syntax) + +A short hand syntax for the same function as above can inline the price calculation directly into the return statement. +While this approach can have it's benefits, it can decrease readability. + + +```Pascal +const availableSupply: nat = 15n; +const totalSupply: nat = 100n; + +function calculatePrice(const available: nat; const total: nat): nat is + block { skip } with total / available + +const price: nat = calculatePrice(availableSupply, totalSupply); +``` + + \ No newline at end of file diff --git a/gitlab-pages/docs/language-basics-operators.md b/gitlab-pages/docs/language-basics/operators.md similarity index 80% rename from gitlab-pages/docs/language-basics-operators.md rename to gitlab-pages/docs/language-basics/operators.md index faf0fdde2..3b2dfda6d 100644 --- a/gitlab-pages/docs/language-basics-operators.md +++ b/gitlab-pages/docs/language-basics/operators.md @@ -1,10 +1,12 @@ --- -id: language-basics-operators +id: operators title: Operators --- ## Available operators +> This list is non-exhaustive, more operators will be added in the upcoming LIGO releases. + |Michelson |Pascaligo |Description | |--- |--- |--- | | `SENDER` | `sender` | Address that initiated the current transaction diff --git a/gitlab-pages/docs/language-basics/types.md b/gitlab-pages/docs/language-basics/types.md new file mode 100644 index 000000000..1de9076ab --- /dev/null +++ b/gitlab-pages/docs/language-basics/types.md @@ -0,0 +1,72 @@ +--- +id: types +title: Types +--- + +## Built-in types + +For the list of built-in types, please refer to the [Cheat Sheet](language-basics/cheat-sheet.md). LIGO's type system is built on top of Michelson, but offers a handful of features like type aliasing, or groupping of multiple types into a single powerful type. + +## Type aliases + +Type aliasing is a great choice when working towards a readable / maintainable smart contract. One well typed variable is worth a thousand words. For example we can choose to *alias* a string, as an animal breed - this will allow us to comunicate our intent with added clarity. + + + +```Pascal +type animalBreed is string; + +const dogBreed: animalBreed = "Saluki"; +``` + + + +## Defining custom types + +### Simple types + + +```Pascal +// accountBalances is a simple type, a map of address <-> tez +type accountBalances is map(address, tez); + +const ledger: accountBalances = map + ("tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx": address) -> 10mtz +end +``` + + + + +### Composed types + +Often our contracts will require complex data structures, which will in turn require a well-typed storage, or functions to work with. LIGO offers a simple way to compose simple types, into larger & more expressive composed types. + +In the example below you can see definition of data types for a ledger, that keeps a balance & number of previous transactions for a given account. + + + +```Pascal +// alias two types +type account is address; +type numberOfTransactions is nat; + +// accountData consists of a record with two fields (balance, numberOfTransactions) +type accountData is record + balance: tez; + numberOfTransactions: numberOfTransactions; +end +// our ledger / accountBalances is a map of account <-> accountData +type accountBalances is map(account, accountData); + +// pseudo-JSON representation of our map +// { "tz1...": {balance: 10mtz, numberOfTransactions: 5n} } +const ledger: accountBalances = map + ("tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx": address) -> record + balance = 10mtz; + numberOfTransactions = 5n; + end +end +``` + + \ No newline at end of file diff --git a/gitlab-pages/docs/language-basics/variables.md b/gitlab-pages/docs/language-basics/variables.md new file mode 100644 index 000000000..4092a3eb9 --- /dev/null +++ b/gitlab-pages/docs/language-basics/variables.md @@ -0,0 +1,40 @@ +--- +id: variables +title: Variables +--- + +## Defining a variable + +Variables in LIGO can be defined in two ways - by using either the `const` or `var` keywords. `const` can be used both at global (top-level) and local scope (within functions/blocks), while `var` can be used for mutable values in the local scope. + + +### Imutable variables using `const` + +> ⚠️ Currently const values are mutable as well, however this is something that will change in the upcoming release. For the time being think of `const` as a semantical way to indicate developer intentions. + + + +```Pascal +const four: int = 4; +``` + + + +### Mutable variables using `var` + +> ⚠️ `var` can't be used in the global scope + + + +```Pascal +// won't work, use const for global values instead +var four: int = 4; + +// value of `number` can be mutated within local scope +function addFour(var number: int): int is + block { + number := number + 4; + } with number; +``` + + \ No newline at end of file diff --git a/gitlab-pages/docs/setup/editor-support.md b/gitlab-pages/docs/setup/editor-support.md new file mode 100644 index 000000000..197e5b2bf --- /dev/null +++ b/gitlab-pages/docs/setup/editor-support.md @@ -0,0 +1,8 @@ +--- +id: editor-support +title: Editor Support +--- + +Good editor support is the basic component of proper development experience - currently, we provide support for VSCode via an [extension](https://marketplace.visualstudio.com/items?itemName=Brice.ligo). + +Currently the extension supports Pascaligo for syntax highlighting (work in progress). But it aims to support debug, gas optimization, dry run and other relevant features in the near future. \ No newline at end of file diff --git a/gitlab-pages/docs/setup-installation.md b/gitlab-pages/docs/setup/installation.md similarity index 97% rename from gitlab-pages/docs/setup-installation.md rename to gitlab-pages/docs/setup/installation.md index c3e5111c6..2455d3bd7 100644 --- a/gitlab-pages/docs/setup-installation.md +++ b/gitlab-pages/docs/setup/installation.md @@ -1,5 +1,5 @@ --- -id: setup-installation +id: installation title: Installation --- @@ -32,7 +32,4 @@ ligo --help ## Manual installation (advanced) -For now, please refer to the steps described in the [Dockerfile](https://gitlab.com/ligolang/ligo/blob/master/docker/Dockerfile). - - - +For now, please refer to the steps described in the [Dockerfile](https://gitlab.com/ligolang/ligo/blob/master/docker/Dockerfile). \ No newline at end of file diff --git a/gitlab-pages/website/pages/en/index.js b/gitlab-pages/website/pages/en/index.js index c37adc495..5e395c5dd 100644 --- a/gitlab-pages/website/pages/en/index.js +++ b/gitlab-pages/website/pages/en/index.js @@ -29,9 +29,9 @@ class HomeSplash extends React.Component {
Pascaligo
+ data-tab="tab-group-3-content-4">PascaLIGO
Cameligo
+ data-tab="tab-group-3-content-5">CameLIGO
Reasonligo (coming soon)
{/*
Camligo
*/} diff --git a/gitlab-pages/website/pages/en/versions.js b/gitlab-pages/website/pages/en/versions.js index f701a8da3..4cc1bd3b5 100644 --- a/gitlab-pages/website/pages/en/versions.js +++ b/gitlab-pages/website/pages/en/versions.js @@ -39,7 +39,7 @@ function Versions(props) { + }setup/installation`}> Documentation @@ -63,7 +63,7 @@ function Versions(props) { + }next/setup/installation`}> Documentation @@ -88,7 +88,7 @@ function Versions(props) { + }${version}/setup/installation`}> Documentation diff --git a/gitlab-pages/website/sidebars.json b/gitlab-pages/website/sidebars.json index e39c0dfa0..0276684dd 100644 --- a/gitlab-pages/website/sidebars.json +++ b/gitlab-pages/website/sidebars.json @@ -1,7 +1,7 @@ { "docs": { - "Setup": ["setup-installation"], - "Language Basics": ["language-basics-variables", "language-basics-functions", "language-basics-entrypoints", "language-basics-operators"], + "Setup": ["setup/installation", "setup/editor-support"], + "Language Basics": ["language-basics/cheat-sheet", "language-basics/types", "language-basics/variables", "language-basics/functions", "language-basics/entrypoints", "language-basics/operators"], "API": ["api-cli-commands"] }, "contributors-docs": { diff --git a/gitlab-pages/website/siteConfig.js b/gitlab-pages/website/siteConfig.js index 71ba23d65..0f98c67e8 100644 --- a/gitlab-pages/website/siteConfig.js +++ b/gitlab-pages/website/siteConfig.js @@ -97,7 +97,7 @@ const siteConfig = { // For no header links in the top nav bar -> headerLinks: [], headerLinks: [ - {doc: 'setup-installation', label: 'Docs'}, + {doc: 'setup/installation', label: 'Docs'}, {doc: 'api-cli-commands', label: 'CLI'}, {doc: 'tutorials/first-smart-contract', label: 'Tutorials'}, { blog: true, label: 'Blog' }, diff --git a/gitlab-pages/website/static/css/custom.css b/gitlab-pages/website/static/css/custom.css index 773b05be3..32e965faa 100644 --- a/gitlab-pages/website/static/css/custom.css +++ b/gitlab-pages/website/static/css/custom.css @@ -29,20 +29,24 @@ background: transparent; } -.homeContainer .tabs { +.tabs { max-width: 800px; margin: 0 auto; border-top: none; border-bottom: 4px solid #e0e0e0; } -.homeContainer .tabs .nav-tabs > div { +.tabs .nav-tabs > div { cursor: pointer; color: #24292e; border-bottom: none; + padding-bottom: 8px; +} +.tab-content { + padding-top: 12px; } -.homeContainer .tabs .nav-tabs > div.active { +.tabs .nav-tabs > div.active { border-bottom: 4px solid #1A1A1A; } @@ -53,11 +57,11 @@ border-bottom: none; } -.homeContainer .tab-content { +.tab-content { border-top: 4px solid #e0e0e0; } -.homeContainer .nav-tabs { +.nav-tabs { border: none; position: relative; top: 4px; @@ -76,11 +80,15 @@ blockquote { - background-color: rgba(26, 26, 26, 0.6); - border-left: 8px solid rgba(26, 26, 26, 0.7); - color: rgba(255,255,255, 0.8); + background-color: rgba(26, 26, 26, 0.3); + border-left: 8px solid rgba(26, 26, 26, 0.1); + color: rgba(255,255,255, 1); } +blockquote code { + opacity: 0.7; +} +/* blockquote a { color: rgba(255,255,255, 0.8); border-bottom: 1px solid rgba(255,255,255, 0.8); @@ -89,7 +97,7 @@ blockquote a { blockquote a:hover { color: rgba(255,255,255, 1); border-bottom: 1px solid rgba(255,255,255, 1); -} +} */ /* blockquote { background-color: rgba(252, 214, 0, 0.687); @@ -98,11 +106,11 @@ blockquote { } */ a { - color: rgba(12, 12, 12, 0.8); + color: rgba(178, 33, 12, 0.8); } a:hover { - color: rgb(12, 12, 12); + color: rgba(178, 33, 12, 1); } .homeContainer .homeWrapper .projectLogo { @@ -198,6 +206,11 @@ a:hover { visibility: hidden; } +code { + background: rgb(240, 240, 240); + color: #444; +} + @media only screen and (min-device-width: 360px) and (max-device-width: 736px) { } diff --git a/gitlab-pages/website/versioned_docs/version-next/language-basics-entrypoints.md b/gitlab-pages/website/versioned_docs/version-next/language-basics-entrypoints.md index aa439932b..d32ea7bfd 100644 --- a/gitlab-pages/website/versioned_docs/version-next/language-basics-entrypoints.md +++ b/gitlab-pages/website/versioned_docs/version-next/language-basics-entrypoints.md @@ -9,7 +9,7 @@ original_id: language-basics-entrypoints ```Pascal -function main (const p : int ; const s : int) : (list(operation) * unit) is +function main (const p : int ; const s : int) : (list(operation) * int) is block {skip} with ((nil : list(operation)), s + 1) ``` @@ -42,4 +42,4 @@ function main (const p : action ; const s : int) : (list(operation) * int) is ``` - \ No newline at end of file + diff --git a/gitlab-pages/website/versioned_docs/version-next/setup-installation.md b/gitlab-pages/website/versioned_docs/version-next/setup-installation.md deleted file mode 100644 index 4363f40ca..000000000 --- a/gitlab-pages/website/versioned_docs/version-next/setup-installation.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -id: version-next-setup-installation -title: Installation -original_id: setup-installation ---- - -There are currently two ways to get started with Ligo, both of those will allow you to use the Ligo CLI with your contracts. You can choose to use either the Docker image, or to compile & build the Ligo CLI yourself. - -## Dockerized installation (recommended) - -> 🐳 You can find instructions on how to install Docker [here](https://docs.docker.com/install/). - -Easiest way to use LIGO is through the Docker image available at [Docker Hub](https://hub.docker.com/r/ligolang/ligo). Sources for the image can be found on [Gitlab](https://gitlab.com/ligolang/ligo/blob/master/docker/Dockerfile). -You can either run the docker image yourself, or you can setup a global ligo executable as shown below. - -### Setting up a globally available `ligo` executable - -> You can install additional ligo versions by replacing `next` with the required version number - -```zsh -# next (pre-release) -curl https://gitlab.com/ligolang/ligo/raw/dev/scripts/installer.sh | bash "next" - -# e.g. 1.0.0 (stable) -curl https://gitlab.com/ligolang/ligo/raw/master/scripts/installer.sh | bash "1.0.0" -``` - -**Verify your ligo installation by running:** -```zsh -ligo --help -``` - - -## Manual installation (advanced) - -For now, please refer to the steps described in the [Dockerfile](https://gitlab.com/ligolang/ligo/blob/master/docker/Dockerfile). - - - diff --git a/gitlab-pages/website/versioned_sidebars/version-next-sidebars.json b/gitlab-pages/website/versioned_sidebars/version-next-sidebars.json index 3d139c204..8e143da9e 100644 --- a/gitlab-pages/website/versioned_sidebars/version-next-sidebars.json +++ b/gitlab-pages/website/versioned_sidebars/version-next-sidebars.json @@ -1,13 +1,16 @@ { "version-next-docs": { "Setup": [ - "version-next-setup-installation" + "version-next-setup/installation", + "version-next-setup/editor-support" ], "Language Basics": [ - "version-next-language-basics-variables", - "version-next-language-basics-functions", - "version-next-language-basics-entrypoints", - "version-next-language-basics-operators" + "version-next-language-basics/cheat-sheet", + "version-next-language-basics/types", + "version-next-language-basics/variables", + "version-next-language-basics/functions", + "version-next-language-basics/entrypoints", + "version-next-language-basics/operators" ], "API": [ "version-next-api-cli-commands"