I understand a "macro" to mean some code that is translated by the compiler into some other code in the source language. The macros described here seem more like built-in functions/varieties than macros to me. It might be nice to clarify how these constructs act as macros instead of special built-in operators or generic functions.

Publish step-by-step documentation using an HTML documentation rendering system.

When I run:

ko play github.com/kocircuit/kocircuit/handbook/Root

I get some kind of code on stdout, but no files are generated, and that code is not HTML.
How do I make sense of it, or how else would I generate the handbook?

The type system description doesn't say whether a variety type can be part of option, sequence or struct types.

Likewise, the unification description does not seem to say how variety types fit within the unification algorithm,

Hi,

To trouble shoot #5 (comment) I started at kocircuit/lang/go/sys/compile.go:31 trying to figure out where the code went wrong.

However, the use of dot imports made it much more difficult to follow where functions and types were declared. For instance CompileRepo is used in sys but defined in compile, and since compile is imported with dot imports, the qualified identifier did not include the package name. This also made it more difficult to find the functions and interfaces defined in syntax.

I therefore propose to stop using dot imports in the implementation of the Ko compiler, to facilitate readability of the code. This is especially important to help outsiders (such as myself) getting familiar and up to speed with the code.

All in all, I must say I find Ko to be very interested, and I will keep a close eye going forward.

With kindness,
Robin

E.g. arguments that are followed by "!" in the declaration must be passed.
E.g, if F is declared as:

F(a, b!, c!) { ... }

Then the invocation F(b: 1, c: "abc") is correct. Whereas F(b: 1) is not correct, as "c" is required and not passed.

Linked from "To get the Aljabr compiler and codelabs, go to https://github.com/aljabrio/aljabrio" in https://kocircuit.github.io/quick/index.html

Broken link: https://github.com/aljabrio/aljabrio

I followed the starting instructions, but "ko play" doesn't seem to want to play with me.

% ko play github.com/kocircuit/kocircuit/codelab/HelloWorld
(/home/rog/src/go/src/kocircuit/kocircuit/lang/go/sys/compile.go:31) (ko/R0) compiled functions=0 steps=0 steps-per-function=0.00
cannot find main circuit github.com/kocircuit/kocircuit/codelab/HelloWorld

It is not clear what the correct argument to "ko play" should be. The go play help doesn't document its positional arguments.

E.g. make A + B be equivalent to Sum(A, B), and so on.

In this document, we see that the ko struct tags define the Ko field name with a name=x tag directive. For example:

type GoMaxInt64 struct {   // gate argument structure
    X int64 `ko:"name=x"`   // The Ko field name is specified in a tag.
    Y int64 `ko:"name=y"`   // There are no restrictions on field types.
}

Since almost every single other serialization package encodes the name without an explicit name= prefix, and this is likely to be the most frequent tag attribute, then why not go with the usual Go convention?

type GoMaxInt64 struct {   // gate argument structure
    X int64 `ko:"x"`   // The Ko field name is specified in a tag.
    Y int64 `ko:"y"`   // There are no restrictions on field types.
}

Topics that should be covered:

• How to build
• How to test
• How to version & release

It would be nice to support go modules by adding a go.mod file.

Using:

go mod init
go mod tidy

produces a compiling (but not necessarily working) module.

In the macro docs, it says:

Equal determines if its argument values are equal. It expects a monadic sequence argument.

but the docs don't seem to clarify exactly what a monadic sequence argument means. Is it a single-element sequence? A sequence of basic types? A sequence of one argument varieties?

Arguments whose name begins with underscore are waited on, but not passed to the called function.

Support multiple colon-separated repo roots in KOPATH, searched in the order given.
This generalizes the notion of having a separate KOROOT and KOPATH variables.

Add support for unit tests (similar to go)

• Only include *_test.ko files during testing
• Add ko test <pkg> command
• Add Assert like function(s)

Such that go get ... (with go 1.11) is also used to fetch Ko modules.

I see 404 on both:

• https://kocircuit.github.io/
• https://kocircuit.github.io/kocircuit/

I've probably missed something, but the unification rules seem incomplete.
Are there any unifications rules between different integer sizes, for example?

Perhaps something like this might suffice (assuming that's what you had in mind):

When two basic types p and q are being unified, U(p, q), the unification fails unless p and q are of the same basic type.