glojure

module
v0.2.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 4, 2024 License: EPL-1.0

README

Glojure

example workflow

Try it in your browser! (fair warning: startup on the web is slow)

Gopher image

Gopher image derived from @egonelbre, licensed under Creative Commons 1.0 Attributions license.

Glojure is an interpreter for Clojure, hosted on Go. Glojure provides easy access to Go libraries, similar to how Clojure provides easy access to Java frameworks.

Glojure is in early development; expect bugs, missing features, and limited performance. Backwards compatibility is not guaranteed until a v1 release. That said, it is used successfully in hobby projects and runs a significant subset of the (transformed) core Clojure library.

Note that unlike most other Go implementations of Clojure, Glojure is a "hosted" language - a term used to describe languages that are implemented in terms of a host language (in this case, Go). This means that all Go values can be used as Glojure values and vice versa.

Prerequisites

Before you get started with Glojure, make sure you have installed and have knowledge of Go (version 1.19 or higher).

Installation

Glojure is currently available from source for all platforms where Go can run, and it requires at least go 1.19.

Install it with the go install command:

$ go install github.com/glojurelang/glojure/cmd/glj@latest

After installation, you can start the REPL (Read-Eval-Print-Loop) with the glj command:

$ glj
user=> (println "Hello, world!")
Hello, world!
nil
user=>

Usage

Here's a small example program that starts an HTTP server with a simple handler function that responds with the request body:

;; example.glj
(ns example.server)

(defn echo-handler
  [w r]
  (io.Copy w (.Body r))
  nil)

(net$http.Handle "/" (net$http.HandlerFunc echo-handler))

(net$http.ListenAndServe ":8080" nil)

Run it with the glj command:

$ glj ./example.glj
$ curl localhost:8080 -d "sicp"
sicp
Interop

Glojure ships with interop with many standard library packages out-of-the-box. Go package names are munged to avoid ambiguity with the use of / to refer to namespaced symbols; instances of / in package names are replaced with $. Here's a simple example:

user=> (println (fmt.Sprintf "A couple of HTTP methods: %v" [net$http.MethodGet net$http.MethodPost]))
A couple of HTTP methods: ["GET" "POST"]
nil

The following standard library packages are included by default:

  • bytes
  • context
  • errors
  • flag
  • fmt
  • io
  • io/fs
  • io/ioutil
  • math
  • math/big
  • math/rand
  • net/http
  • os
  • os/exec
  • os/signal
  • regexp
  • reflect
  • sort
  • strconv
  • strings
  • sync
  • sync/atomic
  • time
  • unicode

To expose additional packages, you must generate a "package map" and compile your own executable that imports both your package map and the Glojure API. See the section below for more details.

Expect improvements to both the availability of standard library packages and interop workflows.

Accessing additional Go packages

The gen-import-interop can be used to emit the contents of a .go file that will export a function that can be used to add the exports of additional packages to the Glojure package map.

$ go run github.com/glojurelang/glojure/cmd/gen-import-interop \
     -packages=:comma-separated-package-list: \
     > your/package/gljimports/my_package_map.go

Then, in your own program:

package main

import (
	// Add your packages' exports to the pkgmap.
	_ "your.package/gljimports"
)

// ...

Differences from Clojure

Numbers
Clojure Type Glojure Type Notes
long int64
double float64
float float32
double float64
byte byte Note that Go bytes are unsigned, whereas JVM bytes are signed.
short int16
int int Note that JVM ints are 32-bit, whereas Go ints are 32- or 64-bit depending on the platform.
char lang.Char The Glojure type is a tagged rune (type Char rune). JVM chars are 16-bit whereas Go runes are 32-bit.
BigInt *lang.BigInt The Glojure type wraps *big.Int.
BigDecimal *lang.BigDecimal The Glojure type wraps *big.Float.
Ratio *lang.Ratio The Glojure type wraps *big.Rat.
BigInteger *big.Int Native JVM BigInteger corresponds to *big.Int.

Comparisons to other Go ports of Clojure

Aspect Glojure Joker let-go
Hosted[^1] Yes No No
Extensible Go interop Yes No No
Concurrency Yes Yes (with GIL) Yes
Clojure tooling (e.g. linter) No Yes No
Execution Tree-walk interpreter Tree-walk interpreter Bytecode Interpreter

If you'd like to see another port in this table, or if you believe there is an error in it, please file an issue or open a pull request!

[^1]: What does it mean to be a hosted language? For Clojure on the JVM, it means that all Java values are also Clojure values, and vice versa. Glojure strives to maintain the same relationship with Go.

Directories

Path Synopsis
cmd
glj
internal
persistent/vector
Package vector implements persistent vector.
Package vector implements persistent vector.
seq
Package seq provides a definition of an internal Seq interface for use across packages.
Package seq provides a definition of an internal Seq interface for use across packages.
pkg
ast
gen/gljimports
GENERATED FILE.
GENERATED FILE.
glj
Package glj provides a minimal interface to bootstrap Glojure access from Go.
Package glj provides a minimal interface to bootstrap Glojure access from Go.
stdlib
Package stdlib provides the standard library for the mratlang language.
Package stdlib provides the standard library for the mratlang language.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL