VS Code Extension for GsLang

环境

插件依赖gip，用于下载driver和管理pkg，第一次安装插件时会提示正在下载gip，下载完成后重载vscode。

安装

通过插件市场安装

• 在vscode插件市场搜索gs，即可直接安装。

通过VSIX安装

1. 从\\cnszvwin0007\技术中心\GsLang获取最新的VSIX安装包
2. 在vscode中按快捷键F1或Ctrl+Shift+P打开Command Palette
3. 搜索并运行命令Extensions:Install form VSIX，选择刚刚获取的安装包进行安装

快速开始

直接打开gs工程目录

1. Ctrl+O选择工程所在文件夹或在文件夹下以vscode打开
2. 工程是否有需要预加载的文件
   • 没有----直接开始使用插件
   • 有----配置driver启动参数（以下选择其中一种，假设启动参数为/m /preload.gsh,/macro.gsh）：
     • 左下角Settings搜索GsLang，找到starup_arguments项输入启动参数
     • 在工程目录的.vscode/settings.json中加入"gslang.starup_arguments": "/m /preload.gsh,/macro.gsh"
     • 使用命令GsLang.InputPreloadArgs配置启动参数
3. 调试参数配置：在launch.json中的execute_path配置启动脚本路径和command_line来指定运行参数。More...

以工作区的方式打开gs项目

1. 使用Open Workspace...命令或双击工作区文件.code-workspace打开工作区
   • 新建工作区：即新建以下结构的.code-workspace文件

     {
        "folders": [ // 工作区中的工作目录
          {
            "path": "server_gs"
          },
          {
            "path": "common-server\\common-lib"
          }
        ],
        "settings": { // 整体配置，作用到工作区中所有的工作目录
          "gslang.starup_arguments": "/m /preload.gsh,/macro.gsh"
        }
     }
     

2. 为工作目录单独配置参数
   • 当某个目录需要的启动参数需要与工作区的参数不同时进行单独配置（以下选择其中一种）
     • 左下角Settings搜索GsLang，在Folder中选择相应的文件夹，修改参数
     • 在该工作目录下的vscode/settings.json中添加配置
   • 其他配置同理，如root_path、driver_path等。
3. 调试参数配置：在launch.json中的execute_path配置启动脚本路径和command_line来指定运行参数。More...

使用说明

参数配置

• 正常情况下，安装插件后打开gs语言工程后即可正常使用插件相关功能了。当工程有特殊的需求时则需要对插件中默认的参数配置进行相应的调整。
• 以工作区打开多工作目录的情况下，可以为工作区统一配置通用的参数，也可以单独为某些工作目录配置特殊的参数（该方式配置的内容拥有更高的优先级）

启动参数

• 目前大多数gs工程项目中都会有预加载操作：即在编译/运行代码之前先由启动参数指定，定义一些期望在所有脚本编译器执行的东西（如mount目录），或加载底层(common-lib)中的宏并自定义上层需要的各种宏。
• 即工程中代码是依赖于这些预加载操作的，所以插件在编译项目工程的文件时也需要有相同的启动参数才能正确的解析出语法树以支持插件程序性语言的相关功能。
• 配置项：gslang.starup_arguments
  • 同样，可以在系统设置中搜索配置也可以在工作目录的.vscode/settings.josn中编辑。
  • 例如 "gslang.starup_arguments": "/m /preload.gsh,/macro.gsh"

调试参数

调试以工作区作为单位，每个需要进行调试的工作区都需要配置自身的调试参数，配置于每个工作区下的.vscode/launch.json文件中。你可以通过手动创建该文件，也可以通过模板自动生成：在运行和调试窗口下 -- 创建launch.json文件 -- 选择工作区 -- Gs-Debugger

详细参数说明

根目录

• 默认情况下，driver执行的根目录以及插件寻找模块依据的根目录均为工作目录（即${workspaceFolder}）。
• 当项目需要时，插件也允许自行配置路径作为根目录。
  • 需要注意的是若自定义了根目录则该工作目录中文件的预加载参数等也要以配置的为准。
• 配置项：gslang.root_path

功能介绍

语法高亮

• 语法高亮功能根据语法将文本解析成符号和作用域，然后根据这份作用域映射应用对应的颜色和样式。
• 想要解析文本，就需要一份体现GS语言语法规则的文件来负责区分文本中的关键字、字符串、注释、变量名、函数名等符号以及各自的作用域。
• 在GS语言插件中，这样一份用正则表达式描述的语法规则文件为gs.tmLanguage.json，其原型是JavaScript的TextMate语法描述文件。
• 通过保留相似语法并修改差异语法的正则表达式来使所有规则逐步契合GS语言的语法特性，最终完美地实现GS语言的语法高亮。

代码片段

• 配置文件gs.tmSnippets.json将代码片段打包到插件中，这样在使用到相应语法结构时可以快速生成代码片段配置的模板。
• 所以配置文件中一般创建的为插件语言常用的片段结构，如for循环、if语句、swicth/case语句等。

悬停提示

• 当鼠标光标停留在某个字符上时，悬浮信息会展示在光标下方，为用户提供符号或对象的相关信息，一般是关于符号的类型和描述。该功能的实现分为以下几步：
  1. 解析鼠标光标所在位置的符号，并判断其类型，如函数、变量等；
  2. 根据类型在语法树中检索该符号对应的函数、变量；
  3. 组织检索到的信息作为参数提供给相应的vscode接口。

定义跳转

• 与悬停提示类似，定义跳转同样是根据所选字符来检索相应的定义，但悬停是将检索到的内容组织后通过悬浮窗口显示出来，而定义跳转则是定位到定义的具体位置并进行跳转。
• 当根据选定的字符找到了多个可能的定义时，需要用户自行选择跳转列表中的某一个定义进行跳转；
• 而当根据当前文件以及其相关的模块找不到相关的定义时，插件则会放大搜索范围，从全局查找可能的定义。
• 函数跳转
  • 代码中字符串是函数的标志是后面紧接着'('(除特殊情况，如(: xxx :))，所以在进行定义跳转时首先要获取的除了光标所在字符外，还需要后伸展查看并判断当前所在是否是函数。
  • 若为函数，则需要向前查看该函数是否是被触发的函数(GS中的trigger通常有.,.?,?.,?.?,=>,=>?)，若是被触发的，则获取trigger前的字符串找到相应的模块或类型并找到这个函数，否则直接在本文件以及component和default_object模块中查询可以直接调用的函数。
• 变量跳转
  • 当判断出光标所在字符串不是函数时，则需要尝试判断其是不是变量或模块名。
    • 判断是否为变量比较简单，即遍历一遍当前位置作用域内的变量（包括枚举、常量等）来匹配。
  • 不足：当前收集到的变量作用域不够精确，如函数中闭包中定义的变量只能模糊地判断作用域为整个函数。
• 模块跳转
  • import/component/include代码后的模块的定义跳转操作直接跳转到相应文件。
  • 若是同时引入多个模块（如import xxx.*）则将所有模块列出由用户自行选择要跳转的文件。
• 宏命令跳转
  • 获取的宏定义信息没有位置信息且所在文件的信息也有问题，宏定义的跳转待优化。

代码补全

• 代码补全提示是根据已输入的符号，猜测用户想要输入的关键字、函数名、变量名、宏定义、枚举等内容。
• 在获取补全候补信息时，需要根据当前文件定义的内容以及import/component的模块来获取相关的函数、变量等信息。
• 实际上，代码的补全提示与定义跳转的实现类似，只是定义跳转是由特点的目标，而代码补全则是根据已有的信息（当前文件、当前函数、引入模块、触发字符与触发前缀以及已经输入的字符）来获取所有可能的选项，然后列出这些选项让用户来选择自己实际想输入的内容。

参数建议

• 参数建议的触发条件是函数名加上左圆括号，同样是根据已有的信息查找可能的函数，然后解析函数的参数列表并用vscode的接口呈现到悬浮窗口中。

诊断提示

• 当用vscode打开工作区或文件夹时，插件会调用driver对所有文件进行一次编译，若编译过程中产生了错误信息，则将其重定向输出到指定的文件中，当编译完成时插件通过解析错误日志记录每条错误信息并输出到output窗口中。
• 而当用户在编辑代码文件并保存时，插件在更新语法树的同时也会对错误信息进行更新。
• 根据错误信息中文件路径以及行号等内容，插件会定相应位置用红色波浪线进行标注。
• 当用户将光标悬停到波浪线上时，悬浮窗口将显示具体的错误信息，若可以快速修复则显示QuickFix选项供用户选择是否进行自动修复（目前支持auto import）。

显示符号定义

• 每次打开/切换编辑区文件时，都会收集当前聚焦的文件的符号定义，通过API接口使得编辑区的顶部显示当前光标所在位置的信息，如当前光标所在工作区的哪个文件夹，文件夹中的哪个文件以及文件中的哪个函数中。
• 待优化：对于符号定义功能，还没有收集所有变量及其位置。

格式化(待实现：可选功能)

• 当新建文件或对文件进行保存时，自动格式化当前文件，主要调整的内容包括文件的编码格式、行尾符等，此外，还要支持对整个项目所有文件的批量格式化。
• 根据gs编码风格的自动格式化，即类似TypeScript、C++等插件的Formatting功能，包括整个文件的和已选择代码部分的格式化。

运行脚本

• GsLang.RunScript运行当前脚本文件：
  • 在文件编辑界面中右键可选择该命令
  • driver使用配置的启动参数和根目录（未配置时为工作目录）
  • driver运行整个文件，即会加载其定义的函数和引入的模块定义的方法
  • driver运行的stdout和stderr会输出到outputChannal（即GsEditor）
  • driver运行完后退出（exited with code=0）
  • driver运行超时（目前设置为30s）时kill driver
• RunSelectedScript运行当前选择的脚本代码：
  • 在文件编辑界面中右键或选择右键可以选择执行该命令
  • 启动命令时插件创建一个名为gsshell的Terminal
  • 启动的shell的根目录设置为工作目录，但未加载工程配置的预加载命令
  • 若选择的代码不为空，则执行选择的代码
  • 若未选择代码或执行完选择的代码后，shell仍然存在，可以当成一个正常的shell使用
  • 不用时需要手动退出/删除Terminal，否则该shell一直存在直到vscode关闭或重新执行该命令时创建新的shell

常见问题