hexowl is a Lightweight and flexible programmer’s calculator with user variables and functions support written in Go.

The main purpose of hexowl is to perform operations on numbers regardless of their base. A single expression can contain decimal, hexadecimal, and binary numbers.

Features

• Support for operations on decimal, hexadecimal and binary numbers;
• Bitwise operators;
• Boolean operators;
• User defined variables;
• User defined functions;
• Ability to save and load the working environment.

Installation

go install github.com/dece2183/hexowl@latest 

Building

There are no dependencies, so you can simply type a build command in the cloned repository folder.

go build

If you want to disable syntax highlighting, you can add the nohighlight tag:

go build -tags nohighlight

Reference

Operators

Built in constants

Built in functions

User functions

To declare a function, you must type its name, explain the arguments in ( ) and write the body of the function after -> operator.

It should look like this:

>: mul(a,b) -> a * b

Once declared, you can call this function as a builtin:

>: mul(2,4)

    Result: 8
            0x8
            0b1000

    Time:   0 ms

User function variations

You can also create variants of functions with expressions right in the explanation of the arguments.

Let’s look at a simple example of declaring a factorial function:

>: f(x == 0) -> 1
>: f(x > 0) -> x * f(x-1)

When calling such a function, the interpreter tries to find a suitable variant depending on the arguments passed, and then calls it.

Arrays and variadic arguments

You can define arrays with the enumerator operator ,:

>: x = 1,2,3,4

All functions receive arguments as an array, so the expressions foo(x) and foo(1,2,3,4) are similar.

There is a single @ keyword to handle such things. If it is specified as the last argument in a function declaration, it will receive an array of the arguments passed to it. The behavior is similar to the ... and __VA_ARGS__ preprocessor macros in C language.

An example of a function that calculates the sum of all elements of an array:

>: arrsum(a) -> a
>: arrsum(a, @) -> a+arrsum(@)

An example of a function that increments all elements of an array:

>: arrinc(v, a) -> a+v
>: arrinc(v, a, @) -> (a+v) , arrinc(v,@)

Integration guide

Hexowl is specially designed for use as an embeddable calculator.

An example of a minimal setup is shown below:

package main

import (
	"fmt"

	"github.com/dece2183/hexowl/operators"
	"github.com/dece2183/hexowl/utils"
)

const expresion = "2+2"

func main() {
	localVars := make(map[string]interface{})
	words := utils.ParsePrompt(expresion)

	operatorTree, err := operators.Generate(words, localVars))
	if err != nil {
		return err
	}

	result, err := operators.Calculate(operatorTree, localVars))
	if err != nil {
		return err
	}

	fmt.Printf("%s = %v", expresion, result);
}

For more specific designs, it is posible to provide an sdtout writer and callbacks for working with environment save files.

package main

import (
	"bytes"
	"fmt"
	"io"

	"github.com/dece2183/hexowl/builtin"
)

type dummyCloser bytes.Buffer

var outbuff = &bytes.Buffer{}
var envFiles map[string]*dummyCloser

func (dc *dummyCloser) Close() error {
	return nil
}

func (dc *dummyCloser) Read(dest []byte) (int, error) {
	b := bytes.Buffer(*dc)
	return b.Read(dest)
}

func (dc *dummyCloser) Write(data []byte) (int, error) {
	b := bytes.Buffer(*dc)
	return b.Write(data)
}

func init() {
	sysDesc := builtin.System{
		Stdout: outbuff,
		ListEnvironments: func() ([]string, error) {
			return maps.Keys(envFiles), nil
		},
		WriteEnvironment: func(name string) (io.WriteCloser, error) {
			if _, ok := envFiles[name]; !ok {
				envFiles[name] = &dummyCloser{}
			}
			return envFiles[name], nil
		},
		ReadEnvironment: func(name string) (io.ReadCloser, error) {
			if _, ok := envFiles[name]; !ok {
				return nil, fmt.Errorf("not found")
			}
			return envFiles[name], nil
		},
	}

	// Now all the additional output will be printed in outbuff.
	// And environment files will be seved to and loaded from envFiles map.
	builtin.SystemInit(sysDesc)
}

There are also functions for registering and manage self-written built-in functions and constants. They are described in hexowl/builtin package.