imba / imba-guide

A quick guide to Imba

⛔ [DEPRECATED] Please use https://github.com/imba/imba.io

Imba guide

This is a quick guide to the Imba language and web development platform.

Imba is a general purpose programming language that compiles to JavaScript and is optimized for writing performant front end web applications.

Requirements

System packages:

• Python (for documentation generator)
• NodeJS (for the playground)

Install the dependencies for the Sphinx documentation generator:

• Go into the repository directory
• Run pip install -r requirements.txt

Install the dependencies for the playground:

• Go into the repository directory
• Run npm install

Quick start

To build the documentation, go to the project directory and run npm run build:docs.

The compiled documentation should be present in site/index.html. Open that file in your browser.

You can also read the source Markdown files directly.

Using the playground

The playground is a simple Imba module that is set up to compile using Webpack. The idea is to open the compiled code and the source side-by-side and compare the source to the output.

To start the automatic compilation, run npm run watch. The compiled JavaScript will appear in dist/client.js.

To start the development web server, run: npm run start.

NOTE: The development server will not compile your playground code into dist/client.js, so if you wish to keep track of the compiler output, you should run both watch and start scripts

Directory structure

• docs/ - documentation source (index.md is the starting point)
• build/ - generated HTML for the documentation (appears after running npm run build:docs)
• code/ - playground code
• dist/ - compiled JavaScript for the playground

Contributing

If you wish to contribute to this project, you may find it helpful to know that the project uses MkDocs. The npm run watch:docs command will spin up a local server on port 8000 that will update as you edit.

Publishing the docs on GitHub Pages

The documentation is published to GitHub Pages with npm run gh-publish.

imba-guide's Issues

Fix tips for JavaScript developers

Some of the tips in the javascript.md section are outdated and should be corrected to take into account the v1.4.x features.

Bonus sections

Bonus sections should be about the language itself, not concrete development tasks.

Finish Level 2

• Modules
• Classes
• Tags
• Async
• Global (hmmmm...)
• List comprehensions

Document object destructuring in method arguments

Fix build instructions and scripts

Add --user flag to pip command.

Use python -m mkdocs instead of just mkdocs in npm script.

Level 3?

Level 3 should be about architectural patterns for different Imba apps and cookbook-style articles in general. Some of this is already targeted for the 'bonus' section, but maybe just move them into level 3 instead.

Add ability to execute examples

Add a button to execute the example snippets and see the results. Perhaps even make the examples editable on the spot? Maybe a shortcut to load the example into Scrimba?

Document the ? : ternary operator

Add cheats for object destructuring in methods.md

• Object destructuring is done by using key: defaultValue in parameter list.
• Only one object can be destructured.
• Default value is required in object destructuring.

Document the `foo if cond` conditional

Syntax highlighting

Add Imba and JavaScript syntax highlighting.

Finish off Level 1

• Methods
• do blocks

Allow complete web apps in playground

Add the ability to switch between the example code and compiled output

Make compiled output available in the docs so that the experienced reader can toggle or see side-by-side.

Document kebab case

This should go into Level 1, probably right after comments. Just need to figure out what else should go into the same section.