Quest Documentation

Modules #

Import Syntax #

Quest supports flexible module import syntax:

Standard Library Modules #

Import built-in modules by name (no quotes):

use math
use os
use term
use hash
use json
use io

Available standard library modules:

  • math - Mathematical functions and constants (sin, cos, pi, etc.)
  • os - Operating system utilities and module search paths
  • term - Terminal colors and formatting
  • hash - Hashing functions (MD5, SHA, etc.)
  • json - JSON parsing and serialization

External Files with Automatic Aliases #

Import .q files and Quest automatically derives the alias from the filename:

use "utils/helpers"      # Imports as "helpers" (derived from filename)
use "lib/math/advanced"  # Imports as "advanced"
use "std/test"           # Imports as "test"

The .q extension is optional and will be added automatically:

use "utils/helpers.q"    # Same as use "utils/helpers"
use "utils/helpers"      # Automatically becomes "utils/helpers.q"

Explicit Aliases with as Keyword #

Use the as keyword to specify a custom alias:

use "std/test" as test_framework
use "utils/helpers" as utils
use "lib/math/advanced" as math

External Modules #

Module Search Path #

When importing external modules with use "path" or use "path" as alias, Quest searches for the module file in the following order:

  1. Current working directory - Always checked first (.)
  2. Development lib directory - Local lib/ folder (for Quest developers)
  3. Directories in os.search_path - User-modifiable at runtime
  4. Directories from QUEST_INCLUDE environment variable - Set before starting Quest
  5. Installed standard library - ~/.quest/lib/ (auto-extracted on first run)

First-Run Installation #

When you first run Quest (after cargo install vibequest), the standard library is automatically extracted to ~/.quest/lib/:

$ quest --version
Quest version 0.1.5
Quest standard library installed to: /home/user/.quest/lib

Subsequent runs are silent. You can customize the standard library by editing files in ~/.quest/lib/.

Search Path Priority #

The search path is constructed with this precedence:

  1. Current directory (implicit, always first) - ./module.q
  2. Development lib/ - lib/module.q (takes precedence for Quest developers)
  3. Paths in os.search_path - User-modifiable at runtime (highest priority for custom additions)
  4. QUEST_INCLUDE paths - Loaded from environment variable at startup
  5. ~/.quest/lib/ - Extracted standard library (fallback for installed binary)

Using QUEST_INCLUDE #

Set the QUEST_INCLUDE environment variable to add default module search directories:

# Unix/Linux/macOS (colon-separated)
export QUEST_INCLUDE="/usr/local/lib/quest:/home/user/quest_modules"
./quest

# Windows (semicolon-separated)
set QUEST_INCLUDE=C:\quest\lib;C:\Users\user\quest_modules
quest.exe

Runtime Path Inspection #

You can inspect the search path at runtime using array methods:

use os

# View current search paths
puts("Search paths:", os.search_path)
puts("Length:", os.search_path.len())

# Get first and last paths
if os.search_path.len() > 0
    puts("First path:", os.search_path.first())
    puts("Last path:", os.search_path.last())
end

Note: Direct assignment to module members (os.search_path = ...) is not yet supported. The search path must be set via the QUEST_INCLUDE environment variable before starting Quest.

See the Array type documentation for available array methods: push, pop, shift, unshift, first, last, get, len.

Example: Module Resolution #

Given this search configuration:

  • Current directory: /home/user/project
  • Development lib: lib/ exists in current directory
  • os.search_path: ["/opt/quest/modules"]
  • QUEST_INCLUDE: /usr/local/share/quest
  • Installed stdlib: ~/.quest/lib/ exists

When you execute use "std/math", Quest searches in order:

  1. /home/user/project/std/math.q (current directory)
  2. /home/user/project/lib/std/math.q (development lib)
  3. /opt/quest/modules/std/math.q (os.search_path)
  4. /usr/local/share/quest/std/math.q (QUEST_INCLUDE)
  5. /home/user/.quest/lib/std/math.q (installed stdlib)

The first file found is loaded as the module.

For Quest developers: The local lib/ directory takes precedence, so you can test changes without reinstalling.

For end users: After cargo install vibequest, modules load from ~/.quest/lib/, which you can customize.

Module Not Found Error #

If a module cannot be found in any search location, Quest reports an error:

use "nonexistent.q" missing
# Error: Module 'nonexistent.q' not found in current directory or search paths: [/opt/quest/modules, /usr/local/share/quest]
Edit this page