火山语言语法手册

一.相关概念和约定:

1.面向对象编程

火山语言基于面向对象的编程理念构造,支持类的封装、继承、多态,但是在此基础上进行了一些精简,以便能更好地学习和使用.

2.火山语言将用户分为初级和高级用户两种.在本文档中,对于只需要高级用户掌握的部分,会以""标志进行标记.绝大多数情况下,只需要掌握初级部分即可,高级部分仅用作用户需要自行扩展火山应用到具体目标平台的适应性时使用.

 

二.相关术语:

1.名称:

火山语言中的名称分为以下这些:

1.单名称:

单名称必须以英文字母/汉字字符开头,后面跟随英文字母/汉字字符/数字/'_'字符.如未特殊标注,本文档中所提出的所有"名称"均为单名称.

2.全名称:

以句点字符组合在一起的单名称成为全名称,如"火山.程序.安卓". 单名称被包含在全名称内(被认为是使用0个句点字符组合的全名称)

3.标识符名称:

必须由两个或多个单词文本组成,首单词必须以英文字母开头,后续单词可以以英文字母/数字/'_'字符开头,单词之间使用句点字符分隔,单词中间的字符只能为英文字母/数字/'_'字符,最后一个单词固定为此标识符的当前版本号数值.
两个标识符,如果其名称部分相同且第一个标识符的版本号大于等于第二个标识符的版本号,则说明第一个标识符能够匹配第二个标识符.
如标识符"cplus.win32.console.1",说明其名称为"cplus.win32.console",版本号为1.

注意: 火山中的名称对英文字母的大小写敏感,譬如"abc","ABC"所指定的不是同一名称.

2.立即数:

立即数有以下几类:

1.数值立即数:

1.十进制整数或小数,小数支持使用科学计数法.

2.十六进制整数: "0x"后跟数字0-9或字母A-B(大小写无关).

3.字符整数值: 使用单引号括住的字符,如'A'.

如果欲强行指定数值的数据类型,可以使用"强制类型转换"操作符,譬如"(长整数)1",提供了一个数据类型为长整数的数值立即数.

如果某整数的数值超出了整数的最大有效范围,将自动被设定为长整数数据类型.

2.逻辑型立即数: 为真/假.

3.字符串立即数:

为用双引号括住的一段文本,文本内支持使用以下转义符:

转义符 解释
\b 退格符
\f 换页符
\r 回车符
\n 换行符
\t 水平制表符
\' 单引号
\" 双引号
\\ 反斜杠
\x 后跟1-3个十六进制字符
\ooo 后跟1-3个八进制字符

4.字面字符串立即数:

在某些场合可以使用字面字符串,符合以下要求的文本被认为是字面字符串:
  1.不为空白字符串(空白字符串必须用""格式来表达);
  2.不为逻辑值真/假的常量文本(被判别为逻辑值);
  3.不以花括号字符开头(被判别为数组数据);
  4.不以双引号字符开头(被判别为非字面字符串);
  5.不以单引号字符开头(被判别为字符立即数);
  6.不以数字或 '+' / '-' 后紧随数字开头(被判别为数值).

字面字符串等同于字符串,只是在字面字符串中,不需要使用双引号将文本括住,不需要使用转义符来表达特定字符.

5.数组立即数(只能在提供常量/变量初始值时使用):

为使用花括号括住的立即数的组合,如: { 1, 2 },多维数组可以嵌套,如: { { 1, 2 }, { 3, 4 } }

注意: 多维数组的各维成员数目必须相等

 

三.火山程序结构:

一个火山程序的构成结构如下:

1.包定义

1.注释行

2.嵌入行

3.类定义

1.注释行

2.嵌入行

3.类常量定义

4.类成员变量定义

5.类方法定义

1.局部常量定义

2.局部变量定义

3.程序语句

下面是一个火山程序的基本样图(红色文字为注释):


1.包定义:

一个包内可以包含多个"注释行"/"嵌入行"/"类定义".

包名为全名称,如果被省略,则默认为"火山.用户.默认".

多个程序文件可以具有相同的包名,此时其中的内容被认为处于同一个包中.

2.注释行

包/类定义层如果直接输入文本,则自动成为注释行.

3.嵌入行

注释或者语句行如果以'@'字符开头,则称为嵌入行,该嵌入行在编译时将被直接发送到目的平台编译器,由用户自身保证该行的正确性.

嵌入行中可以使用以下格式文本引用外部火山名称:

格式 解释 样例
@全名称 引用所指定的全名称 @局部变量1, @对象1.方法1
@<全名称> 引用所指定的全名称 @<对象变量1>.test, @<对象变量1.成员1>.test
@c<类名称> 引用所指定的类名称 @c<类1>, @c<包1.类1>.静态变量1
@p<包名称> 引用所指定的包名称 @p<火山.用户.程序>
@n<约定名称> 引用所指定的全局/项目插件约定名称 @n<onInitAndroidActivity>
@s<特定名称> 引用所指定的特定名称,具体列表如下:
  1. "current_class": 嵌入行当前所处类名;
  2. "current_package": 嵌入行当前所处包名;
  3. "base_class": 嵌入行当前所处类的基础类名;
  4. "startup_class": 程序启动类名.
@s<current_class>
@s<current_package>
@s<base_class>
@s<startup_class>
@@ 用作在嵌入行文本中代表单个'@'字符 @@Override

4.类定义

火山类可以单根继承一个基础类,引用类名时可以直接使用类名称,或者使用"包名.类名"进行全名引用.

名称为"启动类"的类被用作定义启动用户程序的类

基本属性表:

名称 解释
基础类 指定本类的基础类名称,可以是单名称/全名称,也可以是空文本(表示无基础类).
公开 指定本类是否对外公开.公开类可以在所处包外部被访问,而非公开类则不可以.

5.类/局部常量定义

常量用作定义一个不允许在程序中进行修改的恒定值

基本属性表:

名称 解释
类型 提供常量的数据类型,只能是基本数据类型或常量类.
公开 指定本常量是否公开.公开常量可以在所处类外部被访问,而非公开常量只能在本类中访问.
本属性仅对类常量有效
初始值 提供常量的初始值立即数,必须对应常量的数据类型.可以为文本数据类型常量提供字面字符串.

6.类/局部成员变量定义

变量的内容允许在程序中动态修改.

如果未提供初始值,数值型变量的初始值为0,逻辑型变量的初始值为假,文本型变量的初始值为空文本,参考变量的初始值为空对象.

非静态的类成员变量,如果其数据类型为类且其中定义有事件,将被自动挂接到当前类实例对象.

基本属性表:

名称 解释
类型 提供变量的数据类型
静态 指定是否为静态变量.静态变量在所处类载入后即保持始终存在.
由于静态变量初始化时不存在所处类实例,静态成员变量不支持自动挂接其事件到其所处类,在需要时必须通过"接收事件"命令手动挂接.
类的静态成员变量需要通过"类名.变量名"的方式来引用.
参考 指定是否为参考变量
参考变量的内容为指向另外一个非参考变量的引用,本身并不包含实际数据.
公开 指定本变量是否公开.公开变量可以在所处类外部被访问,而非公开变量只能在本类中访问.
本属性仅对类成员变量有效
初始值 提供变量的初始值立即数,必须对应变量的数据类型.可以为文本数据类型变量提供字面字符串.

7.类方法定义

定义类的方法

名称为"类初始化"的方法为类的初始化方法(在类对象被创建时自动调用),该方法不携带任何参数并且不返回值.

名称为"类清理"的方法为类的清理方法(在类对象被销毁时自动调用),该方法不携带任何参数并且不返回值. 注意:在某些目标语言平台(如Java)上,类清理方法不会被支持.

基本属性表:

名称 解释
返回值类型 提供方法执行完毕后所返回数据的数据类型
静态 指定是否为静态方法
类的静态方法需要通过"类名.方法名"的方式来引用.
类别 指定方法的具体类别,可以为以下几种之一:

1.通常: 表明本方法为通常方法

2.属性写入: 表明本方法为属性写入方法.此种方法在所处类中定义了一个同名的属性,该属性可以在本类对象实例的"属性"列中被赋予初始值.此种方法必须满足以下格式要求:

1.无返回值;
2.不能为静态方法;
3.只能定义一个参数,该参数的数据类型必须为基本数据类型或者常量类,并且不能为数组,该数据类型即为本属性的数据类型.

3.定义事件: 定义本类对象将会发送事件的名称及格式,此种方法必须满足以下格式要求:

1.方法体必须为空;
2.返回值数据类型必须为整数;
3.不能为静态方法.

4.接收事件: 定义本类对象将会接收本类中成员变量对象所发送的事件,此种方法且必须满足以下要求:

1.返回值数据类型必须为整数;
2.不能为静态方法;
3.方法名称格式必须为: 事件对象类名 + "_" + 欲接收事件名;
4.方法的第一个参数的数据类型必须为欲接收其事件的事件对象类名;
5.方法其余参数的数目及数据类型必须与欲接收事件的定义方法一致.

公开 指定本方法是否公开.公开方法可以在所处类外部被访问,而非公开方法只能在本类中访问.
参数表 定义本方法的所有参数

8.程序语句

提供具体的方法语句代码

 

四.火山语言关键字表:

1.基本数据类型关键字:

名称 输入字1 解释
字节 sbyte 字节(有符号)基本数据类型,有效值范围从-128到127,占用1个字节空间.
短整数 short 短整数基本数据类型,有效值范围从-32768到32767,占用2个字节空间.
字符 wchar 宽字符基本数据类型,有效值范围从0到65535,占用2个字节空间.
整数 int 整数基本数据类型,有效值范围从-2147483648到2147483647,占用4个字节空间.
长整数 long 长整数基本数据类型,有效值范围从-9223372036854774808到9223372036854774807,占用8个字节空间.
小数 double 双精度小数基本数据类型,有效值范围从1.797693e+308到4.9000000e-324,占用8个字节空间.
逻辑型 bool 逻辑型基本数据类型,有效值为真/假.
文本型 string 文本型基本数据类型,用作记录一段字符串文本.

2.名称关键字:

名称 输入字1 解释
对象名称关键字:
本对象 this 用作在类成员方法中代表所处类的对象本身
父对象 super 用作在类成员方法中代表所处类的父对象,注意本关键字只能在句点操作符的第一个参数位置处使用.
立即数名称关键字:
true 用作代表逻辑值真
false 用作代表逻辑值假
空对象 null 用作代表空对象

3.操作符关键字:

名称 特性 优先级 输入字1 首/左侧参数 右侧参数 解释
.   1   欲访问对象名称 [E] 欲访问对象成员名称 句点分隔操作符,用作分隔对象与其成员名称.
[] [A] 1   欲访问数组数据 [E] [整数] 欲访问数组成员索引值 数组成员访问操作符,用作访问所指定索引位置处的数组成员.
- [A][B] 2   [数值] 欲取反的数值   算术取反操作符,用作返回将指定数值进行符号翻转后的结果值.
强制类型转换 [A][B] 2   欲转换到数据类型名称 欲转换数据类型的数据 类型强转操作符,用作将数据转换到所指定的数据类型.格式为:"(欲强转数据类型)欲转换类型的数据".
允许以下数据类型之间进行强制转换:
  1. "空对象"可以转换到任何类数据类型或文本型;
  2. 数值数据类型之间可以强行转换;
  3. 常量类可以转换到其所对应的基本数据类型;
  4. 类数据类型只能强行转换到其基础类或者继承类.
* [A] 3   [数值] 被乘数 [E] [数值] 乘数 算术相乘操作符,用作计算两个数值的相乘结果.
/ [A] 3   [数值] 被除数 [E] [数值] 除数 算术相除操作符,用作计算两个数值的相除结果.
% [A] 3   算术模除操作符,用作计算两个整数的相除后的余数.
+ [A] 4   [数值/文本] 被加数 [E] [数值/文本] 加数 相加操作符,用作计算两个数值/文本的相加结果.
- [A] 4   [数值] 被减数 [E] [数值] 减数 算术相减操作符,用作计算两个数值的相减结果.
<= [A] 5   [数值] 被比较数值 [数值] 比较数值 小于等于逻辑比较操作符,当左侧参数小于等于右侧参数时返回真.
>= [A] 5   大于等于逻辑比较操作符,当左侧参数大于等于右侧参数时返回真.
< [A] 5   小于逻辑比较操作符,当左侧参数小于右侧参数时返回真.
> [A] 5   大于逻辑比较操作符,当左侧参数大于等于右侧参数时返回真.
属于 [A] 5 instanceof [对象] 被检查对象 用作检查的类名 返回左侧对象是否为右侧类或者其继承类的实例对象
== [A] 6   [数值/逻辑型/文本/数组/对象] 被比较值 [数值/逻辑型/文本/数组/对象]  比较值 等于/不等于逻辑比较操作符,当左侧参数等于/不等于右侧参数时返回真.
注意:
对于数组或文本对象,唯一能够与其进行比较的是"空对象".
!= [A] 6  
&& [A] 7 [逻辑型] 逻辑值一 [E] [逻辑型] 逻辑值二 并且逻辑操作符,当左侧参数和右侧参数均为逻辑值真时返回真.
|| [A] 7 或者逻辑操作符,当左侧参数和右侧参数其中任意一个为逻辑值真时返回真.
= [B] 8   赋值到的变量 [E] 另一变量或所赋予的值

用作提供赋值用数据,也可以是另一个变量,用作支持连续赋值.

赋值操作符,将右侧参数的值赋予给左侧参数所指定的变量.

注释:

1.优先级值越小表明优先级越高;

2."特性"列中的"[A]"表示该操作符只能位于语句参数中; "[B]"表示为右结合;

3."右侧参数"列中如果标注"[E]",表明该参数可以被扩展.

4.命令关键字:

名称 特性 输入字1 参数名称 参数解释 返回值 解释
循环首类关键字:
判断循环 [D] while [逻辑型] 判断值 当此参数值为真时进入循环体,为假时将跳过循环体.   本命令根据提供的逻辑参数的值,来决定是否进入循环体.如果提供的逻辑参数值为真,程序顺序执行下一条语句进入循环体,否则跳转到本命令循环体的下一条语句处.
循环 [D][P] for [I] [整数] 变量起始值 定义循环变量的起始数值.如果被省略,默认值为0.   本命令将利用变量对循环体内的命令进行循环执行.第一次执行此命令时将使用"变量起始值"参数初始化"循环变量"参数所指定的变量.每次(包括第一次)执行到此命令处都将判断循环变量内的值是否已经超过"变量目标值"参数所指定的值,如已超过,则跳转到循环体的下一条语句处,否则进入循环体.
[I] [整数] 变量目标值 定义循环变量的目标数值,在循环首部如果发现循环变量值已超出此目标值时(递增值小于0时小于目标值,递增值大于0时大于目标值)将跳出循环.如果被省略,默认值为0.
[I][V] [整数] 循环变量 本整数型变量将用作控制循环执行次数,在循环尾部将自动递增或递减该变量内的数值(由变量递增值参数决定).循环体中的用户程序可以直接取用此变量中的值.如果被省略,将自动使用内部临时变量.
[I][M] [整数] 变量递增值 每次执行到循环尾部时都将把此值加入到循环变量中去,此值可为正数或负数,如为正数则递增,为负数则递减.如果被忽略,则默认值为1. 注意: 必须为本参数提供非0整数立即值,以便编译器建立循环结束条件.
流程控制类关键字:
如果 [D] if [逻辑型] 判断条件 本条件值的结果决定下一步程序执行位置   本命令根据所提供逻辑参数的值,来决定是否改变程序的执行位置.如果提供的逻辑参数值为真,程序继续顺序向下执行进入本命令的子语句体,然后跳过本命令后续所有的"另如"命令,为假则将跳过本命令的子语句体.
另如 [D][P] elseif [逻辑型] 判断条件 本条件值的结果决定下一步程序执行位置. 注意: 本参数可忽略以不提供,但是此时不能再后续跟随其它的"另如"语句.   本命令只能放在"如果"或其它"另如"命令的后面,根据所提供逻辑参数的值,来决定是否改变程序的执行位置.如果提供的逻辑参数值为真,程序继续顺序向下执行进入本命令的子语句体,然后跳过本命令后续所有的"另如"命令,为假则将跳过本命令的子语句体.
到循环尾 [P] continue       本命令转移当前程序执行位置到当前所处循环体的尾部
跳出循环 [P] break       本命令转移当前程序执行位置到当前所处循环体尾部的下一条语句处
返回 [P] return [I] 返回值 当所处方法定义有非空返回值数据类型时,必须提供返回到调用方的具体值,否则必须省略掉本参数,即两者必须对应.   本命令转移当前程序执行位置到调用本语句所处方法的下一条语句处,并可根据需要返回一个值到调用语句处.
运算类关键字:
取反     [逻辑型] 待取反逻辑值 提供将其反转的逻辑值 逻辑值 将所指定逻辑值进行反转,返回反转后的结果.
位取反     待取反整数值 提供将其所有位反转的整数值 整数值 将所指定整数值的每一位进行反转,返回反转后的结果.
位与     整数参数一 提供用作位操作的整数参数值一 整数值 将参数1的每一位与参数2的对应位进行与操作,返回运算后的结果.
整数参数二 提供用作位操作的整数参数值二
位或     同"位与" 整数值 将参数1的每一位与参数2的对应位进行或操作,返回运算后的结果.
位异或     整数值 将参数1的每一位与参数2的对应位进行异或操作,返回运算后的结果.
位左移     待位移整数值 提供被位移的整数值 整数值 将参数1的每一位向左移动参数2所指定的数目,返回运算后的结果.
位移数目 提供进行位移的位数
位右移     同"位左移" 整数值 将参数1的每一位向右移动参数2所指定的数目,返回运算后的结果.
编译时处理关键字:
编译出错   cerror       仅在编译程序时起作用,用作告知编译器发现了编译错误并停止编译.
调试类关键字:
调试检查   assert [逻辑型] 检查值 在调试版中,当此参数值为假时,程序将中断执行并报错.   本命令仅在编译程序的调试版本时被执行,在编译发布版时所处整条语句均将被忽略不被编译.在调试版中,当所提供的参数值为假时,程序将在此处中断执行并报错.
[I] [文本型] 检查失败信息 指定当检查失败时(检查值参数为假)所输出的信息
为调试版         逻辑型 返回当前所编译程序是否为调试版本
其它:
接收事件     [对象] 欲挂接其事件的对象 提供欲将其所定义事件挂接到当前类对应事件接收方法的对象   将指定对象所支持的事件挂接到当前类对象中的对应事件接收方法上. 本命令用作动态挂接对象事件.
取类输出名     类名 提供所欲返回其完整输出名称的类   返回所指定类对应的全输出名称(包括包名)字符串文本

注释:

1."特性"列中的"[D]"表示该命令需要携带一个子语句体,"[P]"表示当该命令的参数表为空时将被省略掉不显示;

2."参数表"列中的"[I]"表示该参数可以被省略不提供;"[V]"表示必须为该参数提供一个变量;"[M]"表示必须为该参数提供一个立即数.

 

五.扩展属性:

1.程序成员的所有属性由基本属性和扩展属性两部分组成,扩展属性可以应用在除开以下类型的所有定义型程序成员上:

1."参考"基本属性值为真的变量;

2.方法参数;

3.数据类型为数组的变量.

2.扩展属性有以下几种:

1.类中定义的"属性变量"扩展属性值为真的成员变量;

2.类中定义的所有属性写方法;

3.火山系统定义的全局扩展属性(属性名以'@'开头);

4.项目插件定义的项目扩展属性(属性名以'@'开头).

3.属性值可以引用程序中定义的常量,也可以为文本数据类型属性提供字面字符串值,但需要避免两者之间的冲突,系统如果发现属性值是有效名称文本,则优先认为其是一个被引用的程序常量名称.

4.火山系统定义的全局扩展属性表:

名称 数据类型 应用场合 解释
@属性变量 逻辑型 非静态类成员变量 本属性可以应用于非静态的类成员变量(数据类型只能是基本数据类型或常量类数据类型),用作指定该成员变量是否为其所处类的属性型成员.
@值细节类型 整数 类或者类的属性型成员(属性型成员变量或属性写方法) 当应用于类时,指定该类数据类型值的细节类型; 当应用于类的属性型成员时,指定该属性值的细节类型. 可以为以下文本值之一:

  1. "颜色": 为RGB十六进制颜色数值;
  2. "文件名": 为文件名(可以通过"@附加文本"属性提供其过滤器文本);
  3. "字体": 为字体信息,格式为: "字体名, 字体尺寸, 是否为粗体, 是否为斜体", 其中"是否"字段,用1代表真,0代表假;
  4. "定宽字体": 与"字体"类型不同的是仅限定宽字体.

@列表选择项 文本型 类的属性型成员(属性型成员变量或属性写方法) 本属性提供一系列备选列表文本,各个备选文本之间使用换行符分隔,用作在输入类的初始值/类属性成员的属性值时直接选择输入.
本属性的有效条件如下: 1. 所对应成员必须未指定细节类型; 2. 所对应成员如果为类的属性型成员,仅当该成员的数据类型是整数/文本型或对应类型的常量类时有效.
当成员的数据类型为整数时,属性值在编译时将被自动转换为以0开始的整数索引值.
@附加文本 文本型 类的属性型成员(属性型成员变量或属性写方法) 本属性用作提供附加文本信息:

  1. 当所对应成员细节类型为"文件名"时,用作提供具体文件名过滤器文本: 该文本必须以'|'分隔和结束,类似以下格式: "JPG文件(*.jpg;*.jpeg)|*.jpg;*.jpeg|GIF动画(*.gif)|*.gif|",尾部会自动加上能匹配所有文件的过滤器.

@禁止静态 逻辑型 本属性只能应用于类,用作指定是否允许在程序中定义该类及其所有继承类的静态或静态参考变量.
@常量类 整数 本属性只能应用于类,用作指定该类是否为常量类及其所对应的基本数据类型.
可以为以下文本值之一,用作指定其所对应的基本数据类型:

  1.字节;
  2.短整数;
  3.字符;
  4.整数;
  5.长整数;
  6.小数;
  7.逻辑型;
  8.文本型;
  9.文本到ID(常量初始值内容是文本类型,但数据类型为整数型,由编译器进行特定处理)

常量类用作建立对应某基本数据类型数据的特定类,类的内容必须为空.如果存在类的继承,常量类的基础类只能是常量类,非常量类的基础类只能是非常量类.

@别名类 文本型 本属性只能应用于类定义成员上,用作直接封装所指定的目标语言本地类,在程序中使用别名类等于直接使用所对应的本地类.
别名类具有以下使用限制:
  1. 别名类如存在基础类,必须也是别名类,且用户必须自行保证该基础别名类所封装的本地类为本别名类所封装本地类的基础类,非别名类的基础类 不能是别名类;
  2. 别名类的内容必须为空;
  3. 不能为别名类指定输出名;
  4. 如果目标语言支持包/命名空间,所封装的本地类名必须为全名称;
  5. 所封装的本地类必须提供有默认无参数构造方法.

别名类可以为其它非别名类的基础类

@输出名 文本型 任何定义型程序成员 本属性可以应用于任何定义型成员,用作指定其编译后的输出名称(不使用本属性进行指定则编译器会自动为它生成一个输出名称),编译器会保证其它所自动生成的输出名称不会与此指定名发生冲突.所提供输出名称如果以'@'字符开头,表明为引用全局/项目约定名称.
@虚拟方法 逻辑型 类方法 本属性只能应用于方法定义成员上,用作指定该方法为虚拟方法(类的多态),虚拟方法会被自动公开.
类中任何与其基础类虚拟方法同名的方法其返回数据类型和参数定义格式必须完全一致.
如果基础类中的某方法被设置为虚拟方法,则继承类中的同名方法将被自动设置为虚拟方法.
@外部基础类 文本型 类的基础类属性 本属性用作指定一个非火山类名作为当前类的基础类名称(此时当前类应该没有定义基础类或者所有直接/间接基础类的内容均为空白),编译器将不进行任何检查. 注意:

  1.不能将本属性值指向一个火山类名,因为系统不会对其进行引用检查,因而该火山类可能会因为没有被引用而在代码优化时被删除;
  2.如果定义了非空外部基础类,则编译器编译本类时将不会再自动生成本类的无参数空白构造方法.

@禁止创建对象 逻辑型 本属性只能应用于类定义成员上,用作指定是否允许定义类型为该类的变量或变量数组("参考"属性为真的变量/变量数组/参数不在限制之内).
@禁止流程检查 逻辑型 方法 本属性只能应用于方法定义成员上,用作关闭编译器在该方法上的流程检查机制,主要包括以下内容:

  1. 当方法定义有返回值时是否所有退出流程分支均返回了值

@依赖类 文本型 本属性只能应用于类定义成员上,用作指定一个或多个类作为本类的依赖类(多个依赖类名之间使用逗号或换行符分隔),一旦本类被用户程序使用,则其所有在此处指定的依赖类均认为被使用.一般情况下,类之间的依赖关系会被编译器自动判别,此处用作当本类中未曾使用到某类时强制指定其为本类的依赖类.

 

六.安卓项目插件相关:

1.安卓项目插件定义的项目扩展属性表:

名称 数据类型 应用场合 解释
@安卓.导入 文本型 可以应用于包或类定义成员.当用作包时,对当前包所处源文件中定义的所有类均起作用. 本属性用作在所编译生成的目的源程序首加入相关的java命名空间import导入语句,多个导入名称之间使用逗号或换行符分隔.
@安卓.权限需求 文本型 本属性用作声明所处类正常执行所需求的安卓权限,多个权限之间使用逗号或者换行符分隔.如果权限名称未给定前缀,默认为"android.permission".
@安卓.系统需求 整数 本属性用作声明所处类正常执行所需求的最小安卓系统API级别
@安卓.外部库 文本型 本属性用作提供所处类正常执行所需求的外部jar或so库文件名,多个文件名之间使用逗号或者换行符分隔.
强烈推荐所使用的jar外部库使用jdk 1.6版本编译(编译时source和target参数均给"1.6"),如果使用太高版本jdk编译,有可能会导致安卓APK打包工具无法识别从而导致打包失败.
系统对外部jar和so库文件按照不同的算法进行处理:

1.如果是jar外部库,则直接将该库文件加入到项目外部库存放目录;

2.如果是so外部库,系统将按照以下算法(也是系统所使用的标准安卓资源搜寻算法)寻找并加入该so库的其它CPU架构版本:

1.如果该文件携带修饰符,则将在同一目录中搜寻加入具有其余种类修饰符的同名so文件. 修饰符文本必须放在文件后缀名的前面,与文件名之间使用减号分隔,如"test-armeabi-v7a.so".所允许的修饰符为"arm64-v8a"/"armeabi"/"armeabi-v7a"/"mips"/"mips64"/"x86"/"x86_64"之一,用作提供其所支持的CPU架构);

2.如果该文件位于以以上修饰符作为名称的子目录中,则自动在上一层目录中名称为其余种类修饰符的子目录内搜寻加入同名so文件(这一算法与安卓系统本身的一致);

3.如果以上条件都不满足,则仅将该so文件加入到项目外部库目录的"armeabi-v7a"子目录内.

@安卓.外部资源.属性动画

@安卓.外部资源.居间动画

@安卓.外部资源.颜色表

@安卓.外部资源.可绘制

@安卓.外部资源.菜单

@安卓.外部资源.原始数据

@安卓.外部资源.XML数据

@安卓.外部资源.值

文本型 可以应用于包或类定义成员.当用作包时,对当前包所处源文件中定义的所有类均起作用. 这些属性用作提供所处类正常执行所需求的各类外部资源文件名,分别对应以下类型的安卓资源: "animator"、"anim"、"color"、"drawable"、"menu"、"raw"、"xml"、"values".

多个文件名之间使用逗号或者换行符分隔,这些文件将被自动整合到当前程序的对应资源目录位置.

关于系统对这些外部资源文件的搜寻方式,请参见AndroidResFile.
 

@安卓.值资源 文本型 类定义成员 本属性可以应用在数据类型为"可设置值资源"或其继承类的常量/变量上,用作提供该常量/变量在不同修饰符下的对应初始资源值.
本属性必须同时提供一个安卓组合修饰符作为属性名后缀,如:"@安卓.值资源.en",即指定本属性值为所处值资源常量在英文设备上的对应值.
@安卓.窗口.布局 文本型 类定义成员或成员变量 本属性可以应用在直接/间接基础类为"窗口"的类定义成员或者窗口类中类型为"窗口组件"的成员变量上(属性名后可以选择附加一个安卓修饰符文本后缀),用作记录相关的布局参数.
本属性可以携带一个安卓组合修饰符作为后缀,用作指定本布局应用到所指定的设备环境上.如:"@安卓.窗口.布局.en-sw720-hdpi",即指定本布局应用到最小宽度为720dp,高dpi的英文设备上.
属性值中提供的布局属性可以以一个'@'字符开头,表明该布局属性及其值将强制通过编译器的检查(用户此时将自行保证该布局属性及其值的正确性).
@安卓.同步 逻辑型 方法 用作指定该方法支持在多线程中同步
@安卓.后缀文本 文本型 类或方法 本属性可以应用在类或方法定义成员上,用作在转换到Java代码后在成员名后添加一段指定文本,譬如可以为类定义成员添加类似"implements my_interface"文本以实现指定Java接口,为方法定义成员添加类似"throws"文本指定异常抛出列表等.
@安卓.附加清单 文本型 清单成员类 本属性只能在直接/间接基础类为\"清单成员\"的类定义成员上使用,用作提供一个或多个所指定的清单字段内容(用户必须自行保证该字段内容的正确性).每个字段内容的格式必须为"名称=值"形式,字段名称可以为以'.'或':'字符分隔的复合名称,如果没有提供命名空间,将自动添加默认的"android:"命名空间.字段值两侧如果没有双引号将被自动添加,多个字段之间使用换行符进行分隔.基础类中所定义的字段将自动应用到其所有继承类上,如果继承类定义了与基础类中相同名称的字段,则继承类的将覆盖基础类的.
@安卓.窗口组件.配置 文本型 窗口组件类 本属性只能在直接/间接基础类为"窗口组件"的类定义成员上使用,用作提供其在安卓布局文件中的相关配置信息.

具体所支持的属性表格式如下:

native_class = xxx
[need_helper]
[hidden]
[category] = xxx
[self] / [child]
{
    attr
    {
        [hidden]
        [discard]
        name = xxx
        shown_name = xxx
        [desc] = xxx
        data_type = xxx
        [detail_type] = xxx
        [initial_value] = xxx
        [default_value] = xxx
        [min_value] = xxx
        [max_value] = xxx
        [item]
        {
            name = xxx
            shown_name = xxx
            [desc] = xxx
        }
        [item ...]
    }
    [attr ...]
}

以上属性中,被中括号括住属性的为可选属性,否则为必须提供的属性.

名称 数据类型 解释
native_class 文本型 用作提供本组件所对应的本地java类名,必须为有效英文全名称.
helper 文本型 如果不为空文本,标记需要匹配该标识符的 已登记到系统的辅助功能插件来支持本组件的设计/编译.
hidden (顶层) 逻辑型 标记本组件设计时为隐藏状态,仅设计器使用.
category 文本型 提供本组件所处的分类,仅设计器使用.
icon 文本型 提供本组件图标的图片文件名,相对本配置信息所处火山源文件位于的目录,为空表示无.
图片文件要求如下: 格式为BMP,尺寸32x32像素,颜色深度24位,背景色洋红(红绿蓝分量值分别为255,0,255).
self   标记其中属性为组件自身使用的属性
child   标记其中属性为组件的直接子组件使用的属性
attr   标记一个新属性的定义开始
hidden (attr节中) 逻辑型 标记本属性设计时为隐藏状态,仅设计器使用.
discard 逻辑型 标记本属性已经被抛弃,被抛弃属性自动被隐藏,且在设计器/编译器输出时被自动去除.
name 文本型 本属性的名称,必须为有效英文全名称.
属性名中可以使用句点字符分隔命令空间与名称本身,如果未指定命名空间,则默认命名空间为"android"("style"和"class"名称除外).一个特例命令空间名称为"global",该命名空间表示为全局命名空间.
举例说明:
    指定命名空间: "my_app.attr_name" -> "my_app:attr_name";
    指定全局命名空间: "global.attr_name"-> "attr_name"
    使用默认命名空间: "attr_name" -> "android:attr_name"
    特例: "style" -> "style"
如果以'@'字符开头,表示后续名称文本为在辅助功能插件中有约定的名称,此时如果本组件指定了不需要辅助功能插件("need_helper"属性为假)或者在对应辅助功能插件中未定义此约定名称,将解析出错.注意实际所使用的名称将不包括首部的'@'字符.
shown_name 文本型 本属性的显示名称,仅设计器使用.
desc 文本型 本属性的描述文本,仅设计器使用.
data_type 可选项 可选项名称 数据类型 解释 定义本属性的数据类型
boolean 逻辑型  
int 整数型  
double 小数型  
string 文本型  
detail_type 可选项 可选项名称 适用数据类型 解释 定义本属性的细节类型,细节类型必须与属性的数据类型对应.
dim 小数型 位置/尺寸.单位DP.
font_size 字体尺寸.单位SP.
frac 百分比
color 文本型 颜色,格式为'#'字符后跟数个十六进制字符,所支持的格式如下:
  1. #RGB;
  2. #ARGB;
  3. #RRGGBB
  4. #AARRGGBB
其中'#'后的每个字母代表一个十六进制字符位置,'A'代表透明色;'R'代表红色;'G'代表绿色;'B'代表蓝色.
enum 枚举型,表示属性值为一系列可选文本项中的一项.
必须使用"item"为此类属性提供可选文本项列表.
flags 标记集,表示属性值为一系列可选文本项中一或多项的集合,多项标记文本之间使用'|'字符分隔.
必须使用"item"为此类属性提供可选文本项列表
drawable_res_file 可绘制资源文件名(可以是图片或对应类型xml文件名)
default_value 文本型 指定本属性在设计/编译时所使用的默认值
min_value 数值型 仅适用于整数型/小数型的属性,用作提供数值的最小和最大许可值,默认为无限制.
max_value 数值型
item   用作为本属性提供一个可选择文本项

2.安卓项目插件定义的约定名称:

约定名称 解释
基础资源类输出名:
AndroidResBase 所有资源类的基础常量类,常量值为所指定的资源文件名(文件资源)或者以'@'字符引导的资源名称(文件/值资源).如果资源常量值为以'@'字符开始的名称文本,此时编译器将认为此名称所对应的实际资源已经通过在项目选项中设置对应资源目录加入到了项目中.譬如如果资源常量值为"@test"而资源类为"可绘制资源",则编译器会自动将资源常量值转换为类似"R.drawable.test"而不会将其看作资源文件名.用户必须确保所指定名称有效,否则在编译项目资源时将出错.
AndroidResFile 所有文件类资源的基础常量类,常量值为所指定的资源文件名或者以'@'字符引导的资源名称.当为资源文件名格式时,编译器会自动搜寻加入所有具有不同安卓修饰符的同名资源文件,具体算法为:

1. 如果该资源文件名携带修饰符,则将在同一目录中搜寻加入具有其余种类修饰符的同名文件.修饰符文本必须放在文件后缀名的前面,与文件名之间使用减号分隔,如"test-hdpi.9.png"或"test-zh-hdpi.9.png"(组合修饰符),具体所允许的修饰符与安卓系统的规定相同;

2. 如果该资源文件位于以"资源类型+修饰符"作为名称的子目录中,则自动在上一层目录中名称为其余种类修饰符的子目录内搜寻加入同名资源文件. 如: 假设资源文件位于"drawable-hdpi"子目录中,而上一层目录中还存在"drawable-mdpi"子目录,则自动到该目录内搜寻. 这一搜寻机制与安卓系统本身的一致;

3. 如果以上条件都不满足,则仅将该单一资源文件加入到项目的对应资源目录中.

编译器目前支持安卓4.2提供的所有各种修饰符及其组合(组合顺序随意,编译器会自动调整为安卓系统可以识别的文本).

AndroidResValue 所有值类资源的基础类,常量值为以'@'字符引导的外部资源名称.
文件资源类输出名:
AndroidResAnimator 属性动画资源
AndroidResAnim 居间动画资源
AndroidResColorList 颜色表资源
AndroidResDrawable 可绘制资源,提供所有各种可绘制资源,包括图片及相关xml文件.
AndroidResMenu 菜单资源
AndroidResRaw 原始数据资源,属性值可以是任意文件名,其数据将被直接置入安卓资源包中.
AndroidResXML XML数据资源
值资源类输出名:
AndroidResImmValueBase 可设置值资源基础类
本类值资源常量值为以'@'字符引导的外部对应资源名称,或者直接的对应格式值文本.
如果常量值为直接设置的值文本,支持使用"@安卓.值资源"属性提供不同修饰符下的相应值.
AndroidResImmString 字符串资源(可设置值资源)
常量值为以'@'字符引导的外部字符串资源名称,或者直接的字符串文本.
AndroidResImmBool 逻辑值资源(可设置值资源)
常量值为以'@'字符引导的外部逻辑值资源名称,或者直接的逻辑值文本("真"/"假"/"true"/"false").
AndroidResImmColorValue 颜色值资源(可设置值资源)
常量值为以'@'字符引导的外部颜色值资源名称,或者直接的颜色值文本.
所支持的直接颜色值文本格式为: "#RGB","#ARGB","#RRGGBB","#AARRGGBB"四种之一.
AndroidResImmDimension 尺寸值资源(可设置值资源)
常量值为以'@'字符引导的外部尺寸资源名称,或者直接的尺寸数值文本.如果直接尺寸值未携带单位,则默认为"dp".
AndroidResImmInteger 整数值资源(可设置值资源)
常量值为以'@'字符引导的外部整数资源名称,或者直接的整数值文本.
AndroidResID ID值资源
常量值为以'@'字符引导的外部ID值资源名称
AndroidResArray 数组资源
常量值为以'@'字符引导的外部数组资源名称
其它类输出名:
AndroidView 安卓窗口组件基础类
AndroidViewGroup 窗口容器组件
AndroidLayouter 窗口布局器,唯一可以设置布局器类型的窗口组件.
AndroidActivity 窗口,对应安卓的活动(android.app.Activity)类.
AndroidService 服务,对应安卓的服务(android.app.Service)类.
AndroidBroadcastReceiver 广播接收器,对应安卓的广播接收器(android.content.BroadcastReceiver)类
各种约定方法输出名:
onInitAndroidActivity 用作初始化窗口内容时使用
GetAndroidActivityContainer 用作获取窗口本身所使用的容器组件
ms_blMainActivityLoaded 用作载入窗口内容时使用

 

 吴涛 2017/04/24