diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..fd141f7c --- /dev/null +++ b/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) + diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 00000000..2c23d911 --- /dev/null +++ b/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) + diff --git a/docs/clio-executable/clio-executable/README.md b/docs/clio-executable/clio-executable/README.md new file mode 100644 index 00000000..9e3972f8 --- /dev/null +++ b/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 + diff --git a/docs/clio-executable/clio-executable/clio-ast.md b/docs/clio-executable/clio-executable/clio-ast.md new file mode 100644 index 00000000..e1348afd --- /dev/null +++ b/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 +``` + diff --git a/docs/clio-executable/clio-executable/clio-compile.md b/docs/clio-executable/clio-executable/clio-compile.md new file mode 100644 index 00000000..9b2765c1 --- /dev/null +++ b/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 +``` + diff --git a/docs/clio-executable/clio-executable/clio-completion.md b/docs/clio-executable/clio-executable/clio-completion.md new file mode 100644 index 00000000..11ef1ec8 --- /dev/null +++ b/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 +``` + diff --git a/docs/clio-executable/clio-executable/clio-deps.md b/docs/clio-executable/clio-executable/clio-deps.md new file mode 100644 index 00000000..79d43a77 --- /dev/null +++ b/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. + diff --git a/docs/clio-executable/clio-executable/clio-get.md b/docs/clio-executable/clio-executable/clio-get.md new file mode 100644 index 00000000..a17aebe1 --- /dev/null +++ b/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/). + diff --git a/docs/clio-executable/clio-executable/clio-highlight.md b/docs/clio-executable/clio-executable/clio-highlight.md new file mode 100644 index 00000000..cad4221c --- /dev/null +++ b/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 +``` + diff --git a/docs/clio-executable/clio-executable/clio-host.md b/docs/clio-executable/clio-executable/clio-host.md new file mode 100644 index 00000000..c4e3860a --- /dev/null +++ b/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 +``` + diff --git a/docs/clio-executable/clio-executable/clio-init.md b/docs/clio-executable/clio-executable/clio-init.md new file mode 100644 index 00000000..274da2f1 --- /dev/null +++ b/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. + diff --git a/docs/clio-executable/clio-executable/clio-new.md b/docs/clio-executable/clio-executable/clio-new.md new file mode 100644 index 00000000..8f4b2453 --- /dev/null +++ b/docs/clio-executable/clio-executable/clio-new.md @@ -0,0 +1,3 @@ +# Clio new + +`clio new ` Is the quickest way to get started with clio! Use it to generate a new project contained in a subdirectory. \ No newline at end of file diff --git a/docs/clio-executable/clio-executable/clio-run.md b/docs/clio-executable/clio-executable/clio-run.md new file mode 100644 index 00000000..b05dc2f9 --- /dev/null +++ b/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 +``` + diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..c8056439 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 00000000..1692bef5 --- /dev/null +++ b/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` diff --git a/docs/learn/official-tutorial/README.md b/docs/learn/official-tutorial/README.md new file mode 100644 index 00000000..6d23dd01 --- /dev/null +++ b/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) + diff --git a/docs/learn/official-tutorial/control-flow.md b/docs/learn/official-tutorial/control-flow.md new file mode 100644 index 00000000..c7fc0645 --- /dev/null +++ b/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. + diff --git a/docs/learn/official-tutorial/events.md b/docs/learn/official-tutorial/events.md new file mode 100644 index 00000000..ee2d50dd --- /dev/null +++ b/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. + diff --git a/docs/learn/official-tutorial/flow.md b/docs/learn/official-tutorial/flow.md new file mode 100644 index 00000000..57494581 --- /dev/null +++ b/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. + diff --git a/docs/learn/official-tutorial/functions.md b/docs/learn/official-tutorial/functions.md new file mode 100644 index 00000000..59e2a37a --- /dev/null +++ b/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. + diff --git a/docs/learn/official-tutorial/hosting.md b/docs/learn/official-tutorial/hosting.md new file mode 100644 index 00000000..b739356f --- /dev/null +++ b/docs/learn/official-tutorial/hosting.md @@ -0,0 +1,36 @@ +# Hosting + +In Clio, functions are isolated and each have their own frozen scope. This makes it easy to host these functions as microservices and import them from some place else \(Even from another language\). It is even possible to write functions in other languages, host them and import them in Clio \(a Python example exists in main repository\). + +As an example, let's create a `host.clio` file and put this code in it: + +{% code-tabs %} +{% code-tabs-item title="host.clio" %} +```text +42 => answer +#my_emitter -> emitter => my_emitter + +@eager +fn to_power_of i n: + i ^ n + +{ + #port 3000 -- defaults to 3000 + #workers 8 -- defaults to number of cpus + #exports [#to_power_of #my_emitter #answer] -- choose what you want to host +} => host +``` +{% endcode-tabs-item %} +{% endcode-tabs %} + +Now, we can host this file using: + +`clio host host.clio` + +Then in another Clio code, we can import these variables, event emitters and functions. For functions and variables we can use http or https, ws or wss protocols, but for events we must use either ws or wss: + +```text +import answer to_power_of from http://localhost:3000 +import my_emitter from ws://localhost:3000 +``` + diff --git a/docs/learn/official-tutorial/introduction.md b/docs/learn/official-tutorial/introduction.md new file mode 100644 index 00000000..31aae8d3 --- /dev/null +++ b/docs/learn/official-tutorial/introduction.md @@ -0,0 +1,12 @@ +# Introduction + +Clio is a new-generation programming language that compiles to JavaScript, but this doesn't mean it's just JavaScript in new clothes. Clio requires its own runtime including but not limited to data types, lazy evaluator, built-in libraries, event emitter, network-based foreign function interface and the remote ecosystem. Clio introduces a unique syntax, way of programming and new programming concepts. + +As for syntax, Clio isn't a free-form language, that means spaces have meanings in the language syntax. Clio is a noise-free language, that means most of the common symbols found in other languages are not present in Clio, as an example, functions aren't called by braces in Clio and arguments aren't separated by a comma. + +Clio allows to easily chain functions together with flexibility without losing readability, these function calls aren't nested inside each other and they're read and run in same direction as they're written, not from inner to outer. This way of chaining functions is called a flow in Clio, a flow starts with data or data source \(an event listener for example\), functions operate after each other on the data. + +Functions are microservices in Clio, they're isolated and free of side-effects, Clio provides tools to host these functions, export reactive data sources and static variables and import and work with them in any other place in any language. With the network-based foreign function interface you'll be able to use most of modules of any other programming language with ease. + +This document assumes you have at least a basic programming knowledge and you're familiar with concepts like a variable or a function, but it should be easy for non-programmers to pick up. + diff --git a/docs/learn/official-tutorial/modules.md b/docs/learn/official-tutorial/modules.md new file mode 100644 index 00000000..d84fbf3e --- /dev/null +++ b/docs/learn/official-tutorial/modules.md @@ -0,0 +1,33 @@ +# Modules + +You can write your code in separate files and import them in another file, or you can use libraries written by other programmers. Clio supports relative path imports, plus Clio virtual environment imports. You can install a package in this environment using `clio get` command, as an example: + +```text +clio get https://github.com/clio-lang/answer/archive/v0.1.0.tar.gz +``` + +Then in your code, you can import this package: + +```text +import answer from answer-0.1.0/answer +-- or +import answer-0.1.0/answer +``` + +To import files from a relative path you can write: + +```text +import module -- this will import ./module.clio, if not found will try virtual env +import ./module.clio -- this will import ./module, will not try virtual env if not found +import ../module -- if this fails, it will not try virtual env +import ../module.js -- if this fails, it will not try virtual env +``` + +Imports work on browser too. Clio recognizes `exports` and `module.exports` in js files. To write a js module and export some variable you can do: + +```text +exports.answer = 42; +// or +module.exports.answer = () => 42; +``` + diff --git a/docs/learn/official-tutorial/more-about-flows.md b/docs/learn/official-tutorial/more-about-flows.md new file mode 100644 index 00000000..7125e428 --- /dev/null +++ b/docs/learn/official-tutorial/more-about-flows.md @@ -0,0 +1,28 @@ +# More about flows + +## Maps + +Previously we talked about flows and we said there are more advanced uses that we'll discuss further in the manual. One of these advanced features is mapping. You can easily map a function to a list or generator in a flow. + +```text +fn double n: + n * 2 + +[1 2 3 4 5] -> * double -> print +``` + +In the above example, we used `-> *` operator to map `double` to our list, and then we piped its result to print function. Note that whitespace in `-> *` is optional. + +## Positional Arguments + +We said it's possible to change position of arguments in a function call, let's see how. + +```text +'hello' 'world' -> print +'hello' 'world' -> print @1 @0 +``` + +The symbol we use to refer to a specific argument at a specific location is `@`, if used without and index it refers to first argument that is piped to the function, otherwise it refers to the provided index. + +When ready, please proceed to [next part](/docs/learn/) of this article. + diff --git a/docs/learn/official-tutorial/more-data-types.md b/docs/learn/official-tutorial/more-data-types.md new file mode 100644 index 00000000..a0e7daf9 --- /dev/null +++ b/docs/learn/official-tutorial/more-data-types.md @@ -0,0 +1,52 @@ +# More data types + +## Lists + +A list is a generator in Clio. Generators are lazy and indexable. Lists are defined like this: + +```text +[1 2 3 4] => my_list +my_list -> print +``` + +Clio supports multi-dimensional indexing: + +```text +-- this is a comment +[[1 2 3] + [4 5 6] + [7 8 9]] => my_list + +my_list[1 1] -> print -- 2nd row 2nd col! +``` + +You will learn more about indexing in next chapter, for now let's learn a little more about the data types. + +## Ranges + +Ranges are also generators, it means they're lazy and indexable. Here's how we can define a range: + +```text +[0:5] -> * print -- from 0 to 5 +[0:10:2] -> * print -- from 0 to 10, step is 2 +[::2] => evens -- from 0 to infinity, step is 2 + -- ^ all of the even numbers! + +evens[[0:10]] -> * print -- first 10 even numbers | bug! +``` + +## Hash maps + +Hash maps are similar to lists, except that there are keys instead of indexes: + +```text +{ + #key1 #value1 + #key2 #value2 +} => my_map + +my_map.key1 -> print +``` + +To learn how to create your own custom data types, proceed to next part. + diff --git a/docs/learn/official-tutorial/transforms.md b/docs/learn/official-tutorial/transforms.md new file mode 100644 index 00000000..0bd9296c --- /dev/null +++ b/docs/learn/official-tutorial/transforms.md @@ -0,0 +1,21 @@ +# Transforms + +Clio doesn't support passing anonymous functions as arguments, but instead Clio introduces the concept of _transforms_. A transform can be used to transform arguments of a function call _before_ calling the function. Transforms are lazy and are evaluated on function call evaluation. + +```text +[1 2 3 4 5] -> * print #twice @ #is (transform n: n * 2) +``` + +In the above example, `#twice` and `#is` are _words_. A word is a string that is only one word. Transforms are defined similar to functions, but with one argument and only one statement in the body. + +To specify the position of argument passed to transform we can use `@`: + +```text +2 3 4 -> print 'twice 2nd arg is' (transform @1 as n: n * 2) +``` + +To help with readability, Clio syntax enforces a few rules: + +1. A single function call is no more than a single line +2. Transforms are only one line + diff --git a/docs/medium-articles.md b/docs/medium-articles.md new file mode 100644 index 00000000..cb469417 --- /dev/null +++ b/docs/medium-articles.md @@ -0,0 +1,14 @@ +--- +description: Friend links to medium articles to provide free access to the community +--- + +# Medium articles + +Please note some of these posts _may not work anymore_ with the new Clio versions. + +{% embed url="https://blog.usejournal.com/introduction-to-clio-40dbbf9c250b?source=friends\_link&sk=fccbf892f304391eee2f85bfeffa2469" %} + +{% embed url="https://medium.com/@eghbali/making-a-reactive-to-do-app-with-clio-ac7bf8b93959?source=friends\_link&sk=13b0e840eba2a7d684d59355530ff44b" %} + + + diff --git a/docs/modules/modules/README.md b/docs/modules/modules/README.md new file mode 100644 index 00000000..50a7fb79 --- /dev/null +++ b/docs/modules/modules/README.md @@ -0,0 +1,10 @@ +# Modules + +This group of articles explains how the Clio import system works and how you can use Node.js and JavaScript libraries in your Clio code. + +You can find examples of using Clio modules, or using Node.js modules and JavaScript packages with Clio in the following repositories: + +* [Clio To-Do Example](https://github.com/clio-lang/clio-todo) +* [RethinkDB packed for Clio](https://github.com/clio-lang/rethinkdb) +* [Simple Clio Module](https://github.com/clio-lang/answer) + diff --git a/docs/modules/modules/browser.md b/docs/modules/modules/browser.md new file mode 100644 index 00000000..694df280 --- /dev/null +++ b/docs/modules/modules/browser.md @@ -0,0 +1,8 @@ +# Browser + +Imports work on browser too. Browser imports are also relative and both JavaScript and Clio imports are supported. + +Please note there is no `require` function in browser and because of limitations of browsers \(for example file access limitations\) some JavaScript or Clio modules will not work on the browser. + +The default location for `clio_environment` is the value of `window.location.origin`, this can be overridden by setting `window.clio.__basedir` after loading the Clio run-time library and before calling the `clio.process_scripts()` function. + diff --git a/docs/modules/modules/clio-environment.md b/docs/modules/modules/clio-environment.md new file mode 100644 index 00000000..ec2c4151 --- /dev/null +++ b/docs/modules/modules/clio-environment.md @@ -0,0 +1,4 @@ +# Clio environment + +At the root of each project there can be a `clio_env` directory. All Clio modules should be installed in this directory. If a relative import fails, Clio will start looking for the module in the `clio_env` directory. + diff --git a/docs/modules/modules/clio-modules.md b/docs/modules/modules/clio-modules.md new file mode 100644 index 00000000..e54f26b0 --- /dev/null +++ b/docs/modules/modules/clio-modules.md @@ -0,0 +1,46 @@ +# Clio modules + +Any `.clio` file is a Clio module and can be imported in any other Clio code. There is no need to use a `export` keyword or a `exports` variable like in JavaScript. + +{% code-tabs %} +{% code-tabs-item title="my\_module.clio" %} +```text +@eager +fn hello name: + 'hello' name -> print +``` +{% endcode-tabs-item %} +{% endcode-tabs %} + +The above example is a simple Clio module and can be imported and used like this: + +```text +import hello from my_module + +'world' -> hello +``` + +In Clio, imports are relative and by path, there is no support for absolute imports. Clio recognizes the following import path formats: + +```text +import module +import ./module +import ../module +import dir/module +import ./dir/module +import ../dir/module +``` + +Including `.clio` for file name is optional, the above example is the same as the following: + +```text +import module.clio +import ./module.clio +import ../module.clio +import dir/module.clio +import ./dir/module.clio +import ../dir/module.clio +``` + + + diff --git a/docs/modules/modules/js-modules.md b/docs/modules/modules/js-modules.md new file mode 100644 index 00000000..523f318c --- /dev/null +++ b/docs/modules/modules/js-modules.md @@ -0,0 +1,40 @@ +# JS Modules + +JavaScript files can be imported directly in your Clio code. For JavaScript files you need to use `exports` or `module.exports` variables: + +{% code-tabs %} +{% code-tabs-item title="my\_module.js" %} +```text +module.exports.hello = function(name) { + console.log(`Hello ${name}`); +} +``` +{% endcode-tabs-item %} +{% endcode-tabs %} + +and to import it in Clio: + +```text +import hello from my_module.js +``` + +When importing JavaScript files you must include `.js` in the file name. Same as Clio modules, these imports are relative and recognize the same path formats as the Clio file imports. + +To import and use a Node.js module, install it using `npm` + +```text +npm i express +``` + +Then you can import it in your Clio file: + +{% code-tabs %} +{% code-tabs-item title="example.clio" %} +```text +import express +``` +{% endcode-tabs-item %} +{% endcode-tabs %} + + + diff --git a/docs/quick.html b/docs/quick.html new file mode 100644 index 00000000..317ebf4c --- /dev/null +++ b/docs/quick.html @@ -0,0 +1,339 @@ + + + Clio - Quick Guide + + + + + + + + + +
+ Clio is a clean and noise-free language. Each map function takes advantage of multiple cores and cpus [planned]. All functions are defined as micro-services [planned]. + Clio supports cloud modules and functions [implemented], which are modules and functions living on another (or the same) machine written in another (or the same) language. + Clio supports tensor/array programming and indexing [implemented/needs fixing]. +
+
+

Disclaimer

+
+ This guide was written for people who are already familiar with coding and programming languages. + This guide is targetting advanced users, since Clio isn't ready for production yet.
+ Clio is still in early development stages, so things might stop working and there are tons of bugs. Every new feature introduced might break existing functionality. + New features are planned, and some features are already implemented but need fixing. +
+

Flows

+
+ Let's start with a classical hello world example in Clio +
+ 
'hello world' -> print
+
+ -> is the pipe operator, and using pipes is the only way to call functions in Clio, which makes it easy to chain functions +
+ 
'hello world' -> upper -> print
+
+ Using -> to chain functions is called a flow. If necessary, you can use new lines to make your flows more readable +
+ 
'hello world'
+  -> upper
+  -> print
+
+ Let's print a list +
+ 
[1 2 3] -> print
+
+ To map a function to a list or iterator, we write -> * . Using * after the pipe operator means we want to map the function to our data +
+ 
[1 2 3] -> * print
+
+ Clio has support for words. Words are strings that do not have any whitespace in them, # is used to declare a word +
+ 
#hello -> print
+
+ We can refer to the value of the previous step using @ +
+ 
#world -> print #hello @
+
+ It's possible to pass several arguments to a function +
+ 
#world #hello -> print
+
+ @0 @1 @2 ... can be used to refer to the arguments +
+ 
#world #hello -> print @1 @0
+
+ => is used to store data or the result of a flow in a variable +
+ 
'clio' -> upper => clio
+clio -> print
+

Functions

+
+ Let's define a function +
+ 
fn double n:
+  n * 2
+
+[1 2 3] -> * double -> print
+
+ Functions being lazy evaluated by default makes Clio fast by preventing stack size and recursion limit issues +
+ 
fn fib n:
+  if n <= 1: n
+  else:
+    (n - 1 -> fib) + (n - 2 -> fib)
+
+10000 -> fib -> print
+
+ As you've guessed, functions have implicit return in Clio.
Clio supports quick functions, which are single-line and can only be used in flows. +
+ 
64 -> n: n * 2 -> print
+[1 2 3] -> * n: n^2 -> print
+
+ For multi-line functions, Clio supports in-flow definitions as well +
+ 
[1 2 3] -> * fn n:
+  n * 2
+-> print
+
+ Clio doesn't process flows until their value is needed. In this example, no result is printed because Clio functions are lazy by default and hello is never called +
+ 
fn hello t:
+  t -> print #hello @
+
+#world -> hello
+
+ To force evaluate a flow we can use eval +
+ 
fn hello t:
+  t -> print #hello @
+
+#world -> hello -> eval
+
+ To define eager functions, we can use the eager decorator as follows +
+ 
@eager
+fn hello t:
+  t -> print #hello @
+
+#world -> hello
+
+ Decorators can be used with in-flow functions too +
+ 
#world -> (@eager) fn t:
+  t -> print #hello @
+
+ Clio supports function overloading. decorators are shared between all overloads +
+ 
@eager
+fn hello x if str:
+  x -> print 'Hello string' @ #!
+
+fn hello x if num:
+  x -> print 'Hi numeric' @ #!
+
+[42 #WORD] -> * hello
+
+ Functions cannot read from or write to the outside scope. When a function is defined, the outside scope will get frozen for that function, + it will not get any updates from outside, and it cannot update outside variables. This is necessary for the language to be pure. + It also reduces side-effects and makes it easier to write parallel code. +
+ 
1 => x
+fn add_to_x n:
+  x + n => x
+
+x -> print 'x is' @
+1 -> add_to_x -> print 'The result of the function is' @
+x -> print 'x is' @
+2 => x
+x -> print 'x is' @
+1 -> add_to_x -> print 'The result of the function is' @
+
+ Values passed to functions can be transformed before function calls. This is useful when we want to pass properties or do some quick calculations on our data without modifying the data itself +
+ 
[1 2 3] -> * print #twice @ #is (transform n: n * 2)
+
+ This is very different from lambdas and anonymous functions in other languages. A lambda is a quick function definition that can be passed to another function + so the other function can make use of it, that's not the case for Clio's transforms. Transforms actually transform the data before calling the function, so + the value of the transform is passed to the function, not a function that can act on the data. +
+

Control Flow

+
+ Let's start by if-else +
+ 
fn test n:
+  if n > 0:
+    #positive
+  elif n < 0:
+    #negative
+  else:
+    #zero
+
+[0 10 -10] -> * test -> * print
+
+ It's possible to use if-else in flows +
+ 
@eager
+fn test n:
+  n -> if > 0:
+    #positive
+  elif < 0:
+    #negative
+  else:
+    #zero
+  -> print
+
+[0 10 -10] -> * test
+
+ Alternatively, if our if-else blocks are only one-liners, we can pretty format them as follows +
+ 
@eager
+fn test n:
+  n -> if   > 0:  #positive
+       elif < 0:  #negative
+       else:      #zero
+
+    -> print
+
+[0 10 -10] -> * test
+
+ Conditionals can be used in flows, and flows can also be used in conditionals +
+ 
[10 20 30]
+  -> * if pow 2 -> add 2 > 105: #yes
+                          else: #no
+  -> * print
+
+ Clio doesn't support loops, we can use recursion instead. There's no limit for recursion +
+ 
@eager
+fn loop n:
+  if n = 0:
+    'Loop completed' -> print
+  else:
+    n - 1 -> loop
+
+1000 -> loop
+--1'000'000 -> loop -- this will kill your browser!
+
+ Maps can be used instead of for loops +
+ 
-- TODO: fix for non-eager functions!
+
+[0:9] -> * (@eager) fn i:
+  [0:9] -> * (@eager) fn j:
+    [i j]
+-> * print
+

Custom Types

+
+ Clio supports custom types. Custom types in Clio are equivalent to + objects in other languages, but they're made to work better with parallelism and the functional programming paradigm. Let's define a custom type +
+ 
type cat name age:
+  name => self.name
+  age  => self.age
+
+#Moki 6 -> cat => moki
+
+moki's name -> print
+
+ Each custom type has an init function that will be called upon creation. Inside the init function, the properties of the type can be accessed using self +
+ 
type cat name age:
+  name => self.name
+  age  => self.age
+
+  'A new cat was created' -> print
+
+#Moki 6 -> cat => moki
+
+moki's name -> print
+
+ Functions can be overloaded for custom types using the of keyword. This will make self available in the function scope +
+ 
type cat name:
+  name => self.name
+
+type dog name:
+  name => self.name
+
+@eager
+fn hello of cat:
+  self.name -> print 'Meow! My name is' @
+
+fn hello of dog:
+  self.name -> print 'Woof! My name is' @
+
+#Honey -> cat -> hello
+#Gino -> dog -> hello
+
+ The of keyword can be combined with if keyword for further overloading of the argument of hello +
+ 
type cat name:
+  name => self.name
+
+@eager
+fn hello s if str of cat:
+  s -> print 'Hello string' @ 'I\'m a cat!'
+
+@eager
+fn hello n if num of cat:
+  n -> print 'Hello numeric' @ 'I\'m a cat!'
+
+#Chili -> cat => chili
+chili -> hello 'lorem ipsum'
+chili -> hello 42
+

Tensor Programing

+
+ Clio has built-in support for tensor programming and indexing. Let's start with slicing a simple 1D list +
+ 
[1 2 3 4 5 6 7 8 9 10][0] -> print
+
+ Lists, tensors and ranges are all generators in Clio. A Generator has a getter method, a length method and a data attribute. + This makes Generator a lazy type, capable of easily doing lazy operations.
+ Generators can be sliced as we did in the previous example. + The syntax for slicing is Generator[Slicers] . Each slicer can be a range, a list or a number. If the slicer is a number, a single item with that index will be returned. + If the slicer is a list, several items with indexes included in the list will be returned +
+ 
[1 2 3 4 5 6 7 8 9 10][[0 1 2]] -> print
+
+ The Same applies for ranges. If the slicer is a range, several items with indexes in that range will be returned +
+ 
[1 2 3 4 5 6 7 8 9 10][[0:3]] -> print
+
+ Ranges can have steps. The syntax for ranges is [start:end:step] +
+ 
[0:10:1.25] -> * print
+
+ Stepped ranges can be used for slicing +
+ 
[1 2 3 4 5 6 7 8 9 10][[0:7:2]] -> print
+
+ Clio supports multi-dimensional indexing. Let's make a matrix and get the last 2 elements of last 2 lines +
+ 
[[1 2 3]
+ [4 5 6]
+ [7 8 9]][[1:] [1:]] -> print
+ +
+ + + + + + + + + diff --git a/docs/tools/tools-and-editors/README.md b/docs/tools/tools-and-editors/README.md new file mode 100644 index 00000000..85b4fade --- /dev/null +++ b/docs/tools/tools-and-editors/README.md @@ -0,0 +1,4 @@ +# Tools and Editors + +You can find a list of Clio tools and editor extensions here. + diff --git a/docs/tools/tools-and-editors/atom.md b/docs/tools/tools-and-editors/atom.md new file mode 100644 index 00000000..138e9ac6 --- /dev/null +++ b/docs/tools/tools-and-editors/atom.md @@ -0,0 +1,4 @@ +# Atom + +Two packages exist for Atom, one to highlight `.clio` files, and the other to highlight Clio code in HTML files. You can find the [first here ](https://atom.io/packages/language-clio)and the [second one here](https://atom.io/packages/language-clio-html). + diff --git a/docs/tools/tools-and-editors/vscode.md b/docs/tools/tools-and-editors/vscode.md new file mode 100644 index 00000000..5e8b4a6b --- /dev/null +++ b/docs/tools/tools-and-editors/vscode.md @@ -0,0 +1,8 @@ +# VSCode + +VSCode syntax highlighting support exists thanks to [Michele Riva](https://github.com/micheleriva). You can check the [source here](https://github.com/micheleriva/vscode-clio) or check the [package on VSCode marketplace](https://marketplace.visualstudio.com/items?itemName=MicheleRiva.clio-lang). + +![](https://github.com/micheleriva/vscode-clio/raw/master/images/preview.png) + + +