qlang

README

Q Language - A script language for Go

语言特色

• 与 Go 语言有最好的互操作性。可不进行任何包装即可直接使用 Go 语言的函数、类及其成员变量和方法。
• 有赖于 Go 语言的互操作性，这门语言直接拥有了一套非常完整且您十分熟悉的标准库，无额外学习成本。
• 与 Go 十分相近的语法，降低您的学习成本。
• 支持 Go 绝大部分语言特性，包括：for range, string, slice, map, chan, goroutine, defer, etc。
• 微内核：语言的核心只有大约 1200 行代码。所有功能以可插拔的 module 方式提供。

预期的商业场景：

• 由于与 Go 语言的无缝配合，qlang 在嵌入式脚本领域有 lua、python、javascript 所不能比拟的优越性。比如：网络游戏中取代 lua 的位置。
• 作为编译原理的教学语言。由于 qlang 的 Compiler 代码极短，便于阅读和理解，非常方便教学实践之用。

快速入门

在您的 Go 代码中整合 qlang

import (
	"fmt"
	"log"
	"strings"

	"github.com/qiniu/qlang"
	_ "github.com/qiniu/qlang/lib/builtin" // 导入 builtin 包
)

var strings_Exports = map[string]interface{}{
	"replacer": strings.NewReplacer,
}

func main() {

	qlang.Import("strings",	strings_Exports) // 导入一个自定义的包，叫 strings（和标准库同名）
	ql := qlang.New()

	err := ql.SafeEval(`x = strings.replacer("?", "!").replace("hello, world???")`)
	if err != nil {
		log.Fatal(err)
		return
	}

	fmt.Println("x:", ql.Var("x")) // 输出 x: hello, world!!!
}

这是一个功能最精简功能的迷你版 qlang。

想要了解更多，可参考“定制 qlang”相关内容。实际项目中你也可以参考代码：

• qshell.go
• qlang/main.go

非嵌入式场景下使用 qlang

尽管我们认为 qlang 的优势领域是在与 Go 配合的嵌入式场景，但您也可以把 qlang 语言用于非嵌入式脚本领域。

您可以直接通过 qlang 命令行程序来执行 *.ql 的代码。如下：

qlang xxx.ql <arg1> <arg2> ... <argN>

为了方便学习 qlang 工作机理，我们支持导出 qlang 编译的 “汇编指令”：

QLANG_DUMPCODE=1 qlang xxx.ql <arg1> <arg2> ... <argN>

在 Unix 系的操作系统下，您可以在 xxx.ql 文件开头加上：

#!/usr/bin/env qlang

并给 xxx.ql 文件加上可执行权限，即可直接运行 xxx.ql 脚本。

使用 qlang shell

命令行下输入 qlang 命令（不带参数），直接进入 qlang shell。

您同样也可以设置 QLANG_DUMPCODE 环境变量来学习 qlang 的工作机理：

QLANG_DUMPCODE=1 qlang

学习 qlang 语言特性

• Q 语言手册: 这里有语言特性的详细介绍。
• Qlang Tutorials: 这里是一些 qlang 的样例代码，供您学习 qlang 时参考。

下载

发行版本

• https://github.com/qiniu/qlang/releases

最新版本

go get github.com/qiniu/qlang

社区资源

Embedded qlang (eql)

• eql: 全称 embedded qlang，是类似 erubis/erb 的东西。结合 go generate 可很方便地让 Go 支持模板（不是 html template，是指泛型）。

为 Go package 导出 qlang module

• qexport: 可为 Go 语言的标准库或者你自己写的 Go Package 自动导出相应的 qlang module。

Qlang Modules

• 准官方库: https://github.com/qlangio/libs
• 第三方库: https://github.com/qlang-libs

IDE 插件

• liteide - https://github.com/visualfc/liteide
• sublime - https://github.com/damonchen/sublime-qlang
• vim - https://github.com/simon-xia/vim-qlang
• atom - https://github.com/bingohuang/atom-language-q

Documentation

Index

• Variables
• func Debug(fn func())
• func Import(mod string, table map[string]interface{})
• func SetAutoCall(t reflect.Type)
• func SetDumpCode(dumpCode string)
• func SetFindEntry(fn func(file string, libs []string) (string, error))
• func SetOnPop(fn func(v interface{}))
• func SetReadFile(fn func(file string) ([]byte, error))
• type Options
• type Qlang
  • func New() *Qlang
  • func (p *Qlang) Cl(codeText []byte, fname string) (end int, err error)
  • func (p *Qlang) Eval(expr string) (err error)
  • func (p *Qlang) Exec(codeText []byte, fname string) (err error)
  • func (p *Qlang) InjectMethods(pcls interface{}, code []byte) (err error)
  • func (p *Qlang) SafeCl(codeText []byte, fname string) (end int, err error)
  • func (p *Qlang) SafeEval(expr string) (err error)
  • func (p *Qlang) SafeExec(code []byte, fname string) (err error)
  • func (p *Qlang) SetLibs(libs string)

Variables

var Exports = map[string]interface{}{
	"new": New,
	"New": New,
}

Exports is the export table of this module.

var (
	// InsertSemis is interpreter options that means to insert semis smartly.
	InsertSemis = (*Options)(interpreter.InsertSemis)
)

Functions

func Debug

func Debug(fn func())

Debug sets dump code mode to "1" for debug.

func Import

func Import(mod string, table map[string]interface{})

Import imports a module written in Go.

func SetAutoCall

func SetAutoCall(t reflect.Type)

SetAutoCall is reserved for internal use.

func SetDumpCode

func SetDumpCode(dumpCode string)

SetDumpCode sets dump code mode:

"1" - dump code with rem instruction.
"2" - dump code without rem instruction.
else - don't dump code.

func SetFindEntry

func SetFindEntry(fn func(file string, libs []string) (string, error))

SetFindEntry sets the `FindEntry` function.

func SetOnPop

func SetOnPop(fn func(v interface{}))

SetOnPop sets OnPop callback.

func SetReadFile

func SetReadFile(fn func(file string) ([]byte, error))

SetReadFile sets the `ReadFile` function.

Types

type Options

type Options interpreter.Options

Options represent interpreter options.

type Qlang

type Qlang struct {
	*exec.Context
	// contains filtered or unexported fields
}

A Qlang represents the qlang compiler and executor.

func New

func New() *Qlang

New returns a new qlang instance.

func (*Qlang) Cl

func (p *Qlang) Cl(codeText []byte, fname string) (end int, err error)

Cl compiles a source code.

func (*Qlang) Eval

func (p *Qlang) Eval(expr string) (err error)

Eval compiles and executes a source code.

func (*Qlang) Exec

func (p *Qlang) Exec(codeText []byte, fname string) (err error)

Exec compiles and executes a source code.

func (*Qlang) InjectMethods

func (p *Qlang) InjectMethods(pcls interface{}, code []byte) (err error)

InjectMethods injects some methods into a class. `pcls` can be a `*exec.Class` object or a `string` typed class name.

func (*Qlang) SafeCl

func (p *Qlang) SafeCl(codeText []byte, fname string) (end int, err error)

SafeCl compiles a source code, without panic (will convert panic into an error).

func (*Qlang) SafeEval

func (p *Qlang) SafeEval(expr string) (err error)

SafeEval compiles and executes a source code, without panic (will convert panic into an error).

func (*Qlang) SafeExec

func (p *Qlang) SafeExec(code []byte, fname string) (err error)

SafeExec compiles and executes a source code, without panic (will convert panic into an error).

func (*Qlang) SetLibs

func (p *Qlang) SetLibs(libs string)

SetLibs sets lib paths for searching modules.