Add docs

docs/README.md

@@ -0,0 +1,8 @@
+# Clio Documentation
+
+Clio is a pure functional lazy-evaluated programming language targeting decentralized and distributed systems. It is made to take advantage of multiple CPUs and CPU cores \(parallelism\) by default, to run on clusters and on the cloud easily.
+
+Clio compiles to JavaScript. This makes Clio fast, easy to port and easy to extend. It gives Clio a free JIT compiler, a powerful VM and access to lots of existing libraries. It enables Clio to run in the browser and on servers, and anywhere JavaScript can run.
+
+![](https://raw.githubusercontent.com/clio-lang/media/master/clio-cut.png)
+

docs/SUMMARY.md

@@ -0,0 +1,48 @@
+# Table of contents
+
+* [Clio Documentation](README.md)
+* [Install](install.md)
+* [Getting Started](getting-started.md)
+* [Medium articles](medium-articles.md)
+
+## Learn
+
+* [Official Tutorial](learn/official-tutorial/README.md)
+  * [Introduction](learn/official-tutorial/introduction.md)
+  * [Flow](learn/official-tutorial/flow.md)
+  * [Functions](learn/official-tutorial/functions.md)
+  * [More about flows](learn/official-tutorial/more-about-flows.md)
+  * [Transforms](learn/official-tutorial/transforms.md)
+  * [Control flow](learn/official-tutorial/control-flow.md)
+  * [Events](learn/official-tutorial/events.md)
+  * [More data types](learn/official-tutorial/more-data-types.md)
+  * [Hosting](learn/official-tutorial/hosting.md)
+  * [Modules](learn/official-tutorial/modules.md)
+
+## Clio Executable
+
+* [Clio Executable](clio-executable/clio-executable/README.md)
+  * [Clio compile](clio-executable/clio-executable/clio-compile.md)
+  * [Clio ast](clio-executable/clio-executable/clio-ast.md)
+  * [Clio host](clio-executable/clio-executable/clio-host.md)
+  * [Clio highlight](clio-executable/clio-executable/clio-highlight.md)
+  * [Clio get](clio-executable/clio-executable/clio-get.md)
+  * [Clio deps](clio-executable/clio-executable/clio-deps.md)
+  * [Clio init](clio-executable/clio-executable/clio-init.md)
+  * [Clio run](clio-executable/clio-executable/clio-run.md)
+  * [Clio completion](clio-executable/clio-executable/clio-completion.md)
+
+## Modules
+
+* [Modules](modules/modules/README.md)
+  * [Clio modules](modules/modules/clio-modules.md)
+  * [JS Modules](modules/modules/js-modules.md)
+  * [Clio environment](modules/modules/clio-environment.md)
+  * [Browser](modules/modules/browser.md)
+
+## Tools
+
+* [Tools and Editors](tools/tools-and-editors/README.md)
+  * [VSCode](tools/tools-and-editors/vscode.md)
+  * [Atom](tools/tools-and-editors/atom.md)
+

docs/clio-executable/clio-executable/README.md

@@ -0,0 +1,14 @@
+# Clio Executable
+
+Clio executable provides several commands to work with Clio code. These commands are:
+
+* run
+* init
+* new
+* compile
+* ast
+* host
+* highlight
+* get
+* completion
+

docs/clio-executable/clio-executable/clio-ast.md

@@ -0,0 +1,8 @@
+# Clio ast
+
+To print the abstract syntax tree, you can run:
+
+```text
+clio ast file.clio
+```
+

docs/clio-executable/clio-executable/clio-compile.md

@@ -0,0 +1,8 @@
+# Clio compile
+
+To compile a Clio file to JavaScript, you can do:
+
+```text
+clio compile file.clio output.js
+```
+

docs/clio-executable/clio-executable/clio-completion.md

@@ -0,0 +1,8 @@
+# Clio completion
+
+Clio executable provides auto-completion script for various shells. You can run the below command to see how you can activate this feature for your shell:
+
+```text
+clio completion
+```
+

docs/clio-executable/clio-executable/clio-deps.md

@@ -0,0 +1,4 @@
+# Clio deps
+
+Use `clio deps.show` to show Clio dependencies of a project and use `clio deps.get` to fetch and install the dependencies.
+

docs/clio-executable/clio-executable/clio-get.md

@@ -0,0 +1,10 @@
+# Clio get
+
+To get a Clio module and install it in project's Clio env, you can do:
+
+```text
+clio get https://example.com/packages/package.tar.gz
+```
+
+Clio get can install from a url \(compressed package\), a git repository \(@version eg. `@1.2.2` is supported\) or from the official Clio repository. For a list of packages that exist in the official repository you can visit the [official package index repo](https://github.com/clio-lang/packages/).
+

docs/clio-executable/clio-executable/clio-highlight.md

@@ -0,0 +1,8 @@
+# Clio highlight
+
+To print a highlighted version of a Clio file in console, you can do:
+
+```text
+clio highlight file.clio
+```
+

docs/clio-executable/clio-executable/clio-host.md

@@ -0,0 +1,8 @@
+# Clio host
+
+To host a Clio file \(Functions as micro-services\) you can do:
+
+```text
+clio host file.clio
+```
+

docs/clio-executable/clio-executable/clio-init.md

@@ -0,0 +1,4 @@
+# Clio init
+
+The `clio init` command helps you generate a `cliopkg.toml` file for your project and install the Clio standard library in `clio_env` directory of your project.
+

docs/clio-executable/clio-executable/clio-new.md

@@ -0,0 +1,3 @@
+# Clio new
+
+`clio new <project-name>` Is the quickest way to get started with clio! Use it to generate a new project contained in a subdirectory.

docs/clio-executable/clio-executable/clio-run.md

@@ -0,0 +1,8 @@
+# Clio run
+
+To run a Clio file, you can do:
+
+```text
+clio run file.clio
+```
+

docs/getting-started.md

@@ -0,0 +1,11 @@
+---
+description: Getting Started with Clio
+---
+
+Use Clios integrated CLI to bootstrap a new project. To do so, run:
+
+```
+clio new helloclio
+```
+
+Change into the directory using `cd helloclio` and run the automatically generated `index.clio` file with `clio run`. How does Clio know which file to run? Take a look at `cliopkg.toml`. The field `main` specifies the entrypoint of your application. You can also specify other fields such as information about the author, the version of the project and much more. To list all available commands of Clio, simply run `clio` in your shell.

docs/install.md

@@ -0,0 +1,40 @@
+---
+description: How to install Clio
+---
+
+# Install
+
+## Install via NPM
+
+To install Clio language, you'll need Node.js and NPM. After installing Node and NPM, you can install Clio by running:
+
+`npm i -g clio-lang`
+
+Check your installation by running `clio` in your local shell. You're good to go!
+
+## Install via Arch User Repository
+
+If you are using an Arch-based linux distribution, you might consider installing Clio via the Arch User Repository (AUR).
+You can get more information about the `clio-lang` package here:
+
+https://aur.archlinux.org/packages/clio-lang
+
+## Bleeding Edge Installation
+
+Clio is in active development and installation is only recommended for testing, early adopting and development so it is recommended to install from git before we reach a stable version one release.
+
+To install from git, you'll need Node.js, NPM and git. You need to clone the repository:
+
+`git clone https://github.com/clio-lang/clio`
+
+ Then `cd` to the project directory:
+
+`cd clio`
+
+ Now you need to install dependencies, to do that run:
+
+`npm install`
+
+ Now you need to link the `clio` executable:
+
+`npm link`

docs/learn/official-tutorial/README.md

@@ -0,0 +1,20 @@
+# Official Tutorial
+
+This is the official guide for Clio, you can find links to blog posts, examples and third-party websites at the end of this article.
+
+Please note this is a work in progress, Clio isn't ready for production, it's not stable yet, there isn't a decent standard library or a set of built-ins. At this state, Clio is only suitable for language enthusiasts, experts who want to explore new possibilities, contributors and early adopters.
+
+## Blogs
+
+* [Creator's official blog](https://medium.com/@eghbali)
+
+## Examples
+
+* [GitHub Examples Repository](https://github.com/clio-lang/examples)
+* [RosettaCode](http://rosettacode.org/wiki/Clio)
+* [Todo Example \(Host/Browser\)](https://github.com/clio-lang/clio-todo)
+
+## Playgrounds
+
+* [Official Clio playground](https://playground.clio-lang.org)
+

docs/learn/official-tutorial/control-flow.md

@@ -0,0 +1,26 @@
+# Control flow
+
+To control the flow of your programs, Clio provides if/elif/else statements.
+
+```text
+fn check n:
+  if   n > 0: #positive
+  elif n < 0: #negative
+        else: #zero
+
+[1 0 -1] -> * print @ #is (transform n: check)
+```
+
+Body of a if/elif/else statement can be either a single expression or a block of expressions. In Clio, conditional statements are functions and can be used inside a flow, for example we can re-write the above example like this:
+
+```text
+fn check n:
+  n -> if > 0: #positive
+     elif < 0: #negative
+         else: #zero
+
+[1 0 -1] -> * print @ #is (transform n: check)
+```
+
+Clio also supports event-based control flow, but we will discuss this later.
+

docs/learn/official-tutorial/events.md

@@ -0,0 +1,14 @@
+# Events
+
+Clio supports event-based control flow. When we introduced flows, we mentioned a flow starts with data or a source. Events can be considered a source of data and can be used like this:
+
+```text
+#echo -> emitter => echo
+echo:#message -> upper -> print
+echo -> emit #message 'hello events!'
+```
+
+In above example, we create a emitter named `#echo` and store it in variable `echo`. Then we use `:` to listen to the `#message` event of `echo`, piping the message to `upper` and `print`. Then, on the last line, we emit a `#message` event using `echo`, and we pass `'hello events!'` as content of the message.
+
+`echo:#message` acts as a data source here, every time there's new data it will be passed to the specified flow.
+

docs/learn/official-tutorial/flow.md

@@ -0,0 +1,39 @@
+# Flow
+
+In Clio, all function calls and variable declarations happen inside a flow. Simplest form of flow is a flow that starts with some static data and calls a single function with no arguments. Let's write a simple hello world program together.
+
+```text
+'hello world' -> print
+```
+
+Strings are defined by single-quotes, whether they're single line or not. `->` is the pipe operator, and `print` is the function we're calling. If you run the above program you should see `hello world` printed in the console.
+
+Assignments and variable declarations also happen in a flow, for example in the above example if we want to put our string in a variable, and then print it, we can write:
+
+```text
+'hello world' => message
+message -> print
+```
+
+As you see, we use `=>` to assign to a variable to declare a new one. Lets move to a more complicated example, lets learn how to pass extra arguments to functions. This is possible in two ways, first one is done like this:
+
+```text
+'hello' 'world' -> print
+```
+
+This is simple, but it's not that convenient to use, for example when we want to chain functions and add extra argument to the next one. The second way can is done like this:
+
+```text
+`hello` -> print 'world'
+```
+
+Data is always passed as first argument to the function you call, although this behaviour can be changed using a specific symbol, but we're going to skip this for now. Let's learn how to chain the functions together, let's print an uppercase hello world!
+
+```text
+`hello world` -> upper -> print
+```
+
+As you can see, result of a function call can be _piped_ to more functions to create a chain. Here the order of execution is from left to right, as opposed to languages that use braces for function calls, in those languages the order is from inner to outer which leads to confusion and makes the code less readable.
+
+Although there's more about flows to learn, but we will skip them for now.
+

docs/learn/official-tutorial/functions.md

@@ -0,0 +1,57 @@
+# Functions
+
+In Clio, functions are pure and lazy. But before we get into the details, let's define a simple function together.
+
+```text
+fn hello person:
+  'hello' person -> print
+```
+
+In the above example, we defined a function named hello, it accepts a single argument _person_ and says hello to that person. Let's see what happens if we run this function:
+
+```text
+fn hello person:
+  'hello' person -> print
+
+'Pouya' -> hello
+```
+
+If you run the above code, you will not see any output in the console. This is because all the functions you define are _lazy_ by default. That means a call to the function will only be evaluated if the result of it is needed.
+
+Some functions aren't lazy, for example the built-in `print` function is not lazy, that's why you were able to run the _hello world_ example. Eager is opposite of lazy, when a function is eager the evaluation of the function call will be immediate.
+
+To make a function `eager` we decorate our definition with the built-in `eager` function:
+
+```text
+@eager
+fn hello person:
+  'hello' person -> print
+
+'Pouya' -> hello
+```
+
+Now if you run the code you will see the results in the console. Functions in Clio have implicit returns, it means the last evaluated expression will be returned from the function, for example:
+
+```text
+fn double n:
+  n * 2
+
+2 -> double -> print
+```
+
+You don't need to explicitly write return in your function body. Functions are pure, they have access to outside scope, but the outside scope is frozen for them, that means if you change value of a variable after you define a function, that function will still have the old value of this variable.
+
+```text
+10 => x
+
+fn add_to_x n:
+    x + n => x
+
+20 => x
+2 -> add_to_x
+```
+
+Functions should have at least one argument, value of a function call only depends on its arguments so a function with no arguments is going to be a constant. Since the value a function returns depends only on its arguments, it makes sense to cache the results and speed-up our function calls. This way instead of re-executing the function for same arguments, the function remembers the previous results and returns them.
+
+We'll talk more about functions in the future.
+