Imports and Modules

RayQuiro 0.1.0 supports local file imports, built-in system namespaces, source frameworks, and official installable native modules.

---

📋 Import Syntax

Full Alias Import

import "path/to/module.rq" as alias;
alias.someFunction();

Selective Import

from "path/to/module.rq" import functionName, otherName;
functionName();

Module Alias Import

from "path/to/module.rq" import functionName as myFunc, label as myLabel;
myFunc();

---

🗂️ What You Can Import

Source	How	Example
Local .rq files	Path string	import "./lib/math.rq" as math;
Built-in system namespaces	Namespace name	import rayquiro.fs as fs;
Source frameworks	Installed name	import telebot as bot;
Native modules	Module name	import rayquiro.engine as engine;

---

🔧 Built-In System Namespaces

These are compiled directly into rqio and do not require installation:

import rayquiro.fs as fs;
import rayquiro.env as env;
import rayquiro.process as process;
import rayquiro.time as time;
import rayquiro.json as json;
import rayquiro.os as os;
import rayquiro.net as net;
import rayquiro.http as http;
import rayquiro.db as db;

You can also use selective imports:

from rayquiro.fs import write, read, exists;
from rayquiro.time import now_ms, sleep;
from rayquiro.json import parse, stringify;

---

📦 Official Installable Native Modules

These require installation via rqio install. They are distributed as compiled .dll files:

import rayquiro.web as web;
import rayquiro.ui as ui;
import rayquiro.app as app;
import rayquiro.engine as engine;

Install them with:

rqio install rayquiro.web
rqio install rayquiro.ui
rqio install rayquiro.app
rqio install rayquiro.engine

Engine Alias

The legacy raytolfas.engine namespace is also accepted for backwards compatibility:

import raytolfas.engine as engine;

---

📁 Source Frameworks

Source frameworks are .rq source libraries installed into your module directory. They are different from native .dll modules.

Install from GitHub:

rqio framework install RayQuiro/Telebot
rqio framework install RayQuiro/Telebot@main
rqio framework install RayQuiro/Telebot --local

Install from the approved registry:

rqio install telebot
rqio install telebot --local

After installing, import by registered name:

import telebot as bot;

---

🛠️ Custom Frameworks & rqframework.json

You can easily package and publish your own .rq libraries as reusable frameworks. To create a custom framework:

1. Create a GitHub repository (e.g. yourusername/logger).
2. Add a rqframework.json manifest file to the root of the repository. This describes the framework metadata.
3. Add your library code. By default, RayQuiro looks for main.rq or <repo-name>.rq (e.g., logger.rq) as the entry point when a user imports the framework.

Manifest File (rqframework.json)

The manifest defines package metadata, dependencies, and authors:

{
  "name": "logger",
  "version": "1.0.0",
  "description": "A simple structured logger framework for RayQuiro.",
  "author": "yourname",
  "entry": "main.rq"
}

Installing Custom Frameworks

Users can install your custom framework directly using its GitHub repository specification:

# Install globally
rqio framework install yourusername/logger

# Install project-local
rqio framework install yourusername/logger --local

Usage in Code

Once installed, users can import it by its framework name:

import logger;
logger.info("Custom framework successfully resolved!");

For the full publishing guide, including repository structure, the approved registry format, and best practices, see Creating Frameworks.

---

📍 Module Resolution Order

When rqio encounters a non-built-in import, it resolves it in this order:

1. Direct local paths — "./lib/math.rq", "../shared/utils.rq"
2. Project-local source modules — ./.rq_modules/
3. Project-local native modules — ./.rq_modules/native/
4. User-level source frameworks — %USERPROFILE%/.rqio/frameworks
5. User-level native modules — %USERPROFILE%/.rqio/modules
6. Machine-level native modules — C:\Program Files\RayQuiro\modules

---

🏗️ Module File Pattern

A typical local library file lib/math.rq:

fn sum(a, b) {
    return a + b;
}

fn multiply(a, b) {
    return a * b;
}

Then in main.rq:

import "./lib/math.rq" as math;

print(math.sum(7, 5));      // 12
print(math.multiply(4, 9)); // 36

Or selectively:

from "./lib/math.rq" import sum, multiply;
print(sum(7, 5));

---

💡 Best Practices

• Keep shared project utilities in ./lib/ or ./src/.
• Install project-specific source frameworks locally with --local to avoid global pollution.
• Install native modules globally only when reused across many projects.
• Use short, clear aliases when importing namespaces (e.g. as fs, as engine, as time).
• Avoid circular imports — structure your code so dependencies flow in one direction.