4.2.4. 格式化工具
4.2.4. 格式化工具
仓颉语言格式化工具使用指南
功能简介
cjfmt仓颉格式化工具是一款基于 Cangjie Programming Language CodingStyle 开发的代码自动格式化工具。
使用说明
- 可以在 VS Code 安装本工具插件进行使用
- 使用命令行操作
cjfmt [option] file [option] file
cjfmt -h 帮助信息，选项介绍
Usage:
cjfmt -f fileName [-o fileName]
cjfmt -d fileDir [-o fileDir]
Options:
-h Show usage
eg: cjfmt -h
-d Specifies the file directory in the required format. The value can be a relative path or an absolute path.
eg: cjfmt -d test/
-o <value> Output. If a single file is formatted, '-o' is followed by the file name. Relative and absolute paths are supported;
If a file in the file directory is formatted, a path must be added after -o. The path can be a relative path or an absolute path.
eg: cjfmt -f a.cj -o ./fmta.cj
eg: cjfmt -d ~/testsrc -o ./testout
-l <region> Only format lines in the specified region for the provided file. Only valid if a single file was specified.
Region has a format of [start:end] where 'start' and 'end' are integer numbers representing first and last lines to be formated in the specified file.
Line count starts with 1.
eg: cjfmt -f a.cj -o ./fmta.cj -l 1:25
使用命令行进行格式化操作，如果没有指定-d，那么只对一个仓颉文件进行格式化，-o指定的是仓颉文件。
如果指定了-d，那么是对一个目录下的所有仓颉文件进行格式化，-o指定的是目录。
//选项-o 新建一个.cj文件导出格式化后的代码，源文件和输出文件支持相对路径和绝对路径。
例子1：
cjfmt -f ../../../test/uilang/Thread.cj -o ../../../test/formated/Thread.cj
//格式化并覆盖源文件，支持相对路径和绝对路径。
例子2：
cjfmt -f ../../../test/uilang/Thread.cj
//选项-d让用户指定扫描仓颉源代码目录，对文件夹下的仓颉源码格式化，支持相对路径和绝对路径。
//选项-o为输出目录，可以是已存在的路径，若不存在则会创建相关的目录结构，支持相对路径和绝对路径。
//目录的最大长度MAX_PATH不同的系统之间存在差异，如Windows上这个值一般不能超过260；在Linux上这个值一般建议不能超过4096。
例子1：
cjfmt -d test/ //源文件目录为相对目录。
cjfmt -d test/ -o /home/xxx/testout
例子2：
cjfmt -d /home/xxx/test //源文件目录为绝对目录。
cjfmt -d /home/xxx/test -o ../testout/
例子3：
cjfmt -d testsrc/ -o /home/../testout 源文件文件夹testsrc/不存在；报错：error: Source file path not exist!
//选项-l允许用户指定应格式化文件的哪一部分。格式化程序将仅对提供的行范围内的源代码应用规则。
//-l选项仅适用于格式化单个文件（选项-f）。如果指定了目录（选项-d），则-l选项无效。
例子:
cjfmt -f a.cj -o .cj -l 10:25 //仅格式化第10行至第25行
格式化规则
- 一个源文件按顺序包含版权、package、import、顶层元素，且用空行分隔。
【正例】
package com.huawei.myproduct.mymodule
from std import collection.HashMap
public class ListItem <: Component {
}
class Helper {
}
注意：仓颉格式化工具不会强制用空行将版权信息部分与其他部分分隔，若用户在版权信息下方留有一个或多个空行，则格式化工具会保留一个空行。
- 采用一致的空格缩进，每次缩进 4 个空格。
【正例】
class ListItem {
var content: Array<Int64>
init(
content: Array<Int64>,
isShow!: Bool = true,
id!: String = ""
) {
this.content = content
}
}
- 使用统一的大括号换行风格，对于非空块状结构，大括号使用 K&R 风格。
【正例】
enum TimeUnit {
Year | Month | Day | Hour
}
class A {
var count = 1
}
func fn(a: Int64): Unit {
if (a > 0) {
} else {
}
}
let add = { base: Int64, bonus: Int64 =>
print("符合 news")
base + bonus
}
- 按照 Cangjie Programming Language CodingStyle 中的规则 G.FMT.10，使用空格突出关键字和重要信息。
【正例】
var isPresent: Bool = false
func method(isEmpty!: Bool): RetType { ... }
method(isEmpty: isPresent)
0..MAX_COUNT : -1
var hundred = 0
do {
hundred++
} while (hundred < 100)
func fn(paramName1: ArgType, paramName2: ArgType): ReturnType {
...
for (i in 1..4) {
...
}
}
let listOne: Array<Int64> = [1, 2, 3, 4]
let salary = base + bonus
x++
- 减少不必要的空行，保持代码紧凑。
【反例】
class MyApp <: App {
let album = albumCreate()
let page: Router
init() {
this.page = Router("album", album)
}
override func onCreate(): Unit {
println( "album Init." )
}
}
- 按照 Cangjie Programming Language CodingStyle 中的规则 G.FMT.12 规定的优先级排列修饰符关键字。
以下是推荐的顶层元素的修饰符排列优先级：
public
open/abstract
以下是推荐的实例成员函数或实例成员属性的修饰符排序优先级：
public/protected/private
open
override
以下是推荐的静态成员函数的修饰符排序优先级：
public/protected/private
static
redef
以下是推荐的成员变量的修饰符排序优先级：
public/protected/private
static
- 多行注释的格式化行为
以 * 开头的注释， * 会互相对齐， 不以 * 开头的注释，则会保持注释原样。
注意事项
仓颉格式化工具暂不支持语法错误的代码的格式化
仓颉格式化工具暂不支持元编程的格式化。