From 0e682b7c0796bc085504891a0c8b5e3ac577cf60 Mon Sep 17 00:00:00 2001 From: ValKmjolnir Date: Tue, 13 Sep 2022 22:14:17 +0800 Subject: [PATCH] :memo: update docs --- README.md | 278 +++++++++++++++++++++++++---------------------- doc/README_zh.md | 245 ++++++++++++++++++++++------------------- doc/vs.md | 22 +++- 3 files changed, 299 insertions(+), 246 deletions(-) diff --git a/README.md b/README.md index f91e9ed..9b99eaa 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,5 @@ # __Nasal Scripting Language__ -```C++ - __ _ - /\ \ \__ _ ___ __ _| | - / \/ / _` / __|/ _` | | - / /\ / (_| \__ \ (_| | | - \_\ \/ \__,_|___/\__,_|_| -``` - ![GitHub code size](https://img.shields.io/github/languages/code-size/ValKmjolnir/Nasal-Interpreter?style=flat-square&logo=github) ![GitHub release(latest by date)](https://img.shields.io/github/v/release/ValKmjolnir/Nasal-Interpreter?style=flat-square&logo=github) ![in dev](https://img.shields.io/badge/dev-v10.1-blue?style=flat-square&logo=github) @@ -38,29 +30,27 @@ __[Nasal](http://wiki.flightgear.org/Nasal_scripting_language)__ is an ECMAscript-like language that used in [FlightGear](https://www.flightgear.org/). The designer is [Andy Ross](https://github.com/andyross). -This interpreter is totally rewritten by [ValKmjolnir](https://github.com/ValKmjolnir) using `C++`(`-std=c++11`) -without reusing the code in [Andy Ross's nasal interpreter](). +This interpreter is totally rewritten by [ValKmjolnir](https://github.com/ValKmjolnir) using `C++`(`-std=c++14`) +without reusing the code in [Andy Ross's nasal interpreter](https://github.com/andyross/nasal). But we really appreciate that Andy created this amazing programming language and his interpreter project. -Now this project uses __MIT license__ (2021/5/4). Edit it if you want, -use this project to learn or create more interesting things (But don't forget me XD). +This project uses __MIT license__ (2021/5/4). __Why writing this nasal interpreter?__ In 2019 summer holiday, members in [FGPRC](https://www.fgprc.org/) told me that it is hard to debug with nasal-console in Flightgear, especially when checking syntax errors. -So i tried to write a new interpreter to help them checking syntax error and even, runtime error. +So i wrote a new interpreter to help them checking syntax error and even, runtime error. I wrote the lexer, parser and -bytecode virtual machine(there was an ast-interpreter, -but deleted after v4.0) to help checking errors. +bytecode virtual machine to help checking errors. We found it much easier to check syntax and runtime -errors before copying nasal-codes in nasal-console in Flightgear to test. +errors. -Also, you could use this language to write some +You could also use this language to write some interesting programs and run them without the lib of Flightgear. You could add your own modules to make -this interpreter a useful tool in your own projects (such as a script in a game just as Flightgear does). +the interpreter a useful tool in your own projects. ## __How to Compile__ @@ -72,57 +62,39 @@ this interpreter a useful tool in your own projects (such as a script in a game ![clang++](https://img.shields.io/badge/LLVM-clang++-262D3A?style=flat-square&logo=LLVM) ![vs](https://img.shields.io/badge/Visual_Studio-MSVC-5C2D91?style=flat-square&logo=visualstudio) -Better choose the latest update of the interpreter. -Download the source and build it! It's quite easy to build this interpreter. +Better download the latest update source of the interpreter and build it! It's quite easy to build this interpreter. +__CAUTION__: If want to use the release zip/tar.gz file to build the interpreter, please read the [__Release Notes__](./doc/dev.md#release-notes) to make sure this release file has no fatal bugs. -__CAUTION__: If want to use the release zip/tar.gz file to build the interpreter, please read the [__Release Notes__](./doc/dev.md#release-notes) to make sure this release file has no fatal bugs. There are some tips to fix the release manually. +Use g++(`MinGW-w64`) or MSVC(`Visual Studio`) on `Windows` . -Use g++(`MinGW-w64`) or MSVC(`Visual Studio`) on __`Windows`__ platform. Download MinGW-w64 [__HERE__](https://www.mingw-w64.org/downloads/)(Visual Studio also has this), and use g++/clang++ on __`linux/macOS/Unix`__ platform (we suggest `clang`). +Use g++/clang++ on `Linux/macOS/Unix` platform (we suggest `clang`). -We could build the interpreter using `makefile`. - -`mingw32-make` is __`Windows(MinGW-w64)`__ platform's `make`: +On `Windows (MinGW-w64)`: > mingw32-make nasal.exe -> -> mingw32-make.exe nasal.exe -on __`linux/macOS/Unix`__: +You could create project in `Visual Studio` by this way: [__CLICK__](./doc/vs.md). + +On `Linux/macOS/Unix`: > make nasal You could choose which compiler you want to use: -> make nasal CXX=clang++ -> -> make nasal CXX=g++ -> > make nasal CXX=... If you think `-O3` isn't that safe and stable, you could choose: > make stable-release -> -> mingw32-make stable-release-mingw - -You could create project in `Visual Studio` by this way: [__CLICK__](./doc/vs.md). ## __How to Use__ First we should learn how to write and run a program using this language, click to see the [__tutorial__](#tutorial). -Use this get version of interpreter: +Use this command to get help: -> ./nasal - -Input this command to run scripts __directly__: - -> ./nasal filename - -Use these commands to get help(see more debug commands in help): - -> ./nasal -h | --help +> ./nasal -h If your system is __`Windows`__ and you want to output unicode,please use this command before running nasal interpreter: @@ -142,7 +114,7 @@ Reading this tutorial will not takes you over 15 minutes. __If you have learnt C/C++/Javascript before, this will take less time.__ You could totally use it after reading this simple tutorial: -
basic value type +
Basic value type __`vm_none`__ is error type. This type is used to interrupt the execution of virtual machine and will not be created by user program. @@ -221,7 +193,7 @@ This type is often created by native-function of nasal. If want to define your o
-
operators +
Operators Nasal has basic math operators `+` `-` `*` `/` and a special operator `~` that links two strings together. @@ -257,7 +229,7 @@ a~='string';
-
definition +
Definition ```javascript var a=1; @@ -269,7 +241,7 @@ var (a,b,c)=(0,1,2);
-
multi-assignment +
Multi-assignment The last one is often used to swap two variables. @@ -281,7 +253,7 @@ The last one is often used to swap two variables.
-
conditional expression +
Conditional expression In nasal there's a new key word `elsif`. It has the same functions as `else if`. @@ -300,7 +272,7 @@ if(1){
-
loop +
Loop While loop and for loop is simalar to C/C++. @@ -329,7 +301,7 @@ foreach(var i;elem)
-
subvec +
Subvec Nasal provides this special syntax to help user generate a new vector by getting values by one index or getting values by indexes in a range from an old vector. If there's only one index in the bracket, then we will get the value directly. @@ -344,7 +316,7 @@ a[-1,1,0:2,0:,:3,:,nil:8,3:nil,nil:nil];
-
special function call +
Special function call This is of great use but is not very efficient (because hashmap use string as the key to compare). @@ -355,7 +327,7 @@ f(x:0,y:nil,z:[]);
-
lambda +
Lambda Also functions have this kind of use: @@ -382,7 +354,7 @@ var fib=func(f){
-
closure +
Closure Closure means you could get the variable that is not in the local scope of a function that you called. Here is an example, result is `1`: @@ -412,7 +384,7 @@ var student=func(n,a){
-
trait +
Trait Also there's another way to OOP, that is `trait`. @@ -494,7 +466,7 @@ If you want to use this trick to make the program running more efficiently, you
-
native functions and module import +
Native functions and module import This part shows how we add native functions in this nasal interpreter. If you are interested in this part, this may help you. @@ -609,7 +581,7 @@ nas_ref builtin_keys(nas_ref* local,nasal_gc& gc)
-
modules(for lib developers) +
Modules(for lib developers) If there is only one way to add your own functions into nasal, that is really inconvenient. @@ -678,7 +650,6 @@ Windows(`.dll`): Then we write a test nasal file to run this fib function, using `os.platform()` we could write a program that runs on three different OS: ```javascript -import("lib.nas"); var dlhandle=dylib.dlopen("libfib."~(os.platform()=="windows"?"dll":"so")); var fib=dylib.dlsym(dlhandle,"fib"); for(var i=1;i<30;i+=1) @@ -733,14 +704,13 @@ If get this, Congratulations! ## __Difference Between Andy's and This Interpreter__ -### 1. must use `var` to define variables +
Must use `var` to define variables This interpreter uses more strict syntax to make sure it is easier for you to program and debug. In Andy's interpreter: ```javascript -import("lib.nas"); foreach(i;[0,1,2,3]) print(i) ``` @@ -755,25 +725,53 @@ So in this interpreter i use a more strict syntax to force users to use `var` to If you forget to add the keyword `var`, you will get this: ```javascript -[code] test.nas:2 undefined symbol "i". -foreach(i;[0,1,2,3]) -[code] test.nas:3 undefined symbol "i". - print(i) +code: undefined symbol "i" + --> test.nas:1:9 + | +1 | foreach(i;[0,1,2,3]) + | ^ undefined symbol "i" + +code: undefined symbol "i" + --> test.nas:2:11 + | +2 | print(i) + | ^ undefined symbol "i" ``` -### 2. default dynamic arguments not supported +
+ +
Default dynamic arguments not supported In this interpreter, function doesn't put dynamic args into vector `arg` by default. So if you use `arg` without definition, you'll get an error of `undefined symbol`. +```javascript +var f=func(){ + println(arg) +} +f(1,2,3); +``` + +Compilation result: + +```javascript +code: undefined symbol "arg" + --> test.nas:2:15 + | +2 | println(arg) + | ^ undefined symbol "arg" +``` + +
+ ## __Trace Back Info__ When interpreter crashes, it will print trace back information: -
1. native function [die] +
Native function `die` Function `die` is used to throw error and crash immediately. @@ -791,10 +789,10 @@ hello [vm] error: error occurred this line [vm] native function error. trace back: - 0x000000ac: 40 00 00 00 25 callb 0x25 <__die@0x41afc0> (lib.nas:131) - 0x000004f6: 3e 00 00 00 01 callfv 0x1 (a.nas:4) - 0x000004fa: 3e 00 00 00 00 callfv 0x0 (a.nas:6) -vm stack(0x7fffcd21bc68, limit 10, total 12): + 0x000000ac 40 00 00 00 25 callb 0x25 <__die@0x41afc0> (lib.nas:131) + 0x000004f6 3e 00 00 00 01 callfv 0x1 (a.nas:4) + 0x000004fa 3e 00 00 00 00 callfv 0x0 (a.nas:6) +vm stack (0x7fffcd21bc68 , limit 10, total 12): 0x0000005b | null | ... 0x00000057 | str | <0x138ff60> error occurred t... @@ -804,7 +802,7 @@ vm stack(0x7fffcd21bc68, limit 10, total 12):
-
2. stack overflow crash info +
Stack overflow crash info Here is an example of stack overflow: @@ -821,11 +819,11 @@ func(f){ ```javascript [vm] stack overflow trace back: - 0x000004fb: 3e 00 00 00 01 callfv 0x1 (a.nas:5) - 0x000004fb: 1349 same call(s) - 0x000004f3: 3e 00 00 00 01 callfv 0x1 (a.nas:2) - 0x000004ff: 3e 00 00 00 01 callfv 0x1 (a.nas:3) -vm stack(0x7fffd3781d58, limit 10, total 8108): + 0x000004fb 3e 00 00 00 01 callfv 0x1 (a.nas:5) + 0x000004fb 1349 same call(s) + 0x000004f3 3e 00 00 00 01 callfv 0x1 (a.nas:2) + 0x000004ff 3e 00 00 00 01 callfv 0x1 (a.nas:3) +vm stack (0x7fffd3781d58 , limit 10, total 8108): 0x00001ffb | func | <0x15f8d90> entry:0x4f9 0x00001ffa | func | <0x15f8d90> entry:0x4f9 0x00001ff9 | pc | 0x4fb @@ -835,7 +833,7 @@ vm stack(0x7fffd3781d58, limit 10, total 8108):
-
3. normal vm error crash info +
Normal vm error crash info Error will be thrown if there's a fatal error when executing: @@ -848,49 +846,49 @@ func(){ ```javascript [vm] callv: must call a vector/hash/string trace back: - 0x000004f4: 3b 00 00 00 00 callv 0x0 (a.nas:3) -vm stack(0x7fffff539c28, limit 10, total 1): + 0x000004f4 3b 00 00 00 00 callv 0x0 (a.nas:3) +vm stack (0x7fffff539c28 , limit 10, total 1): 0x00000050 | num | 0 ```
-
4. detailed crash info +
Detailed crash info Use command __`-d`__ or __`--detail`__ the trace back info will show more details: ```javascript hello [vm] error: error occurred this line -[vm] native function error. -trace back: - 0x000000ac: 40 00 00 00 25 callb 0x25 <__die@0x41afc0> (lib.nas:131) - 0x000004f6: 3e 00 00 00 01 callfv 0x1 (a.nas:4) - 0x000004fa: 3e 00 00 00 00 callfv 0x0 (a.nas:6) -vm stack(0x7ffff42f3d08, limit 10, total 12): - 0x0000005b | null | - 0x0000005a | pc | 0x4f6 - 0x00000059 | addr | 0x7ffff42f3d18 +[vm] error: native function error +trace back (main) + 0x000000b0 40 00 00 00 2b callb 0x2b <__die@0x41c380> (lib.nas:131) + 0x00000553 3e 00 00 00 01 callfv 0x1 (test.nas:4) + 0x00000557 3e 00 00 00 00 callfv 0x0 (test.nas:6) +vm stack (0x7fffe0ffed90 , limit 10, total 12) + 0x0000004a | null | + 0x00000049 | pc | 0x553 + 0x00000048 | addr | 0x7fffe0ffeda0 ... - 0x00000052 | nil | -registers(main): - [ pc ] | pc | 0xac - [ global ] | addr | 0x7ffff42f3808 - [ localr ] | addr | 0x7ffff42f3d68 + 0x00000041 | nil | +registers (main) + [ pc ] | pc | 0xb0 + [ global ] | addr | 0x7fffe0ffe9a0 + [ localr ] | addr | 0x7fffe0ffedf0 [ memr ] | addr | 0x0 - [ funcr ] | func | <0x18fbe50> entry:0xac + [ canary ] | addr | 0x7fffe1002990 + [ top ] | addr | 0x7fffe0ffee40 + [ funcr ] | func | <0x677cd0> entry:0xb0 [ upvalr ] | nil | - [ canary ] | addr | 0x7ffff43137f8 - [ top ] | addr | 0x7ffff42f3db8 -global(0x7ffff42f3808): - 0x00000000 | func | <0x18d62d0> entry:0x5 - 0x00000001 | func | <0x18d7e40> entry:0xc +global (0x7fffe0ffe9a0 ) + 0x00000000 | func | <0x65fb00> entry:0x5 + 0x00000001 | func | <0x65fb20> entry:0xd ... - 0x0000004e | func | <0x18e6710> entry:0x4c2 - 0x0000004f | hash | <0x191f8b0> {5 val} -local(0x7ffff42f3d68): + 0x0000003d | func | <0x66bf00> entry:0x51f + 0x0000003e | hash | <0x65ffa0> {5 val} +local (0x7fffe0ffedf0 ) 0x00000000 | nil | - 0x00000001 | str | <0x1932480> error occurred t... + 0x00000001 | str | <0x6cb630> error occurred t... ```
@@ -901,49 +899,71 @@ We added a debugger in `v8.0`. Use command `./nasal -dbg xxx.nas` to use the debugger, and the debugger will print this: +
Click to unfold + ```javascript [debug] nasal debug mode input 'h' to get help source code: ---> var fib=func(x) - { +--> var fib=func(x) + { if(x<2) return x; return fib(x-1)+fib(x-2); - } - for(var i=0;i<31;i+=1) + } + for(var i=0;i<31;i+=1) print(fib(i),'\n'); next bytecode: ---> 0x00000000: 01 00 00 00 50 intg 0x50 (test/fib.nas:0) - 0x00000001: 0b 00 00 00 05 newf 0x5 (./lib.nas:5) - 0x00000002: 02 00 00 00 02 intl 0x2 (./lib.nas:5) - 0x00000003: 0f 00 00 00 00 dyn 0x0 ("elems") (./lib.nas:5) - 0x00000004: 32 00 00 00 07 jmp 0x7 (./lib.nas:5) - 0x00000005: 40 00 00 00 00 callb 0x0 <__print@0x419400> (./lib.nas:6) - 0x00000006: 4a 00 00 00 00 ret 0x0 (./lib.nas:6) - 0x00000007: 03 00 00 00 00 loadg 0x0 (./lib.nas:5) -vm stack(0x7fffce09e6e8, limit 10, total 0) +--> 0x00000000 01 00 00 00 41 intg 0x41 (test/fib.nas:0) + 0x00000001 0b 00 00 00 05 newf 0x5 (lib.nas:6) + 0x00000002 02 00 00 00 02 intl 0x2 (lib.nas:6) + 0x00000003 0f 00 00 00 00 dyn 0x0 ("elems") (lib.nas:6) + 0x00000004 32 00 00 00 07 jmp 0x7 (lib.nas:6) + 0x00000005 40 00 00 00 00 callb 0x0 <__print@0x419c80> (lib.nas:7) + 0x00000006 4a 00 00 00 00 ret 0x0 (lib.nas:7) + 0x00000007 03 00 00 00 00 loadg 0x0 (lib.nas:6) +vm stack (0x7fffd0259138 , limit 10, total 0) >> ``` +
+ If want help, input `h` to get help. When running the debugger, you could see what is on stack. This will help you debugging or learning how the vm works: +
Click to unfold + ```javascript source code: - ... + var fib=func(x) + { +--> if(x<2) return x; + return fib(x-1)+fib(x-2); + } + for(var i=0;i<31;i+=1) + print(fib(i),'\n'); next bytecode: - ... -vm stack(0x7fffce09e6e8, limit 10, total 7) - 0x00000056 | pc | 0x533 - 0x00000055 | addr | 0x0 - 0x00000054 | nil | - 0x00000053 | num | 0 - 0x00000052 | nil | - 0x00000051 | nil | - 0x00000050 | func | <0x166e000> entry:0x5 + 0x00000548 0c 00 00 00 aa happ 0xaa ("running") (lib.nas:503) + 0x00000549 03 00 00 00 3e loadg 0x3e (lib.nas:498) + 0x0000054a 0b 00 00 05 4e newf 0x54e (test/fib.nas:1) + 0x0000054b 02 00 00 00 02 intl 0x2 (test/fib.nas:1) + 0x0000054c 0d 00 00 00 1b para 0x1b ("x") (test/fib.nas:1) + 0x0000054d 32 00 00 05 5d jmp 0x55d (test/fib.nas:1) +--> 0x0000054e 39 00 00 00 01 calll 0x1 (test/fib.nas:3) + 0x0000054f 2d 00 00 00 03 lessc 0x3 (2) (test/fib.nas:3) +vm stack (0x7fffd0259138 , limit 10, total 7) + 0x00000047 | pc | 0x566 + 0x00000046 | addr | 0x0 + 0x00000045 | nil | + 0x00000044 | num | 0 + 0x00000043 | nil | + 0x00000042 | nil | + 0x00000041 | func | <0x88d2f0> entry:0x5 +>> ``` + +
diff --git a/doc/README_zh.md b/doc/README_zh.md index 5ab89e1..64b1302 100644 --- a/doc/README_zh.md +++ b/doc/README_zh.md @@ -1,19 +1,11 @@ # __Nasal 脚本语言__ -```C++ - __ _ - /\ \ \__ _ ___ __ _| | - / \/ / _` / __|/ _` | | - / /\ / (_| \__ \ (_| | | - \_\ \/ \__,_|___/\__,_|_| -``` - ![GitHub code size](https://img.shields.io/github/languages/code-size/ValKmjolnir/Nasal-Interpreter?style=flat-square&logo=github) ![GitHub release(latest by date)](https://img.shields.io/github/v/release/ValKmjolnir/Nasal-Interpreter?style=flat-square&logo=github) ![in dev](https://img.shields.io/badge/dev-v10.1-blue?style=flat-square&logo=github) [![license](https://img.shields.io/badge/license-MIT-green?style=flat-square&logo=github)](../LICENSE) -> 这篇文档包含多种语言版本: [__中文__](../doc/README_zh.md) | [__English__](../README.md) +> 这篇文档包含多语言版本: [__中文__](../doc/README_zh.md) | [__English__](../README.md) ## __目录__ @@ -38,16 +30,16 @@ __[Nasal](http://wiki.flightgear.org/Nasal_scripting_language)__ 是一个与ECMAscript标准语法设计相似的编程语言，并且作为运行脚本被著名的开源飞行模拟器 [FlightGear](https://www.flightgear.org/) 所依赖。 该语言的设计者和初版解释器实现者为 [Andy Ross](https://github.com/andyross)。 -这个解释器项目则由 [ValKmjolnir](https://github.com/ValKmjolnir) 完全使用 `C++`(`-std=c++11`)重新实现，没有复用 [Andy Ross的nasal解释器]() 中的任何一行代码。尽管没有任何的参考代码，我们依然非常感谢Andy为我们带来了这样一个神奇且容易上手的编程语言。 +这个解释器项目则由 [ValKmjolnir](https://github.com/ValKmjolnir) 完全使用 `C++`(`-std=c++14`)重新实现，没有复用 [Andy Ross的nasal解释器](https://github.com/andyross/nasal) 中的任何一行代码。尽管没有任何的参考代码，我们依然非常感谢Andy为我们带来了这样一个神奇且容易上手的编程语言。 -现在这个项目已经使用 __MIT 协议__ 开源 (2021/5/4)。根据该协议的内容，你们可以根据自己的需求进行修改，使用它来学习或者创造更多有趣的东西(不过可别忘了，如果要开源必须要附带本项目拥有者的相关信息)。 +该项目已经使用 __MIT__ 协议开源 (2021/5/4)。 __我们为什么想要重新写一个nasal解释器?__ -这是个很偶然的想法。2019年暑假，[FGPRC](https://www.fgprc.org.cn/) 的成员告诉我，在Flightgear中提供的nasal控制台窗口中进行调试实在是太费劲了，有时候只是想检查语法错误，也得花费时间打开这个软件等待加载进去之后进行调试。所以我就想，也许可以写一个全新的解释器来帮助他们检查语法错误，甚至是检查运行时的错误。 +2019年暑假，[FGPRC](https://www.fgprc.org.cn/) 的成员告诉我，在Flightgear中提供的nasal控制台窗口中进行调试很不方便，仅仅是想检查语法错误，也得花时间打开软件等待加载进去后进行调试。所以我就写了一个全新的解释器来帮助他们检查语法错误，甚至是检查运行时的错误。 -我编写了nasal的词法分析器和语法分析器，以及一个全新的字节码虚拟机(曾经我们使用ast解释器来直接在抽象语法树中执行，然而在v4.0之后这个解释器已经淘汰)，并用这个运行时来进行nasal程序的调试。我们发现使用这个解释器来检测语法和运行时错误非常快捷，远比每次都需要复制nasal代码到Flightgear的nasal控制台中去查看要方便，且错误信息清晰直观。 +我编写了nasal的词法分析器和语法分析器，以及一个全新的字节码虚拟机，并用这个运行时来进行nasal程序的调试。我们发现使用这个解释器来检测语法和运行时错误提高了我们的工作效率。 -当然，你也可以使用这个语言来写一些与Flightgear运行环境无关的其他有趣的程序，并用这个解释器来执行，让这个语言脱离Flightgear的环境，去别的地方大展身手。你也可以编写你自己的模块，让nasal来调用，使得这个语言成为你的项目中一个非常有用的工具。 +你也可以使用这个语言来写一些与Flightgear运行环境无关的有趣的程序，并用这个解释器来执行。你也可以让解释器来调用你自己编写的模块，使它成为项目中一个非常有用的工具。 ## __编译__ @@ -60,55 +52,37 @@ __我们为什么想要重新写一个nasal解释器?__ ![vs](https://img.shields.io/badge/Visual_Studio-MSVC-5C2D91?style=flat-square&logo=visualstudio) 我们推荐你下载最新更新的代码包来直接编译，这个项目非常小巧因此你可以非常快速地将它编译出来。 +__注意__: 如果你想直接下载发行版提供的zip/tar.gz压缩包来构建这个解释器，在下载之前请阅读[__发行日志__](../doc/dev_zh.md#发行日志)以保证这个发行版的文件中不包含非常严重的bug。 -__注意__: 如果你想直接下载发行版提供的zip/tar.gz压缩包来构建这个解释器，在下载之前请阅读[__发行日志__](../doc/dev_zh.md#发行日志)以保证这个发行版的文件中不包含非常严重的bug(有的严重bug都是在发行之后才发现，非常搞心态)。在发行版日志中我们会告知如何在代码中手动修复这个严重的bug。 +`Windows` 用户通过 g++(`MinGW-w64`) 或者使用 MSVC(`Visual Studio`) 来进行编译。 -__`Windows`__ 用户通过g++(`MinGW-w64`)使用以下命令或者使用MSVC(`Visual Studio`)来进行编译. 没有编译环境的请在[__这里__](https://www.mingw-w64.org/downloads/)下载MinGW-w64。(VS同样也有MinGW-w64) -__`linux/macOS/Unix`__ 用户可以使用g++或者clang++替代下面命令中中括号的部分来进行编译(我们建议您使用`clang`)。 +`Linux/macOS/Unix` 用户可以使用 g++ 或者 clang++ 来进行编译 (建议您使用 `clang`)。 -使用makefile我们就可以编译这个解释器。 - -`mingw32-make`是 __`Windows(MinGW-w64)`__ 平台的`make`: +`Windows` 平台(`MinGW-w64`): > mingw32-make nasal.exe -> -> mingw32-make.exe nasal.exe -__`linux/macOS/Unix`__ 平台直接使用make即可: +你也可以在`Visual Studio`中用这种方式来创建项目：[__点击跳转__](../doc/vs.md)。 + +`Linux/macOS/Unix` 平台: > make nasal 你也可以通过如下的其中一行命令来指定你想要使用的编译器： -> make nasal CXX=clang++ -> -> make nasal CXX=g++ -> > make nasal CXX=... 如果你觉得`-O3`编译的版本不是那么安全和稳定，你也可以选择生成稳定的版本： > make stable-release -> -> mingw32-make stable-release-mingw - -你可以在`Visual Studio`中用这种方式来创建项目：[__点击跳转__](../doc/vs.md)。 ## __使用方法__ 首先我们要通过[__教程__](#教程)知道这个语言的语法以及如何使用这个解释器来运行nasal程序。 -使用这个命令查看解释器的版本: +下面这个命令可以用于查看使用方法: -> ./nasal - -输入下面的命令来 __直接__ 执行: - -> ./nasal filename - -下面两个命令可以用于查看帮助(调试器的使用方法可以进入调试模式之后根据提示来查询): - -> ./nasal -h | --help +> ./nasal -h 如果你的操作系统是 __`Windows`__ 并且你想输出unicode，请保证你的控制台程序的代码页支持utf-8，若不支持，使用下面这个命令启用代码页: @@ -638,7 +612,6 @@ Windows(`.dll`): 好了，那么我们可以写一个测试用的nasal代码来运行这个斐波那契函数了。下面例子中`os.platform()`是用来检测当前运行的系统环境的，这样我们可以对不同系统进行适配: ```javascript -import("lib.nas"); var dlhandle=dylib.dlopen("libfib."~(os.platform()=="windows"?"dll":"so")); var fib=dylib.dlsym(dlhandle,"fib"); for(var i=1;i<30;i+=1) @@ -693,14 +666,13 @@ dylib.dlclose(dlhandle); ## __与andy解释器的不同之处__ -### 1. 必须用`var`定义变量 +
必须用 var 定义变量 这个解释器使用了更加严格的语法检查来保证你可以更轻松地debug。这是非常有必要的严格，否则debug会非常痛苦。 在Andy的解释器中: ```javascript -import("lib.nas"); foreach(i;[0,1,2,3]) print(i) ``` @@ -710,21 +682,48 @@ foreach(i;[0,1,2,3]) 所以在这个解释器中，我直接使用严格的语法检查方法来强行要求用户必须要使用`var`来定义新的变量或者迭代器。如果你忘了加这个关键字，那么你就会得到这个: ```javascript -[code] test.nas:2 undefined symbol "i". -foreach(i;[0,1,2,3]) -[code] test.nas:3 undefined symbol "i". - print(i) -``` +code: undefined symbol "i" + --> test.nas:1:9 + | +1 | foreach(i;[0,1,2,3]) + | ^ undefined symbol "i" -### 2. 默认不定长参数 +code: undefined symbol "i" + --> test.nas:2:11 + | +2 | print(i) + | ^ undefined symbol "i" +``` +
+ +
默认不定长参数 这个解释器在运行时，函数不会将超出参数表的那部分不定长参数放到默认的`arg`中。所以你如果不定义`arg`就使用它，那你只会得到`undefined symbol`。 +```javascript +var f=func(){ + println(arg) +} +f(1,2,3); +``` + +编译结果: + +```javascript +code: undefined symbol "arg" + --> test.nas:2:15 + | +2 | println(arg) + | ^ undefined symbol "arg" +``` + +
+ ## __堆栈追踪信息__ 当解释器崩溃时,它会反馈错误产生过程的堆栈追踪信息: -
1. 内置函数die +
内置函数 die `die`函数用于直接抛出错误并终止执行。 @@ -742,10 +741,10 @@ hello [vm] error: error occurred this line [vm] native function error. trace back: - 0x000000ac: 40 00 00 00 25 callb 0x25 <__die@0x41afc0> (lib.nas:131) - 0x000004f6: 3e 00 00 00 01 callfv 0x1 (a.nas:4) - 0x000004fa: 3e 00 00 00 00 callfv 0x0 (a.nas:6) -vm stack(0x7fffcd21bc68, limit 10, total 12): + 0x000000ac 40 00 00 00 25 callb 0x25 <__die@0x41afc0> (lib.nas:131) + 0x000004f6 3e 00 00 00 01 callfv 0x1 (a.nas:4) + 0x000004fa 3e 00 00 00 00 callfv 0x0 (a.nas:6) +vm stack (0x7fffcd21bc68 , limit 10, total 12): 0x0000005b | null | ... 0x00000057 | str | <0x138ff60> error occurred t... @@ -755,7 +754,7 @@ vm stack(0x7fffcd21bc68, limit 10, total 12):
-
2. 栈溢出 +
栈溢出 这是一个会导致栈溢出的例子: @@ -772,11 +771,11 @@ func(f){ ```javascript [vm] stack overflow trace back: - 0x000004fb: 3e 00 00 00 01 callfv 0x1 (a.nas:5) - 0x000004fb: 1349 same call(s) - 0x000004f3: 3e 00 00 00 01 callfv 0x1 (a.nas:2) - 0x000004ff: 3e 00 00 00 01 callfv 0x1 (a.nas:3) -vm stack(0x7fffd3781d58, limit 10, total 8108): + 0x000004fb 3e 00 00 00 01 callfv 0x1 (a.nas:5) + 0x000004fb 1349 same call(s) + 0x000004f3 3e 00 00 00 01 callfv 0x1 (a.nas:2) + 0x000004ff 3e 00 00 00 01 callfv 0x1 (a.nas:3) +vm stack (0x7fffd3781d58 , limit 10, total 8108): 0x00001ffb | func | <0x15f8d90> entry:0x4f9 0x00001ffa | func | <0x15f8d90> entry:0x4f9 0x00001ff9 | pc | 0x4fb @@ -786,7 +785,7 @@ vm stack(0x7fffd3781d58, limit 10, total 8108):
-
3. 运行时错误 +
运行时错误 如果在执行的时候出现错误，程序会直接终止执行: @@ -799,49 +798,49 @@ func(){ ```javascript [vm] callv: must call a vector/hash/string trace back: - 0x000004f4: 3b 00 00 00 00 callv 0x0 (a.nas:3) -vm stack(0x7fffff539c28, limit 10, total 1): + 0x000004f4 3b 00 00 00 00 callv 0x0 (a.nas:3) +vm stack (0x7fffff539c28 , limit 10, total 1): 0x00000050 | num | 0 ```
-
4. 详细的崩溃信息 +
详细的崩溃信息 使用命令 __`-d`__ 或 __`--detail`__ 后，trace back信息会包含更多的细节内容: ```javascript hello [vm] error: error occurred this line -[vm] native function error. -trace back: - 0x000000ac: 40 00 00 00 25 callb 0x25 <__die@0x41afc0> (lib.nas:131) - 0x000004f6: 3e 00 00 00 01 callfv 0x1 (a.nas:4) - 0x000004fa: 3e 00 00 00 00 callfv 0x0 (a.nas:6) -vm stack(0x7ffff42f3d08, limit 10, total 12): - 0x0000005b | null | - 0x0000005a | pc | 0x4f6 - 0x00000059 | addr | 0x7ffff42f3d18 +[vm] error: native function error +trace back (main) + 0x000000b0 40 00 00 00 2b callb 0x2b <__die@0x41c380> (lib.nas:131) + 0x00000553 3e 00 00 00 01 callfv 0x1 (test.nas:4) + 0x00000557 3e 00 00 00 00 callfv 0x0 (test.nas:6) +vm stack (0x7fffe0ffed90 , limit 10, total 12) + 0x0000004a | null | + 0x00000049 | pc | 0x553 + 0x00000048 | addr | 0x7fffe0ffeda0 ... - 0x00000052 | nil | -registers(main): - [ pc ] | pc | 0xac - [ global ] | addr | 0x7ffff42f3808 - [ localr ] | addr | 0x7ffff42f3d68 + 0x00000041 | nil | +registers (main) + [ pc ] | pc | 0xb0 + [ global ] | addr | 0x7fffe0ffe9a0 + [ localr ] | addr | 0x7fffe0ffedf0 [ memr ] | addr | 0x0 - [ funcr ] | func | <0x18fbe50> entry:0xac + [ canary ] | addr | 0x7fffe1002990 + [ top ] | addr | 0x7fffe0ffee40 + [ funcr ] | func | <0x677cd0> entry:0xb0 [ upvalr ] | nil | - [ canary ] | addr | 0x7ffff43137f8 - [ top ] | addr | 0x7ffff42f3db8 -global(0x7ffff42f3808): - 0x00000000 | func | <0x18d62d0> entry:0x5 - 0x00000001 | func | <0x18d7e40> entry:0xc +global (0x7fffe0ffe9a0 ) + 0x00000000 | func | <0x65fb00> entry:0x5 + 0x00000001 | func | <0x65fb20> entry:0xd ... - 0x0000004e | func | <0x18e6710> entry:0x4c2 - 0x0000004f | hash | <0x191f8b0> {5 val} -local(0x7ffff42f3d68): + 0x0000003d | func | <0x66bf00> entry:0x51f + 0x0000003e | hash | <0x65ffa0> {5 val} +local (0x7fffe0ffedf0 ) 0x00000000 | nil | - 0x00000001 | str | <0x1932480> error occurred t... + 0x00000001 | str | <0x6cb630> error occurred t... ```
@@ -851,49 +850,71 @@ local(0x7ffff42f3d68): 在`v8.0`版本中我们添加了调试器。 使用这个命令`./nasal -dbg xxx.nas`来启用调试器，接下来调试器会打开文件并输出以下内容: +
展开 + ```javascript [debug] nasal debug mode input 'h' to get help source code: ---> var fib=func(x) - { +--> var fib=func(x) + { if(x<2) return x; return fib(x-1)+fib(x-2); - } - for(var i=0;i<31;i+=1) + } + for(var i=0;i<31;i+=1) print(fib(i),'\n'); next bytecode: ---> 0x00000000: 01 00 00 00 50 intg 0x50 (test/fib.nas:0) - 0x00000001: 0b 00 00 00 05 newf 0x5 (./lib.nas:5) - 0x00000002: 02 00 00 00 02 intl 0x2 (./lib.nas:5) - 0x00000003: 0f 00 00 00 00 dyn 0x0 ("elems") (./lib.nas:5) - 0x00000004: 32 00 00 00 07 jmp 0x7 (./lib.nas:5) - 0x00000005: 40 00 00 00 00 callb 0x0 <__print@0x419400> (./lib.nas:6) - 0x00000006: 4a 00 00 00 00 ret 0x0 (./lib.nas:6) - 0x00000007: 03 00 00 00 00 loadg 0x0 (./lib.nas:5) -vm stack(0x7fffce09e6e8, limit 10, total 0) +--> 0x00000000 01 00 00 00 41 intg 0x41 (test/fib.nas:0) + 0x00000001 0b 00 00 00 05 newf 0x5 (lib.nas:6) + 0x00000002 02 00 00 00 02 intl 0x2 (lib.nas:6) + 0x00000003 0f 00 00 00 00 dyn 0x0 ("elems") (lib.nas:6) + 0x00000004 32 00 00 00 07 jmp 0x7 (lib.nas:6) + 0x00000005 40 00 00 00 00 callb 0x0 <__print@0x419c80> (lib.nas:7) + 0x00000006 4a 00 00 00 00 ret 0x0 (lib.nas:7) + 0x00000007 03 00 00 00 00 loadg 0x0 (lib.nas:6) +vm stack (0x7fffd0259138 , limit 10, total 0) >> ``` +
+ 如果需要查看命令的使用方法，可以输入`h`获取帮助信息。 当运行调试器的时候，你可以看到现在的操作数栈上到底有些什么数据。 这些信息可以帮助你调试，同时也可以帮助你理解这个虚拟机是如何工作的: +
展开 + ```javascript source code: - ... + var fib=func(x) + { +--> if(x<2) return x; + return fib(x-1)+fib(x-2); + } + for(var i=0;i<31;i+=1) + print(fib(i),'\n'); next bytecode: - ... -vm stack(0x7fffce09e6e8, limit 10, total 7) - 0x00000056 | pc | 0x533 - 0x00000055 | addr | 0x0 - 0x00000054 | nil | - 0x00000053 | num | 0 - 0x00000052 | nil | - 0x00000051 | nil | - 0x00000050 | func | <0x166e000> entry:0x5 + 0x00000548 0c 00 00 00 aa happ 0xaa ("running") (lib.nas:503) + 0x00000549 03 00 00 00 3e loadg 0x3e (lib.nas:498) + 0x0000054a 0b 00 00 05 4e newf 0x54e (test/fib.nas:1) + 0x0000054b 02 00 00 00 02 intl 0x2 (test/fib.nas:1) + 0x0000054c 0d 00 00 00 1b para 0x1b ("x") (test/fib.nas:1) + 0x0000054d 32 00 00 05 5d jmp 0x55d (test/fib.nas:1) +--> 0x0000054e 39 00 00 00 01 calll 0x1 (test/fib.nas:3) + 0x0000054f 2d 00 00 00 03 lessc 0x3 (2) (test/fib.nas:3) +vm stack (0x7fffd0259138 , limit 10, total 7) + 0x00000047 | pc | 0x566 + 0x00000046 | addr | 0x0 + 0x00000045 | nil | + 0x00000044 | num | 0 + 0x00000043 | nil | + 0x00000042 | nil | + 0x00000041 | func | <0x88d2f0> entry:0x5 +>> ``` + +
diff --git a/doc/vs.md b/doc/vs.md index f1ebbfd..2647c08 100644 --- a/doc/vs.md +++ b/doc/vs.md @@ -1,9 +1,21 @@ -# How to Create VS project | 如何创建VS工程 +# Create VS project | 创建 VS 工程 -1. Get code from this repo using `git`. | 用`git`从这个仓库获取代码。 +## How to Create VS project -2. In Visual Studio, click `File`->`New`->`Project From Existing Code...`. | 在VS的界面，点击文件(F)->新建(N)->从现有代码创建项目(E)。 +1. Get code from this repo using `git`. -3. Select `Visual C++`->`Next`->choose `project file location`->write the `project name` at ease->`Finish`. | 选择创建`Visual C++`项目->下一步->项目文件位置选择你下载的代码存放的文件夹->填项目名称，随便写->完成。 +2. In Visual Studio, click `File`->`New`->`Project From Existing Code...`. -4. Click `Source Files` in `Search Solution Explorer` at left, right click `main.cpp`, compile. | 点开左侧解决方案资源管理器中的`Source Files`，右键点击`main.cpp`，编译。 +3. Select `Visual C++`->`Next`->choose `project file location`->write the `project name` at ease->`Finish`. + +4. Click `Source Files` in `Search Solution Explorer` at left, right click `main.cpp`, compile. + +## 如何创建VS工程 + +1. 用`git`从这个仓库获取代码。 + +2. 在VS的界面，点击文件(F)->新建(N)->从现有代码创建项目(E)。 + +3. 选择创建`Visual C++`项目->下一步->项目文件位置选择你下载的代码存放的文件夹->填项目名称，随便写->完成。 + +4. 点开左侧解决方案资源管理器中的`Source Files`，右键点击`main.cpp`，编译。