Humal 1.4.0

Added

1. Browser runtime: a web namespace for accessing browser functionality from Humal.
2. DOM helpers: web.element(), web.text(), web.value(), and web.button() for working with page elements.
3. Event handling: web.on(), web.off(), and web.button().onClick() for registering and removing event listeners.
4. Browser API access: access to window, document, navigator, Fetch, Web Crypto, and other available browser APIs.
5. Storage support: convenient lowercase aliases for Local Storage, Session Storage, and IndexedDB.
6. Asynchronous browser code: browser programs can use Humal's async fn and await syntax.
7. Parcel transformer: a custom transformer that compiles .hum files and connects browser applications to the Humal Web runtime.
8. Browser environment configuration: the env option in humal.config.json allows projects to select browser-specific tooling behavior.
9. Browser input compatibility: browser handling for programs that use Humal's input syntax.

Improvements

1. Runtime validation: browser-only functionality reports a clear error when used outside a browser.
2. Element handling: DOM helpers accept CSS selectors and supported existing element objects.
3. Error reporting: missing elements and invalid event callbacks produce explicit errors.
4. Browser method binding: callable browser properties are bound to the appropriate context when needed.
5. Constructor handling: browser constructors are distinguished from regular methods.
6. Cleaner UI code: common DOM operations can be expressed with Humal helpers.
7. Tooling integration: browser projects can use browser-specific type declarations and lint configuration when the project tooling is configured for env: "browser".

Getting started

1. Install Humal

npm install -g @qvelop444/humal

2. Create a browser project

Run:

humal init myapp --env browser
cd myapp
npm install

Humal initializes the browser project, including the configuration, HTML entry point, Parcel configuration, and npm scripts.

The generated project structure is:

myapp/
├── index.html
├── .parcelrc
├── humal.config.json
├── package.json
├── .gitignore
└── src/
    └── main.hum

3. Browser environment configuration

Humal creates humal.config.json with the browser environment enabled:

{
  "entry": "src/main.hum",
  "sourceDir": "src",
  "module": "esm",
  "env": "browser",
  "webEntry": "index.html"
}

The env option enables browser-specific tooling behavior. The webEntry option identifies the HTML entry point used by Parcel.

4. Write your first browser application

The generated index.html references src/main.hum. Replace the contents of src/main.hum with:

web.document.title = "Humal Web"

web.text("#status", "Ready")

fn saveName()
    let name = web.value("#name")
    web.localstorage.setItem("name", name)
    web.text("#status", "Saved: " + name)

web.value("#name", web.localstorage.getItem("name") ?? "")

web.button("#save").onClick(saveName)

This example demonstrates DOM manipulation, event handling, and persistent browser storage using Humal syntax.

5. Run the development server

Start Parcel through Humal:

npm run dev:web

Open the local URL printed by Parcel in your terminal, usually http://localhost:1234/.

Create a production build with:

npm run build:web

The production build is written to Parcel's output directory, normally dist/.

Manual Parcel configuration

This section is intended for existing projects that want to add Humal Web without using the browser project template.

Install the required packages:

npm install --save-dev parcel @qvelop444/humal

Create a .parcelrc file in the project root:

{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.hum": [
      "./node_modules/@qvelop444/humal/src/parcel.js"
    ]
  }
}

The relative path points to Humal's Parcel transformer inside the installed npm package. Parcel uses this transformer to compile .hum files into JavaScript.

Configure the npm scripts in package.json:

{
  "scripts": {
    "dev:web": "humal dev:web",
    "build:web": "humal build:web"
  }
}

Ensure that humal.config.json specifies "env": "browser" and that index.html references the correct .hum entry point.

The web API

DOM helpers

API	Description
web.document	Access the browser document
web.window	Access the browser window
web.element(target)	Resolve a selector or element
web.text(target, value)	Set an element's text
web.value(target)	Read an element's value
web.value(target, value)	Set an element's value
web.button(target)	Access button helper methods
web.on(target, event, callback, options)	Register an event listener
web.off(target, event, callback, options)	Remove an event listener
web.ready(callback)	Run a callback when the DOM is ready
web.alert(message)	Show a browser alert

The button helper supports .onClick(), .text(), and .disable().

Browser API aliases

Humal Web provides lowercase aliases for selected browser APIs:

web.localstorage
web.sessionstorage
web.indexeddb
web.urlsearchparams
web.abortcontroller
web.intersectionobserver
web.mutationobserver
web.resizeobserver
web.websocket
web.sharedworker
web.broadcastchannel
web.textencoder
web.textdecoder
web.formdata
web.filereader

These aliases expose the corresponding browser objects through the web namespace. Their availability depends on browser support and the execution environment.

Network requests and asynchronous code

async fn loadData()
    let response = await web.fetch("/api/data")

    if !response.ok
        throw new Error("Request failed")

    let data = await response.json()
    web.text("#status", JSON.stringify(data))

web.button("#load").onClick(loadData)

Network errors and HTTP error responses should be handled separately. For example, fetch() does not normally reject just because a server responds with status 404 or 500; check response.ok or response.status.

Install the VS Code extension

Download the .vsix file, then in VS Code go to the Extensions view, click the three dots, select Install from VSIX..., and choose the downloaded .vsix file.

Humal 1.3.0

Added

1. Added switch statement support.
2. Added indentation-based case clauses.
3. Added default clause support.
4. Added support for multiple case labels and JavaScript fall-through behavior.
5. Added support for break inside switch.
6. Added support for JavaScript expressions in case conditions.
7. Added support for nested switch statements.
8. Added support for existing Humal constructs inside case bodies.

Examples

Basic switch

let value = 2

switch value
    case 1
        print "one"
        break

    case 2
        print "two"
        break

    default
        print "other"

Multiple case labels

let value = 2

switch value
    case 1
    case 2
    case 3
        print "one, two or three"
        break

    default
        print "other"

Expressions in case

let value = 10

switch value
    case 5 + 5
        print "expression works"
        break

    default
        print "no match"

Improvements

1. Improved indentation handling for switch statements.
2. Enhanced compiler support for JavaScript control flow constructs.
3. Continued focus on keeping Humal syntax close to JavaScript while using indentation instead of block punctuation.
4. Improved the VS Code extension: the global Humal Dark theme was removed, and syntax handling was enhanced.

Install the VS Code extension

Download the .vsix file, then in VS Code go to the Extensions view, click the three dots, select Install from VSIX..., and choose the downloaded .vsix file.

Humal 1.2.0

Added

1. humal check for TypeScript and ESLint validation
2. humal fmt for Humal source formatting
3. humal watch for automatic rebuilding
4. humal dev for development mode with automatic rebuild and restart
5. Integrated TypeScript, ESLint and Prettier tooling

Improved

1. Improved CLI workflow
2. Improved project configuration with humal.config.json
3. Improved build and development workflow

Fixed

1. Fixed watcher process exiting immediately
2. Improved handling of build and tooling errors
3. Improved temporary file cleanup

The Humal VS Code extension itself remains unchanged in this release. Below, you will find the .vsix file and installation instructions.

Install the VS Code extension

Download the .vsix file, then in VS Code go to the Extensions view, click the three dots, select Install from VSIX..., and choose the downloaded .vsix file.

Humal 1.1.0

Humal 1.1.0

Compiler

1. Improved the compiler's internal architecture and structure.
2. Implemented stricter handling of strings, escape sequences, and comments.
3. Improved error reporting with line and column indicators in the source code.
4. Enhanced indentation checking via a new "Linear Indentation Tracker" mechanism.
5. Added structured parsing for Humal language constructs.
6. Improved import and export handling for ESM and CommonJS modules.
7. Improved input data processing.
8. Enhanced compatibility with JavaScript syntax, including object literals and object destructuring.
9. Added validation for generated JavaScript code.
10. Added basic Source Map support for linking and debugging generated JavaScript against Humal source code.
11. Improved preservation of source code line mappings during code transformations.

The Humal VS Code extension itself remains unchanged in this release. Below, you will find the .vsix file and installation instructions.

Install the VS Code extension

Download the .vsix file, then in VS Code go to the Extensions view, click the three dots, select Install from VSIX..., and choose the downloaded .vsix file.

Humal language support for VS Code

Official VS Code extension .vsix file for Humal programming language support.

What's inside ?:

With this extension, you get full editor support: syntax highlighting, indentation handling, snippets, autocomplete, tooltips, and an icon for .hum files.