创建你自己的模板

g8 运行时从给定 Github 项目中的两个位置上寻找模板:

  • 假如存在 src/main/g8 目录就使用 src/main/g8 (src layout)
  • 不存在的话, 就使用根目录作为模板 (root layout)

src layout

推荐使用 src layout, 这样的话很容易使得模板本身也是一个 sbt 项目. 同时在把模板发布到 github 之前可以使用 sbt plugin 插件对模板进行本地的测试.

开始一个新模板项目简单的方法是参考 Giter8 的这个模板的模板:

$ g8 foundweekends/giter8.g8

这会创建一个 sbt 项目, 可以在 src/main/g8 目录下找到基础的模板源文件. default.properties 文件定义了模板的字段以及默认值, 它采用了 Java 属性文件的格式.

default.properties

default.properties 文件可以放在 project/ 目录下, 或者是模板的根目录下. 属性是简单的键值对, 值在应用模板时可被替换.

StringTemplate, 应用于 Scalasti, 是应用 Giter8 模板的引擎, 因此在源文件中的模板字段要用前后两个 $ 字符包裹起来. 例如, 对于 “classname” 字段可能在源文件中的引用方式是这样的:

class $classname$ {

模板字段本身可被其他字段内部引用. 比如, 你可以基于给定的用户 Github id 来声明一些 URL:

name = URL Builder
github_id=githubber
developer_url=https://github.com/$github_id$
project_url=https://github.com/$github_id$/$name;format="norm"$

这会在交互界面下产生如下效果:

name [URL Builder]: my-proj
github_id [githubber]: n8han
project_url [https://github.com/n8han/my-proj]:
developer_url [https://github.com/n8han]:

name 字段

如果定义了 name 字段, 它会被 Giter8 特殊处理. 它被认定为所创建项目的名称, 因此 g8 运行时会基于这个 name (替换了空格和大写字母)创建一个目录用于存放所有模板输出. 倘若 name 字段未在模板中指定, g8 会把输出文件创建在用户当前的工作目录. 在这两种情况下, 输出的文件目录层次关系都会保持与模板源目录中定义的一致. 文件和目录名同样可以使用定义的模板字段, 例如.

src/main/g8/src/main/scala/$classname$.scala

package 字段

如果定义的 package 字段, 它会被作为用户源文件的包名. 在目录名上的 $package$ 会展开为包目录结构. 例如, net.databinder 会生成目录 net/databinder.

verbatim 字段

如果定义了 verbatim 字段, 它被认为是符合模式的以空格分隔的文件名列表, 如 *.html *.js. 匹配 verbatim 模式的文件不会应用模板中定义的字段.

Maven 属性

maven 属性 告知 Giter8 去查询 Maven 中心仓库. 相比于指定一个特定的版本 (这得为每一次发布更新模板), 可以只声明要用的库, giter8 将会根据 Maven 中心仓库设置相应库的最新版本.

这一属性值的格式为 maven(groupId, artifactId). 记住, Scala 项目发布时经常会在构件 id 中注明 Scala 版本标识. 所以对于 Unfiltered 库, 我们可以如下方式指明最新版本号:

name = My Template Project
description = Creates a giter8 project template.
unfiltered_version = maven(net.databinder, unfiltered_2.11)

root layout

尚处在试难中的布局方式叫做 root layout, 它直接使用 Github 项目的根目录作为模板的根目录.

由于你不能再在 project 下的文件应用模板字段, 所以这种布局应用方式有很大的局限性. 它也许不需要用于 sbt 来构建的模板, 或不包含任何字段的模板有用处.

格式化模板字段

Giter8 对于格式化模板字段有内置的支持. 当引用字段时可加入格式化选项. 例如, name 字段可用如下方法格式为大写字母开始的驼峰形式:

$name;format="Camel"$

格式化选项有:

upper    | uppercase       : all uppercase letters
lower    | lowercase       : all lowercase letters
cap      | capitalize      : uppercase first letter
decap    | decapitalize    : lowercase first letter
start    | start-case      : uppercase the first letter of each word
word     | word-only       : remove all non-word letters (only a-zA-Z0-9_)
Camel    | upper-camel     : upper camel case (start-case, word-only)
camel    | lower-camel     : lower camel case (start-case, word-only, decapitalize)
hyphen   | hyphenate       : replace spaces with hyphens
norm     | normalize       : all lowercase with hyphens (lowercase, hyphenate)
snake    | snake-case      : replace spaces and dots with underscores
packaged | package-dir     : replace dots with slashes (net.databinder -> net/databinder)
random   | generate-random : appends random characters to the given string

一个值为 My Project 的 name 字段可用如下方式渲染为:

$name$ -> "My Project"
$name;format="camel"$ -> "myProject"
$name;format="Camel"$ -> "MyProject"
$name;format="normalize"$ -> "my-project"
$name;format="lower,hyphen"$ -> "my-project"

注, 可同时指定多个格式化选项 (逗号分隔), 它们以给定的顺序依次应用.

对于文件或目录名中的字段, 可通过在字段名后加双下划线来指定格式化选项. 例如, 目录名为 $organization__packaged$ 的话会转换 org.somewhere 为 org/somewhere, 就像是内建的对 package 字段支持那样. 文件名为 $name__Camel$.scala, 且 name awesome project 的话, 将会创建文件 AwesomeProject.scala.

本地测试模板

模板可通过 file:// 协议形式的 URL 传递给 g8, 这时保存存在文件系统中的模板能被使用. 带上 --force 选项会在无提示的情况下覆盖文件输出, 你可借以测试对模板的修改.

比如, 倘若你已把 Unfiltered 模板克隆到了本地, 就可以运行如下命令:

$ g8 file://unfiltered.g8/ --name=uftest --force

在另一个终端中, 测试模板的输出.

$ cd uftest/
$ sbt
> ~ compile

修改模板, 保存在 .g8 下的模板源目录中, 然后回到前一个终端运行命令来难模板:

$ g8 file://unfiltered.g8/ --name=uftest --force

在你的 uftest sbt 会话中, ~ compile 命令处于等待状态, 一旦发现有文件修改就会自动重新编译.

使用 Giter8Plugin

Giter8 提供了一个 sbt 插件用于在推送模板到 Github 分支之前进行测试. 如果你使用上面推荐的 foundweekends/giter8.g8 模板, 它应该已经这样配置好了的.

如果你需要为已有的模板项目升级使用这个插件, 你可以在 project/giter8.sbt 中加上如下依赖:

addSbtPlugin("org.foundweekends.giter8" % "sbt-giter8" % "0.7.1")

当你配置了使用该插件, 并从该模板工程目录进到 sbt 控制台后, 就可以运行 g8Test 来应用模板, 默认的输出是在 target/sbt-test 目录下, 并且针对那个项目在新 forked 进程中运行 scripted 测试. 你可以通过 project/giter8.test 或 src/test/g8/test 来进行 scripted 测试, 不然就会调用 >test. 采用一个 sbt 项目是一个很好的模板的健壮性检查.

但是, 假如你的模板不是一个 sbt 项目会如何呢?

project/default.properties
TodaysMenu.html

你仍然可以使用 sbt 控制台来测试模板. 基本的 g8 行为将会对模板应用默认的字段值并写入到相同的 target/g8 目录中.

只要你把模板推送到了 Github (记往项目名必须以 .g8 结尾), 你就可以用真实的 g8 进行测试. 当你已准备好了, 把你的模板项目加到 wiki 页面上, 这样别的 giter8 用户就能找到它.

results matching ""

    No results matching ""