Skip to content

Latest commit

 

History

History
338 lines (239 loc) · 14.9 KB

index.markdown

File metadata and controls

338 lines (239 loc) · 14.9 KB
Raw
layout title nav_order description
home
Introduction
0
Welcome! This is the official documentation for Blade 0.0.85.

Introducing Nyssa Package Manager. The official package manager for the Blade programming language. {: .fs-4 .text-red-300 }

The Blade Language Documentation

{: .fs-9 }

Welcome! This is the official documentation for Blade 0.0.85. {: .fs-6 .fw-300 }

Build Status Gitter License Coverage Status Version


The following code implements a simple backend API that runs on port 3000:

import http
import json

var server = http.server(3000)
server.on_receive(@(request, response) {
  response.headers['Content-Type'] = 'application/json'
  response.write(json.encode(request))
})

echo 'Listening on Port 3000...'
server.listen()



What is Blade?

Blade is a simple, clean, and embeddable dynamic programming language created to be simple enough for beginners, yet powerful and expressive for professionals. It has a very small syntax set with a very low learning curve. Blade improves upon the best features of JavaScript, Python, and Ruby to give developers a familiar and powerful system that feels native for developers coming from any of these languages and an easy way to leverage the strength of any.

Blade also comes with Nyssa, the official package manager, which makes it easy to install and manage packages and modules.

Blade is NOT named after any weapon, but rather after the iconic Marvel Comics vampire slayer — Blade.

Features

  • First-class package management: Package management is built into the language module system.
  • Iterable classes: Blade has built-in support for iterable classes, making it easy to work with collections of data.
  • Backend development: Blade can be used for backend development without any external dependencies.
  • Function promotion: Blade allows for function promotion, making it easy to reuse any piece of code from an imported module.
  • Default exports and imports: Blade supports default exports and imports, making it easy to organize code.
  • Anonymous functions: Blade supports anonymous functions, making it easy to write functional code.
  • Access modifiers: Unlike any of JavaScript, Python and Ruby, Blade supports access modifiers for variables, properties, functions, classes, modules, etc.
  • Decorator functions: Blade supports decorator functions, making it easy to add functionality to existing code.
  • Function overrides: Blade supports function overrides in classes, allowing a class to choose the result to return for a function if the function allows it.
  • Easy to extend with C modules: Blade supports external extensions built in C, making it easy to extend the language with C modules.

Use Cases

Blade can be used for a wide range of tasks, including:

  • Web development: Blade can be used to create web applications and web services.
  • Data science: Blade can be used to perform data analysis and machine learning tasks.
  • Scripting: Blade can be used to write scripts to automate tasks.
  • And more...

Showcase

  • Nyssa: The Nyssa self-hostable repository server and package manager is written in Blade.
  • jsonrpc: A JSON-RPC library for Blade programming language.
  • wire: Dynamic HTML template engine.
  • tar: Pure Blade library for creating and extracting TAR archives.

How does it differ from Python and Ruby?

  • First-class package management (Package management is built into the language module system).
  • Iterable classes.
  • Backend development without any external dependencies.
  • Function promotion.
  • Default exports and imports.
  • Anonymous functions.
  • Access modifiers for variables, properties, function, class, modules, etc.
  • Decorator functions.
  • Function overrides in classes — A class can chose the result to return for a function if the function allows it.
  • Easy to extend with C modules with a familiar API to Wren.

Download

Windows   Linux   MacOS  

It is advisable to install Nyssa the official package manager after installing Blade. See installation instruction here.

  • This downloads only support x86-64 plaforms.
  • Apple M1 devices should install Rosetta 2 to run the downloaded application or install from source.
  • For other platforms, you'll need to install from source (see below for details).

Installing Blade from source

Blade currently supports and have been tested on the Linux, OSX and Windows operating system. To install Blade, you need to have CMake and a C/C++ compiler toolchain/IDE installed on your computer.

For Linux and macOS

If you are on a Unix, OSX or Linux machine, you can use the automated install tool by running the command below in your favorite terminal.

$ bash <(curl -s https://raw.githubusercontent.com/blade-lang/blade/main/scripts/install.sh)

For Windows

Starting from version 0.0.7, Blade's officially supported compilers for the Windows environment is now the TDM-GCC and WinLibs compiler. The decision to change the official compiler from Visual Studio and MSYS2 to TDM-GCC and WinLibs is to allow a minial configuration effort while installing Blade as well as to allow us to develop Blade faster as trying to be cross-compatible with Visual Studio has proven to slow down the growth of the language and the ecosystem and setting up MSYS2 environment to compile Blade is more work than required for either TDM-GCC or WinLibs.

This also allows us to build valid Blade C extensions on Windows with less hassle. Check out the blade-ext-demo or any of the extension in the packages directory for more info on how to write a valid C extension for Blade.

Important Notice

  1. Only TDM-GCC, WinLibs, MinGW64 and MSVC compiler have been tested and are currently guaranted to build Blade. While other compilers may build it, they are not currently recommended.
  2. For MSVC, a minimum of Windows SDK version 10.0.18362 is recommended. This will be readily available from Visual studio 2017 on Windows 10 and above.

To install Blade with TDM-GCC or WinLibs, install TDM-GCC or WinLibs via the given links. Add TDM-GCC or WinLibs bin directory to your environment path. TDM-GCC also allows you to add to path during its installation.

Dependencies

The following dependencies are required and can be installed via Cygwin or Vcpkg.

  • CMake
  • OpenSSL
  • Curl
  • Libffi

After this, run the following commands from the root of your Blade clone:

git clone https://github.com/blade-lang/blade.git
cd blade
cmake -B . -DCMAKE_MAKE_PROGRAM=mingw32-make -G "Unix Makefiles"
cmake --build .

If your dependencies were installed via Vcpkg, you may need to reference the Vcpkg toolchain. E.g.

git clone https://github.com/blade-lang/blade.git
cd blade
cmake -B . -DCMAKE_MAKE_PROGRAM=mingw32-make -G "Unix Makefiles" -DCMAKE_TOOLCHAIN_FILE=PATH_TO_VCKPG\scripts\buildsystems\vcpkg.cmake
cmake --build .

This will build and install Blade into a new directory called blade within the current directory. You can move this directory to any location on your computer.

To make Blade (blade) available from your terminal, you'll need to add the generated blade directory to your computer paths.

See this, this or this Stack overflow questions for information on adding Blade installation directory to path.

For all other platforms

For environments without an autoinstall and the adventurous ones, to install Blade, so far as you can successfully setup git, cmake and one of GCC or Clang based compilers, you can use the following commands to install Blade:

$ git clone https://github.com/blade-lang/blade.git
$ cd blade
$ cmake -B .
$ cmake --build .

See the Windows section above for a list of dependencies.

See BUILDING for more details.

Running the Blade REPL

Blade comes with support for REPL (Read-Evaluate-Print-Loop). The REPL mode is triggered when calling the Blade (blade) executable without any file.

Something like this:

$ blade
Blade 0.0.85 (running on BladeVM 0.0.9), REPL/Interactive mode = ON
Clang 13.0.0, (Build time = Feb  8 2022, 02:47:36)
Type ".exit" to quit or ".credits" for more information
%> echo 'Hello, World'
'Hello, World'
%>

To exit the loop, simply type .exit and press enter or press the Ctrl+D combination on your keyboard.

We'll be using this mode a lot in this documentation.

Running a Blade script

The blade command can take a file as parameter and execute the file as simply as follows:

$ blade somefilename.b
...

Did you notice how the filename ends with a .b? Blade program files should make use of the .b extension. This is the recommended convention.

It is important to remember that:

While Blade may not enforce the .b extension for all scripts, it is a requirement for a script that is meant to be imported as a module into another program.

Editor Support

For editor support, we recommend Visual Studio Code along with the blade-vscode Extension{:target="_blank"}. Support for more editors are planned and on the way.

Blade CLI options

Blade CLI comes with lots of options to control how Blade runs and how it runs your scripts.

Type:

$ blade -h

to show the CLI options. It should look something like this.

Usage: blade [-[h | c | d | e | j | v | g | w]] [filename]
   -h       Show this help message.
   -v       Show version string.
   -b       Buffer terminal outputs.
            [This will cause the output to be buffered with 1kb]
   -d       Print bytecode.
   -e       Print bytecode and exit.
   -j       Show stack objects during execution.
   -g arg   Sets the minimum heap size in kilobytes before the GC
            can start. [Default = 1024 (1mb)]
   -c arg   Runs the give code.
   -w       Show runtime warnings.

This help message will automatically be triggered when you try to use an unsupported switch.

For example, to get the version of Blade installed:

$ blade -v
Blade 0.0.85 (running on BladeVM 0.1.0)

Community

  • Join the conversation on Gitter

Contributing

Blade desire to make the community around it as friendly and welcoming as possible. Therefore, all forms of contributions from pull requests, suggestions, typo fixes in documentation, feature request, bug reports and any contribution at all is highly appreciated. Please refer to the Contributing guide for more information.

You can also mail your issues to Ore Richard Muyiwa directly.

WE NEED HELP! From review of this documentation, to suggestions on the core features of Blade, testing of Blade features, writing more comprehensive tests, bug detection, code fixes and more. PLEASE CONTRIBUTE!