Gox语言的中文简介可以从这篇文章开始看起，或者这里看更多的开发指南。

gox

Notice: from version 0.986a, Goxlang removed some script-engine support for smaller size. Only Qlang-engine is kept. And from version 0.998a, Sciter is recommended for cross-platform GUI programming in Gox. Although it requires a dynamic library file, but it's worthy. From 1.29a, Fyne is used as default OpenGL based GUI library instead of Giu. From 1.56a, LCL library support is removed. From 1.60a, Go Modules is supported and GOPATH is deprecated.

Gox (or Goxlang) is a free, open-source script language or a interpreter written by Golang. It's based on Qlang, with some improvement. The syntax of Gox language is very similar to Golang.

Golang is not required to be installed. Gox is only in one executable file, green and fast.

And thanks to Sciter and Go-Sciter, which enables Gox to provide a modern GUI programming ability, and it's cross-platform, native, no dependencies and convenient, only an additional library will needed. Even more, Gox has an code editor embedded, so the external text editor may not be required for small piece of code. Note: this GUI library file is packed within the zip file in Windows release, for Linux/Mac, please see the instructions in Sciter website.

Gox supports password-protect your source code file, it's also a major difference from most script/interpretive language.

1. Installation

Download the latest Gox executable file from the official website(recommended) or Github or Gitee (due to the speed issue, official website and Gitee are recommended). Then put it into a directory in the system path. If you download the zip file, extract it first.

A command-line only version of gox (named goxc, no GUI features) is also available. This version will be more fast, and of course smaller in file size.

Since the more features added makes the Gox executable became very large, the Tiny Gox Version is now available to download(not updated frequently). Some features are removed from Gox tiny version, such as OpenGL GUI, drawing, NoSQL, some database drivers(Oracle, MS-SQL), etc.

Goxg version is used to run GUI only programs, it will not open a CMD console.

2.usage

Check the version.

gox -version

Show help.

gox -h

Run a script file.

gox test.gox

Start the interpreter in REPL mode.

gox

the REPL runs like this,

use "quit()" or "exit()" function to exit.

Select script file to run in REPL mode

run()

Just call run() function in REPL, a file selection dialog will popup.

Run example script from Gitee directly

gox -example basic.gox

Gox will download the example script directly from Github and run it.

View/Save example script from Gitee

gox -example -view basic

the basic.gox (the suffix could be omitted) script will be printed to standard output. Use redirect to save the script, i.e.

gox -example -view basic > d:\scripts\a.gox

Run online script directly

Gox will try to download the script first and then run it.

Run with a magic number(acquired from somewhere)

gox 18

Gox will try to download the script associated with the magic number and then run it.

MNS(Magic-Number-Script) can also be executed in the shell mode, i.e.

gox >magic(18)

Run script from clipboard

gox -clip

Gox will try to get the text content from system clipboard and run it as a script

Encrypt source code file

gox -encrypt=mycode basic.gox

An encrypted file with an additional "e" of the file name(i.e. basic.goxe) will be created in the same directory of the original source code file. "mycode" is the password to encrypt the file, and of course remember this code to decrypt it back.

Decrypt/restore encrypted source code file

gox -decrypt=mycode basic.goxe

An decrypted file with an additional "d" of the file name(i.e. basic.goxed) will be created in the same directory of the original encrypted source code file. Manually rename the file to "basic.gox" if necessary.

Running an encrypted script directly

gox -decrun=mycode basic.goxe

or

gox -decrun=mycode -example basic.goxe

Init GUI programming environment

gox -initgui

Download Sciter and LCL dll files in the same folder with Gox application path, now only in Windows platform.

Open a simple editor to edit Gox code

gox -edit

Open a simple editor to edit specific Gox code file

gox -edit d:\tmp\basic.gox

the screenshot of Gox editor is as below,

Although Gox provides a simple code editor, the editors with more powerful functions are recommended, such as Visual Studio Code. Currently, you can set the .gox files the same syntax highlight scheme as Golang files.

Batch run

First create a file(better named with .gxb suffix), content as below for example:

Each line in Gox batch file could be considered as a common Gox command line but the first paramter(Gox executable path) is omitted.

There are 3 ways to inform Gox to know it's a batch file to run:

 // gxb
 basic.gox
 d:\scripts\next.gox -inputvalue=1 -verbose
 18

3. User/developer guide

File encoding

All the script file is better in UTF-8 encoding, and its line-endings are better to use "\n" or "\r\n".

Stop/Terminate the script

Using exit(), os.Exit(1) or return in the script is valid. In interactive mode, quit() is valid, too.

command-line parameters and swithes

The global value "argsG" could be used for retrieve command-line arguments, and the first element(the Gox executable) is removed. If you need the whole command-line, use os.Args instead.

All the command-line switches/flags used by Gox itself are not recommended to be used in the scripts.

An example for command-line handling is as below(source code),

the output for this script should be something like,

Import packages

In Gox with Qlang engine, most of the standard Golang packages are supported and will be imported by default, just use them directly.

Along with most of the core Golang libraries, the "tk" package(here) is often used. The "tk" package provides many useful functions. See example scripts for more. And refer to the docs here.

Refer to the documents of these Golang packages for the detailed usage.

4. More Topics and Sample Scripts

Basic Gox script:

Basic script with GUI

A simple calculator with GUI(OPENGL is required).

The screen shot while running the script is like,

Basic script with GUI by LCL library

The script below acts almost the same as the script above, but written with LCL library support, and OPENGL is not required, so it's more compatible in the server-side environment.

The screen shot while running the script is like,

5. More Examples

Browse the example scripts here

6. Language

Difference between Gox and Golang

  • Gox is a dynamic-type language, so one of the major difference is no data-type declaration necessary in Gox.

It's very similar for function parameters and return values.

7. Library Reference

First, since Gox is based on Qlang and written by Golang, most of the core libraries of Golang will be available. So try to use the modules from Golang(but Golang installation is not required), and refer to the Golang documents(here, here or here). In addition, you can browse Qlang's, Govcl's and Giu's documents.

Most of the standard Golang packages are available include: bytes, encoding/json, errors, flag, fmt, image, image/color, image/draw, image/jpg, image/png, io, io.ioutil, log, math, math/big, math/rand, net, net/http, net/http/cookiejar, net/url, os, os/exec, os/signal, path, path/filepath, regexp, runtime, sort, strconv, strings, sync, time.

Library tk (github.com/topxeq/tk) is the most frequently used package in Gox, the documents are here or here.

Other libraries embedded in Gox include:

  • gonum.org/v1/plot(scientific drawing and charts, use it as gonumorg_v1_plot), and with gonumorg_v1_plot_plotter, gonumorg_v1_plot_plotutil, gonumorg_v1_plot_vg
  • github.com/domodwyer/mailyak(send mail via SMTP)
  • github.com/360EntSecGroup-Skylar/excelize(Excel file processing)
  • github.com/fogleman/gg(basic drawing)
  • github.com/dgraph-io/badger(NoSQL DB)
  • github.com/topxeq/govcl/vcl(derived from ying32's Govcl, GUI programming with LCL library)
  • github.com/AllenDang/giu(OpenGL GUI)
  • github.com/sciter-sdk/go-sciter(GUI programming with Sciter, HTML+CSS+TiScript+Golang)
  • github.com/topxeq/blink(control a chronium WebView, Windows only)
  • github.com/topxeq/sqltk(general SQL operations, enable access to Oracle, MySQL, MSSQLServer, SQLite databases)
  • github.com/topxeq/imagetk(various image-processing funtions)
  • github.com/beevik/etree(XML processing)
  • github.com/topxeq/xmlx(another XML processing package)
  • github.com/stretchr/objx(another JSON library)
  • github.com/kbinani/screenshot(cross-platform, multi-display screenshot)
  • github.com/topxeq/doc2vec/doc2vec(document to vector engine and training functions)
  • github.com/aliyun/alibaba-cloud-sdk-go/services/dysmsapi(send Aliyun SMS)
  • github.com/topxeq/afero(a memory file system)
  • github.com/topxeq/socks(a library for socks5 server/client programming)
  • github.com/topxeq/regexpx(add more functions to the standard regexp package)

Browse their Github pages for usage and documents, and of course the examples in the example directory.

To use an embedded package, see the examples below:

directly use

or

Attention: To refer a 3rd-party package, '.com' is always omitted for the domain name such as github.com, and the same is '.org' for gonum.org. And the slash('/') is replaced by underscore('_'), other special characters will be removed. For some packages used frequently(such as github.com/topxeq/tk), we will give it a convenient short-name(tk), but not all. You can define a short name for the packages that will be used.

define a short name

However, Gox provides some convenient global variables and functions decribed as below.

Variables

argsG

get global variable

The global value "argsG" could be used for retrieve command-line arguments, and the first element(the Gox executable) is usually removed. If you need the whole command-line, use os.Args instead.

scriptPathG

holds the full script path(include the file name), for network scenes, will be ""(empty string)

versionG

holds the current version of Gox

Functions

Note: some functions may exist or not in different script engine, and may have some slight differences.

pass

A function doing nothing. Usually used at the end of a script to ensure return nothing(so that will print nothing by the VM).

defined

check if a variable is defined

eval

evaluate an expression and return the result

type/typeof/typeOf/kindOf

return the string representation of the type for a variable or expression

remove

remove one or several items from an array

print/pr

the same as fmt.Print

println/pln

the same as fmt.Println

printf/prf

the same as fmt.Printf

printfln/pl

the same as fmt.Printf but add a new-line character at the end

sprintf

the same as fmt.Sprintf

fprintln/fprintf

the same as fmt.Fprintln/fmt.Fprintf

plv

the same as pl("%#v", v)

plvx

the same as tk.Plvx, i.e. fmt.Printf("[TYPE] %T [VALUE] %v [ITYPE] %#v\n", argsA, argsA, argsA)

pv

output the name, type, value of a variable, attention: the parameter passed to this function should be a string, and only the global varibles are allowed.

plvsr

the same as pl("%#v", v), but for various arguments

plerr

a convenient way to print an error value

plExit

the same as tk.PlAndExit, printfln then exit

exit

the same as os.Exit(1), used to terminate\exit the whole script running

setValue

assign a value by a pointer, used in Qlang engine.

getValue

get a value referenced by a pointer, used in Qlang engine.

setVar

set global variable

getVar

get global variable

bitXor

bitwise XOR operation, since in Qlang engine, ^ is used for get address/pointer of a variable(like & in other engine), so the origin bitwise XOR operator in Golang is used and we will use bitXor function instead.

isNil

check if a variable equals to nil(especially for non error type nil,such as *etree.Tree(nil))

strToInt

the same as tk.StrToIntWithDefaultValue

intToStr/floatToStr/toStr/toInt/toFloat

convert the values to string accordingly

toLower/toUpper

convert the lower/upper case

checkError

a convenient way to print an error value if not nil, and terminate the whole program running

deferFunc is the function which will be called before terminating the application, if none, pass nil for it, i.e. checkError(errT, nil)

checkErrorString

the same as checkError, but check a TXERROR string

checkErrf

the same as tk.CheckErrf, check an error, if not nil, terminate the program and printf something

checkErrStrf

the same as tk.CheckErrStrf, check a TXERROR string, if it's a TXERROR string, terminate the program and printf something

fatalf

printf then terminate the program

isErrStr

check if is TXERROR string (which starts with TXERROR:)

errStr

generate a TXERROR string (which starts with TXERROR:)

errStrf

generate a TXERROR string with format like printf, the same as tk.ErrStrF

getErrStr

remove the prefix(TXERROR:) of a TXERROR string, return the result

errf

the same as tk.Errf, generate an error

getInput(deprecated)

get user input from command-line

getInputf

the same as getInput, but use printf to print a prompt string

panic

raise a panic manually

keys

get the keys of a map

range

range an array, actually a keyword, not a function

deepClone

deep copy a struct variable and generate a new one

usage:

deepCopy

deep copy a struct variable to another one

getClipText

get clipboard text

setClipText

set clipboard text

trim

trim a string

run

execute a script file(in a new created VM)

run(argsA...)

runCode

execute a script string(in a new created VM, argsG will hold the arguments)

runCode(codeA string, argsA ...string)

runScript

runScript(scriptA, modeA, argsA ...)

run script in a new VM

any other modeA will run it as a system command.

magic

execute a script with a magic number(in a new created VM, argsG will hold the arguments)

magic(numberA, argsA...)

systemCmd

run a system command

newSSHClient

create a SSH client to run shell commands, upload/download file from a remote server. Thanks to melbahja and visit here to find more docs.

short examples:

find more in this example script here

getParameter

the same as tk.GetParameterByIndexWithDefaultValue

getSwitch

the same as tk.GetSwitchWithDefaultValue, get a command-line switch such as "-path=d:\tmp"

getIntSwitch

the same as tk.GetSwitchWithDefaultIntValue

switchExists/ifSwitchExists

the same as tk.IfSwitchExistsWhole, to determine if a command-line switch exists, such as "-verbose"

xmlEncode/htmlEncode/htmlDecode/base64Encode/base64Decode/md5Encode/jsonEncode/jsonDecode

misc encode/decode functions

newFunc

convert a pointer of type *execq.Function to *(func())

edit

the same as gui.EditFile, or the command-line switch "-edit", used to start an embedded code editor for Gox files.

gui.GetConfirm

show a confirm dialog, return true or false

gui.LoadFont

for loading font for GUI display, example:

see the example script here.

gui.SelectFile

xxxxxxx

gui.SelectSaveFile

xxxxxxx

gui.SelectDirectory

xxxxxxx

gui.EditFile

the same as edit function, or command-line switch "-edit"

Development

  • Feel free to modify the source code to make a custom version of Gox. You can remove some packages not necessary for you, or add some Golang or third-party packages into it.

  • The command here is used for developers to add imported libraries to Gox.

The usage is as below:

or just use a Gox script if you have the Golang environment and "go get" the Gox repository already:

and add them to the qlang/lib directory(look at the files inside for reference):

go install -ldflags="-H windowsgui"

  • Add the following flags while building will generate a more small-sized version without symbol and other debug information embedded in the executable.

go install -ldflags="-s -w"

  • You can embed custom Gox script inside the Gox/Goxc main executable, following this steps:

    • change the content in the embed.go, assign your script to the variable codeTextG.
    • build the Gox/Goxc using tag "embed", i.e. "go install -tags embed".
    • then you can run the executable and the script embedded will be run. Or you can distributed it as a single file(also a more secure one).
    • use command-line argument "-noembed" to prevent the embedded script from running automatically.