Skip to content

Commit 5e98cb0

Browse files
leafee98leafee98
committed
modified docs, generate executable jar by pom.xml
1 parent c1d8a7e commit 5e98cb0

File tree

3 files changed

+216
-0
lines changed

3 files changed

+216
-0
lines changed

‎README.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,36 @@
11
# Class Schedule To Icalendar (Core)
22

3+
潜在的毕业设计项目, 在此之前会限制源码级别的使用.
4+
5+
根据指定格式的课程表定义文件的信息, 生成可供日历软件导入的`ics`文件. 本项目是逻辑实现的核心部分.
6+
7+
## 课程表定义文件(试验阶段, 未来有可能会进行格式上的修改)
8+
9+
见[csti-define.md](/doc/csti-define.md)
10+
11+
## 特征
12+
13+
- 项目生成结果符合[rfc 5545](https://tools.ietf.org/html/rfc5545)标准
14+
- 生成结果中, 事件包括事件前的提醒
15+
- 生成结果中, 支持事件名称和事件描述的自定义
16+
- 支持Java库内已有的所有时区
17+
18+
## 使用
19+
20+
编译好的主程序有为命令行程序, 有两个参数可以使用.
21+
22+
```
23+
-i <input file>
24+
-o <output file>
25+
```
26+
27+
如果 `<input file>` 或 `<output file>` 值为短横线或未设置命令行参数, 则表示采用标准输入/输出流.
28+
29+
## 待办
30+
31+
[ ] 修正转义不完善的问题(针对`\$`等转义字符)
32+
[ ] 对于可选的留空的配置选项, 使用默认值而不是空字符串作为配置结果
33+
34+
## 许可
35+
36+
允许编译和使用, 但暂时不开放对源码的直接复制使用

‎doc/csti-define.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# 课程表定义文件 格式描述
2+
3+
## 格式要求
4+
5+
每一个以单个空格为起始的行都被认作时上一行的继续, 在处理时会先移除行首的一个空格,再进行行的合并.
6+
7+
> 如果需要进行断行, 只需要在新的一行以一个空格作为起始即可.
8+
>
9+
> 如果新的一行以多个空格起始, 则在合并上一行时会保留除第一个空格以外的空格
10+
>
11+
> `tab` 起始的行**不**被视作上一行的继续
12+
13+
全局配置的选项必须以 `[[[` 和 `]]]` 进行包括, 且两个三括号必须位于单独的一行, 不得紧接其他配置内容.
14+
15+
每节课程的配置必须以 `<<<` 和 `>>>` 进行包括, 且两个三括号必须位于单独的一行, 不得紧接其他配置内容.
16+
17+
在 `[[[` 和 `]]]` 或 `<<<` 和 `>>>` 之外的内容会被忽略, 即可以将其他说明性文字写在三括号之外
18+
19+
如果需要使用配置选项的默认值, 则需要直接在配置文件中移除该选项的配置, 或将此项配置留空
20+
21+
## 全局配置
22+
23+
### `event-summary-format`
24+
25+
定义生成事件的名称格式, 支持进行[变量替换](#变量替换), 同是也要注意[格式定义中特殊字符转义](#格式定义中特殊字符转义), 默认值为 `${lessonName}-${location}`
26+
27+
28+
### `event-description-format`
29+
30+
定义生成事件的描述格式, 格式要求同[事件名称格式的定义](#event-summary-format), 默认值为 `name:${lessonName}\nlocation:${location}\nteacher:${teacher}\ntype:${lessonType}\nremark:${remark}\nschedule:${scheduleFull}`
31+
32+
### `timezone`
33+
34+
时区设置, 值为一串字符串, 内部实现是借助于 `Java.time` 来获取夏令时信息, 所以要求可以被Java的 `ZoneId` 解析到正确的时区
35+
36+
### `first-day-of-week`
37+
38+
定义每周的第一天为周几, 通常西方使用周日作为每周的第一天, 但是东方则是一般使用周一作为每周的第一天.
39+
40+
此处的值为一个整数, 范围是 `0-7`, 其中 `0` 和 `7` 都代表周日
41+
42+
### `semester-start-date`
43+
44+
定义学期的第一天, 格式定为 `yyyy-MM-dd`, 注意这一天的与 `first-day-of-week` 应该相吻合
45+
46+
### `reminder-time`
47+
48+
定义课程的提醒时间, 整数表示延后, 负数表示提前, 单位支持 `s`\`m` 和 `h`, 分别表示提前或者延后的秒\分\时.
49+
50+
可以填写多个值, 其间使用逗号分隔, 表示对于同一节课提醒多次
51+
52+
比如 `-1h,-15m` 表示在上课前1小时和前15分钟提醒两次
53+
54+
### `lesson-ranges`
55+
56+
定义每节课的起止时间, 格式为 `1=08:00:00-08:45:00`, 表示每天的第1节课自08:00:00开始, 直到08:45:00时下课.
57+
58+
可以写多个定义, 每个定义之间通过逗号分隔, 格式中 `=` 前的数字可以不按照递增规律进行编写, 但是所有定义最后一定要是从1到n不重不漏. 比如下面两个定义就是可以被接受并且等价的, 注意这里为了可读性套用了以空格起始的行视为上一行的延续的规则.
59+
60+
```
61+
lesson-ranges:
62+
1=08:00:00-08:45:00,
63+
3=09:50:00-10:35:00,
64+
2=08:50:00-09:35:00,
65+
4=10:40:00-11:25:00,
66+
5=11:30:00-12:15:00
67+
```
68+
69+
```
70+
lesson-ranges:
71+
1=08:00:00-08:45:00,
72+
2=08:50:00-09:35:00,
73+
3=09:50:00-10:35:00,
74+
4=10:40:00-11:25:00,
75+
5=11:30:00-12:15:00
76+
```
77+
78+
## 单个课程配置
79+
80+
### `name`
81+
82+
课程的名称
83+
84+
### `type`
85+
86+
课程的类型
87+
88+
### `teacher`
89+
90+
课程的授课教师
91+
92+
### `location`
93+
94+
上课的地点, 此项属性会被填充到 `ics` 文件的事件中 `LOCATION` 的位置
95+
96+
### `remark`
97+
98+
备注, 可以记录其他一些信息
99+
100+
### `schedule`
101+
102+
课程的安排时间定义.
103+
104+
每一条安排时间定义被划分为三个部分, 即**周次定义**, **周天定义**, **课程节数安排**. 中间以竖线(`|`)分隔, 每个课程安排定义以分号(`;`)结尾.
105+
106+
三个部分中每一个部分都是一个列表, 可以填写数字范围 `1-15` 表示从 `1` 到 `15` 的每一个数字, 也可以直接写一个数字如 `4`, 数字和数字范围可以混用并多用, 比如 `1,3,5-9` 和 `1,3,5,6,7,8,9` 等价.
107+
108+
假设全局配置的每节课程起止时间和课程安排时间分别如下(仅提出关键配置, 未遵守文件结构), 则表示此课程安排在在 `第4\6\7\8\10周的周1的第1到3节课程`, 和 `第4\5\7\8\9\10周的周2的第10到第12节`. 生成结果中的课程实际起止时间为 `08:00:00` 到 `10:35:00`, 和 `18:30:00` 到 `20:55:00`.
109+
110+
```
111+
lesson-ranges:
112+
1=08:00:00-08:45:00,
113+
2=08:50:00-09:35:00,
114+
3=09:50:00-10:35:00,
115+
4=10:40:00-11:25:00,
116+
5=11:30:00-12:15:00
117+
6=13:30:00-14:15:00,
118+
7=14:20:00-15:05:00,
119+
8=15:20:00-16:05:00,
120+
9=16:10:00-16:55:00,
121+
10=18:30:00-19:15:00,
122+
11=19:20:00-20:05:00,
123+
12=20:10:00-20:55:00
124+
125+
...
126+
127+
schedule:
128+
4,6-8,10|1|1-3;
129+
4-5,7-8,9,10|2|10-12;
130+
131+
```
132+
133+
在生成结果中的课程实际起止时间为全局配置中对应此课程的第一节课的开始时间到全局配置中对应此课程的最后一节课的结束时间. 即**同一定义中连续安排的课程会被生成为一个事件**.
134+
135+
> 注意三个部分中的列表即便写作 `3-5,6-8`, 其效果也是和 `3-8`是等价的, 最终会生成为一个事件
136+
>
137+
> 如果在第三个部分课次定义中需要强调是先上 `3-5` 再上 `6-8`, 将其分为两个事件, 则需要将其分开在两个课程安排定义中, 如下:
138+
>
139+
> ```
140+
> schedule:
141+
> 1-3|1|3-8;
142+
>
143+
> 改为
144+
>
145+
> schedule:
146+
> 1-3|1|3-5;
147+
> 1-3|1|6-8;
148+
> ```
149+
150+
## 变量替换
151+
152+
```
153+
${lessonName} 课程的 name 属性
154+
${location} 课程的 location 属性
155+
${teacher} 课程的 teacher 属性
156+
${lessonType} 课程的 type 属性
157+
${remark} 课程的 remark 属性
158+
${scheduleFull} 课程的 schedule 完整属性
159+
```
160+
161+
暂未实现的变量替换
162+
163+
```
164+
${weekInfo} 本节课程发生时的当前周次
165+
${schedule} 本节课程的起止课程节
166+
````
167+
168+
## 格式定义中特殊字符转义
169+
170+
建议遵守以下转义规则, 否则可能会出现意料之外的结果
171+
172+
- 换行符号需要使用 `\n` 进行转义
173+
- `$` 符号需要使用 `\$` 进行转义
174+
- `{` 符号需要使用 `\{` 进行转义
175+
- `}` 符号需要使用 `\}` 进行转义

‎pom.xml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,13 @@
5050
<plugin>
5151
<artifactId>maven-jar-plugin</artifactId>
5252
<version>3.0.2</version>
53+
<configuration>
54+
<archive>
55+
<manifest>
56+
<mainClass>com.github.leafee98.CSTI.core.App</mainClass>
57+
</manifest>
58+
</archive>
59+
</configuration>
5360
</plugin>
5461
<plugin>
5562
<artifactId>maven-install-plugin</artifactId>

0 commit comments

Comments
 (0)