VS Code Extension for GsLang

环境

1. 安装node
2. 安装yarn：npm install -g yarn
3. 设置默认私有仓库：npm config set registry http://gsgip.g-bits.com:4873/

安装

通过插件市场安装

• 在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...

使用说明

激活插件

有两种方法可以激活插件：

1. 使用vscode打开gs语言文件(后缀为gs或gsh)时自动激活插件。
2. 运行命令GsLang.Helper时插件激活。
3. 运行调试相关的命令时插件激活。

    "activationEvents": [
        "onLanguage:gs",
        "onCommand:GsLang.Helper",
        "onCommand:GsLang.LaunchRelease",
        "onCommand:GsLang.LaunchDebug",
        "onCommand:GsLang.AttachInput",
        "onCommand:GsLang.AttachSelect"
    ]

参数配置

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

Driver路径

• 默认情况下，插件编译文件使用的driver是插件自带并拷贝到用户目录下的版本（特殊实现了一些外部函数）。
• 若有特殊需求，可以配置参数gslang.driver_path来指定想要使用的driver的路径:
  • 在系统设置中搜索找到该项配置并填写driver路径或编辑工作目录下.vscode/settings.josn。
• 改进目标：安装插件时根据当前操作系统从远程下载相应环境编译的driver，而不是将固定版本的driver置于插件附带的文件中。

启动参数

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

调试参数

• 在launch.json中配置，一般是在自动生成的launch文件中修改execute_path和command_line来指定运行的driver和运行参数

• 通用方式的配置：

       {
           "type": "gsdebug",
           "name": "launch-release",
           "request": "launch",
           "with_debug": false,
           "debug_port": 20001,
           "root_path": "${workspaceFolder}",
           "execute_path": {
              "win32": "./bin/cmmshell.exe"
           },
           "command_line": "/r ./ /e main.gs",
           "program": "${command:LaunchRelease}"
       }
  

  • type：配置类型，GsLang的配置类型为gsdebug。
  • name：配置名称，显示在左侧菜单栏的调试列表中。
  • request：请求类型，launch或attach，用于识别启动和附加操作。
  • root_path：根目录，一般为工作目录，${workspaceFolder}表示当前项目的工作目录。
  • program：响应内置预设的操作。

• 启动方式的配置:

      {
          "type": "gsdebug",
          "name": "launch-release",
          "request": "launch",
          "with_debug": false,
          "debug_port": 20001,
          "root_path": "${workspaceFolder}",
          "execute_path": {
             "win32": "./bin/cmmshell.exe"
          },
          "command_line": "/r ./ /e main.gs",
          "program": "${command:LaunchRelease}"
      }
  

  • with_debug：launch的启动参数，表示带调试启动和不带调试启动的两种模式。
  • debug_port：提供给Gs的预设的调试端口。
  • execute_path：Gs执行程序的路径，支持完整路径和相对路径。
  • command_line：命令行运行参数。

• 附加方式的配置：

     {
         "type": "gsdebug",
         "name": "attach-input",
         "request": "attach",
         "debug_port": 20001,
         "root_path": "${workspaceFolder}",
         "program": "${command:AttachInput}"
     }
  

  • program：
    • ${command:AttachInput}表示执行输入指定端口号内置程序。
    • ${command:AttachSelect}表示执行通过选择列表选择端口内置程序。

Features

• 提供两种启动方式：带调试启动和不带调试启动。
  • 两种启动方式都会在运行参数后面加上--enable-debugger 端口号::是否等待调试，确保开启Gs的调试功能。
    • 端口号为指定的话，默认端口为20001。
    • 如果指定的端口号被占用，Gs会重新分配，直到获得一个唯一的监听端口。
  • 两种方式的区别:
    • 带调试启动：启动时会根据VsCode上已设置的断点进行暂停。
    • 不带调试启动：启动时脱离VsCode执行，可以通过attach方式进行附加到Gs进程中。
• 提供两种附加方式：输入指定端口号和通过选择列表选择端口
  • 输入指定端口号：
    • 在开启Gs调试功能后，Gs会分配一个用于调试的唯一端口，可通过该端口号attach到Gs进程中。
    • 查看Gs的调试的端口，可以在Gs中输入'get_env("debug_port")获得调试端口。
  • 通过列表选择端口：
    • 启动调试功能的Gs都会在个人文件夹下创建gslang_debug的目录，用于记录此次启动调试功能的相关信息（进程号，端口号等.）。
    • VsCode通过遍历**个人文件夹/gslang_debug/**中的文件，从而获取所有已启动的调试端口。
    • 用户可以通过选择启动的调试端口进行附加到Gs进程中。
• 调试堆栈和变量的查看：
  • 在VsCode处于调试状态时才可以进行查看操作。
  • 调用堆栈的查看：
    • 在左侧菜单栏的调用堆栈中显示协程列表，并且显示当前暂停的协程的调用堆栈。
    • 可以通过点击调用堆栈进行切换当前堆栈信息。
  • 变量的查看：
    • 在左侧菜单栏的变量显示当前执行协程的相关信息。
    • 支持鼠标悬浮在变量上方时，能进行变量查看。
    • 支持层级展示map和array的数据结构。

根目录

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

运行命令

• ~~GsLang.SuperCmd~~
  • 快捷键Ctrl+F12，用于输入名字后触发其他命令
• GsLang.Helper
  • 快捷键Ctrl+F1，快速输入/选择命令，目前用于新建模板工程，后续也可集成一些其他功能或命令到选择中
• GsLang.SelectStartFileBat
  • 右键选择文件作为启动参数文件，选择后插件会解析文件中一些预加载的代码作为启动参数
• GsLang.InputStartBatPath
  • 快捷键Ctrl+F3，输入启动参数文件的路径，与上一个命令作用一样，需要注意的是若输入的路径为相对路径时要清楚当前的根目录是工作目录还是另行配置过了
• GsLang.InputPreloadArgs
  • 快捷键Ctrl+F2，输入启动参数，直接配置工作区的启动参数
• GsLang.CompileProject
  • 快捷键Ctrl+F6，重新编译整个工程生成语法树数据
• GsLang.RunScript和GsLang.RunSelectedScript
  • 右键选择文件或代码片段运行脚本
• GsLang.ShowProjectErrors
  • 在output窗口显示当前项目的所有错误
• GsLang.ShowDocumentErrors
  • 在output窗口显示当前文件的错误

功能介绍

语法高亮

• 语法高亮功能根据语法将文本解析成符号和作用域，然后根据这份作用域映射应用对应的颜色和样式。
• 想要解析文本，就需要一份体现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

常见问题