Skip to content

Latest commit

 

History

History
225 lines (177 loc) · 8.08 KB

File metadata and controls

225 lines (177 loc) · 8.08 KB

通用项目创建脚本文档

为了将来能够按照统一的标准创建项目,我们在此定义并且开发通用项目创建脚本(Project Creation Script)。通过此脚本可以允许程序以特定的方式创建新的项目。

此脚本是基于json开发的,所有的语法标准都会按照json语言。接下来的文档中将会讲述文件的大概结构并且程序会如何读取这些文件。

文件总览

此部分将会大概展示一个pcs文件的基本解构

{
  "version": "v1",
  "project_name": "项目名称",
  "project_description": "项目简介",
  "tags": [
    "标签的UUID",
    "标签的UUID"
  ],
  "store_location": "项目的存储位置",
  "properties": ["项目的属性"],
  "create_script": [
    "此部分将会保存项目创建时应用程序该如何操作"
  ]
}

除了 propertiescreate_script 以外,其他的都会作为一个项目的必填属性。因为这些在创建一个项目的时候是必要的。然而 propertiescreate_script 都是用户可以随便编写且定制的部分。你也可以直接编写此部分的内容来自定义用户想如何初始化项目。此部分的内容是独立的,因此你可以让此部分单独存在并且向程序生命在需要的时候导入需要的部分

Properties 属性

Properties属性包括项目一些特殊的属性,比如是否是只读项目,这个项目是否加密,等等。随着将来的开发,更多的属性将会添加到备选项目中。

现在已经包括的属性

{
  "properties": [
    {
      "name": "read_only"
    },
    {
      "name": "encrypted",
      "encrypted": "加密密码"
    }
  ]
}

如你所见,所有的属性都将会作为一个json对象存在properties列表中。每一个属性名称都必须存在name的字段中。若一个项目会有更多的信息,则其他的信息都将会存在以属性名称为键的字段中。

properties外置声名

脚本中所有可以导入的部分都会用到相同的语法,那就是import关键字。在可导入的部分直接这样写:

{
  "properties": [
    {"import": "导入外部文件的位置"}
  ],
  "create_script": [
    {"import": "导入外部文件的位置"}
  ]
}

在相应的位置填写导入声名,软件将会自动识别所在的位置并且应用到对应的位置。请注意,如果你已经填写了导入声名,就不要在此部分填写其他东西,因为会被覆盖掉。

create_script属性

此部分将会声名在创建项目时如何操作此项目,其中包含了一些操作关键词可供用户操作。

{
  "create_script": [
    {
      "method": "copy",
      "from": "文件位置"
    },
    {
      "method": "create",
      "type": "file或者是dir",
      "name": "带有文件后缀的文件名,或者是目录的名称"
    },
    {
      "method": "delete",
      "type": "file或者是dir",
      "name": "删除目标的名称,如果是文件需要携带文件后缀"
    }
  ]
}

如上所示,这三种方法是最基础的方法。我们接下来来讲一下这些指令的基础结构和效果以及一些其他你可能需要的基础知识。

指令块的基础结构

一个大括号包括的部分称之为一个指令块。指令块中包含了一个指令需要的所有信息。(我知道这样写很奇怪,但是为了方便计算机和人类都可以快速读懂指令到底在讲什么,所以我们仍然使用json作为基础语法)。 任何一个指令块的第一个条目必然是method属性。method属性会让程序知道这个代码块想要执行什么指令,根据method属性来决定程序收集哪些信息来完成执行操作。

接下来的所有部分都将会视情况而定,不同的指令有不同的信息需要提供。我们会在接下来的章节中讲述。

create_script 指令总览

1. Copy

{
  "method": "copy",
  "from": "<file_location>"
}

此指令会让程序复制指定位置的文件到项目的根目录下。你可以直接输入一个文件的绝对路径。若你想从公共项目资源复制文件,你可以使用{$project_public:'命名空间'}/前缀加上文件名来复制文件。前缀导入一般用于插件或者项目创建预设快速创建文件。

对于前缀的使用与公共资源和公共资源命名空间的使用,请参寻文档的其他部分。


2. Create

{
  "method": "create",
  "type": "<creation type>",
  "name": "<file name>"
}

此指令会让程序在项目目录为根目录的相对位置创建一个文件或者文件夹。创建文件的指令访问项目文件夹以外的位置是被绝对禁止的。

Type属性有两个可以使用的值,dir或者是file。dir会创建一个目录,而file会创建一个文件。name部分需要填写目录或者文件的名称。请注意文件名称需要带文件类型。

⚠安全警告!

您可以通过create指令来创建脚本文件,但是为了防止开发者通过此操作向脚本注入恶意代码,默认情况下所有的脚本在执行之前都会先通知用户并让用户确认。在安全模式下,所有的脚本执行和调用系统代码行是不被允许的。


3. Delete

{
  "method": "delete",
  "type": "<creation type>",
  "name": "<file or folder name>"
}

此指令会删除指定的文件或目录。type属性只接受两种值,一个是file,另外一个是dir。在name中您需要提供目标对象的名称。请注意,delete无法访问除了项目文件夹以外的任何位置。


4. Write

{
  "method": "write",
  "target": "<target file location relative to the project root dir>",
  "content": "<file content>"
}

此指令允许写入一个文件,target接受一个相对于项目根目录,content接收将要输入文件的内容。您可以使用{$var:'变量名'}/的形式来调用变量。


5. Read

{
  "method": "read",
  "target": "<target file>",
  "output": [
    
  ]
}

此指令允许读取一个文件并且将数据存储在某一特定位置,output属性是一个通用属性,内部接受使用代码块。比如说,你可以选择使用变量存储

{
  "method": "read",
  "target": "<target file>",
  "output": [
    {"var": "file_content", "value": "{$func_output.0}"}
  ]
}

或者可以直接调用写指令来写入文件

{
  "method": "read",
  "target": "./never_gonna_give_you_up_lyrics.txt",
  "output": [
    {
      "method": "write",
      "target": "./rick_roll.txt",
      "content": "{$func_output.0}"
    }
  ]
}

针对变量的调用和使用,以及内置函数返回值的使用,请参寻文档后部


特殊字段的使用

有一些全局的变量或者自定义变量会使用到特殊字段。特殊字段大概的格式为:{$字段名称}。如果一个特殊字段需要输入特定的名称,则特殊字段将会是这个样子的:{$字段名称:'输入值1'|'输入值2'} meth

变量定义与使用

此脚本语言允许用户自定义变量以进行更多的操作。变量的定义和使用的写法是一样的。 如果一个变量在使用前就被定义了,则会直接调用其中的值,否则就会定义一个新的变量。

这里的变量与其他编程语言的变量大同小异,现阶段主要接受三种类型:数字,字符串,和布尔。声明变量无需声名变量类型,并且在必要时系统会自动将变量类型转换。

变量在不同的层级会有相对的变量作用域,函数体内的循环将会作为局部变量存在,但是函数体内仍然可以寻找全局变量。若局部变量和全局变量的名称相同,则优先调用局部变量。

变量代码块定义和调用变量:

{
  "var": "变量名称",
  "value": "设定值(若不写此字段则系统将识别为读取变量)"
}

行内调用变量:

{$var:'变量名'|'设定值(若不写此字段则系统将识别为读取变量)'}

Creation Method 单独文件

Creation Method中的内容允许单独存在,使用import来导入文件。对于此单独的文件