Modules, tests and laws
Slide 40 of 85
40importModules, tests and laws

Modules

Grammar: import, file
importPATHasIDENT
import = "import" PATH [ "as" IDENT ] ;
importdeclarationEOF
file = { import | declaration } EOF ;As the compiler reads it; §2.1 of the specification is out of date here.

import brings another file's declarations into scope, reached through a name. The path says what kind of import it is:

  • import ./lib/text is a Hive file on disk, relative to the importing file's own folder, with the .hive left off. A path with spaces is quoted: import "./lib dir/text" as words.
  • import https://github.com/owner/repo/src/text is a file inside a git repository.
  • import hive.net as web names a standard library module. Every module already answers to its own name with no import — crypto.sha256 is hive.crypto.sha256 — so importing one only gives it another name. A module adds nothing to the build unless it is used.

The name is the file's own, or the module's last segment, unless as gives another. It is camelCase, so a file whose name is not one — text-utils.hive — has to be imported with as, and no import may be named hive. An import names a module and nothing inside it, so import hive.ui.View is refused, and so is a module the library does not have.

A library module's own name is held the way a builtin's is: a declaration, an import, a local or a parameter of the same name comes first, in that file only, and hive.<module> always reaches the library.

Everything a module declares is visible; there is no pub. A name only ever means what the module you are reading says it means, so two files may each declare their own Align and both stay distinct, the other file's being text.Align. An imported callable is an ordinary value. An error inside an imported file is reported in that file, with names as its source spells them.

A remote import needs git on the PATH. The repository is https://host/owner/repo and the rest is the path inside it; a revision goes where the repository ends — a commit of at least seven hex digits, a tag, or a branch, which is followed wherever it moves. Clones are cached once per commit under ~/.hive/pkg. An import with no revision is pinned on first use: the commit it resolved to is written into a lock file beside the entrypoint, main.hive-lock, which belongs in version control. One with a revision asks the repository what it names on every check and build. Import cycles are refused, and the error prints the loop.

A library module, by its own name
import hive.net as web

proc main(): void {
	// Every library module answers to its own name, with no import.
	echo crypto.sha256("hive")

	// `hive.` is the long spelling of the very same call.
	echo hive.crypto.sha256("hive")

	// `as` gives a module another name.
	if web.resolve("localhost") is Result.Ok(addresses) {
		echo addresses
	}

	// A name of the program's own comes first, as it does over a builtin,
	// and the library is still `hive.time`.
	time := "half past nine"
	echo time
	echo hive.time.year() > 2000
}
lib/text.hive
type Align {
	Left
	Right
}

func pad(s: Str, width: Int, side: Align): Str {
	mut out := s
	for ; len(out) < width; {
		if side is Align.Left { out = out + "." } else { out = "." + out }
	}
	return out
}

func repeat(s: Str, times: Int): Str {
	mut out := ""
	for i := 0; i < times; i++ { out = out + s }
	return out
}
main.hive, beside it
import ./lib/text

// This file's Align and lib/text's Align are two different types: a name
// only ever means what the module you read it in says it means.
type Align {
	Centre
}

proc main(): void {
	mine := Align.Centre()
	if mine is Align.Centre { echo "ours" }

	echo text.pad("total", 16, text.Align.Left())

	// An imported callable is an ordinary value.
	rule := text.repeat("~", _)
	echo rule(16)
}
A module in a repository
// The repository is `https://host/owner/repo`; everything after it is the
// path inside it, and the .hive is left off exactly as it is on disk.
import https://github.com/owner/repo/src/text

// A revision goes where the repository ends: a commit, a tag or a branch.
import https://github.com/owner/[email protected]/src/pricing

// A Go file inside one, under the same rules — .go still compulsory.
import https://github.com/owner/repo@a1b2c3d/go/slugs.go as slugs

proc main(): void {
	// The name is the file's, not the repository's or the host's: moving a
	// module out to one changes nothing about how this line reads.
	echo text.repeat("=", 28)
	echo pricing.line("Beeswax", 450)
	echo slugs.slugify("Hive Tool")
}
What the first build leaves behind
$ hive check main.hive
No problems found in main.hive (3s)

$ cat main.hive-lock
# Written by the Hive compiler: the commit each remote import was
# resolved to. Keep this in version control — it is what makes another
# machine build the same program. Delete a line to take the latest of
# that repository again.
https://github.com/owner/repo 4f2a9c1e8b7d6a5f4e3d2c1b0a9f8e7d6c5b4a39
A cycle, refused
$ hive check main.hive
lib/pricing.hive:1: this import forms a cycle:

    lib/inventory.hive
      -> lib/pricing.hive
      -> lib/inventory.hive