From acd5a9ecb68349d283581a1fe95ed06e4758a414 Mon Sep 17 00:00:00 2001 From: "Erik C. Thauvin" Date: Sat, 23 Jan 2016 16:01:55 -0800 Subject: [PATCH] Added pandoc task. --- README.html | 241 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 54 ++++++++---- build.gradle | 20 +++++ 3 files changed, 299 insertions(+), 16 deletions(-) create mode 100644 README.html diff --git a/README.html b/README.html new file mode 100644 index 0000000..6ca6fdf --- /dev/null +++ b/README.html @@ -0,0 +1,241 @@ + + + + + + + + + + + + +

Semantic Version Annotation Processor

+

An annotation processor that automatically generates a Version class containing the semantic version (major, minor, patch, etc.) that is read from a Properties file or defined in the annotation.

+

This processor was inspired by Cédric Beust's version-processor.

+

Examples

+ +
@Version(major = 1, minor = 0, patch = 0, prerelease = "beta")
+public class A {
+// ...
+ +
@Version(properties = "version.properties")
+public class A {
+// ...
+
# version.properties
+version.major=1
+version.minor=0
+version.patch=0
+version.prerelease=beta
+

Template

+

Upon running the annotator processor, a source file GeneratedVersion.java is automatically generated with static methods to access the semantic version data. The source is based on a fully customizable Velocity template.

+
@Version(template = "myversion.vm")
+public class A {
+// ...
+

Default Template

+

The default template implements the following static methods:

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescriptionExample
getProjectThe project name, if any.MyProject
getBuildDateThe build date.java.util.Date
getVersionThe full version string.1.0.0-alpha+001
getMajorThe major version.1
getMinorThe minor version.0
getPatchThe patch version.0
getPreReleaseThe pre-release version, if any.alpha
getBuildMetadataThe build metadata, if any.001
+

Custom Template

+

A very simple custom template might look something like:

+
/* myversion.vm */
+package ${packageName}
+
+import java.util.Date;
+
+public final class ${className} {
+    public final static String BUILDMETA = "${buildmeta}";
+    public final static Date DATE = new Date(${epoch}L);
+    public final static int MAJOR = ${major};
+    public final static int MINOR = ${minor};
+    public final static int PATCH = ${patch};
+    public final static String PRERELEASE = "${prerelease}";
+    public final static String PROJECT = "${project}";
+}
+

The Velocity variables are automatically filled in by the processor.

+

Elements & Properties

+

The following annotation elements and properties are available:

+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementPropertyDescriptionDefault
projectversion.projectThe project name.
majorversion.majorThe major version number.1
minorversion.majorThe minor version number.0
patchversion.patchThe patch version number.0
prereleaseversion.prereleaseThe pre-release version.
buildmetaversion.buildmetaThe build metadata version.
classNameThe name of the generated class.GeneratedVersion
propertiesThe properties file.
templateThe template file.version.vm
+

In order to easily incorporate with existing projects, the property keys may be assigned custom values:

+
@Version(
+  properties = "example.properties", 
+  majorKey = "example.major",
+  minorKey = "example.minor",
+  patchKey = "example.patch",
+  prereleaseKey = "example.prerelease",
+  buildmetaKey = "example.buildmeta",
+  projectKey = "example.project"
+)
+public class Example {
+// ...
+
# example.properties
+example.project=Example
+example.major=1
+example.minor=0
+example.patch=0
+...
+ + diff --git a/README.md b/README.md index e0d6135..ecd599c 100644 --- a/README.md +++ b/README.md @@ -8,23 +8,22 @@ This processor was inspired by Cédric Beust's [version-processor](https://githu * Using annotation elements: - ```java - @Version(major = 1, minor = 0, patch = 0, prerelease = "beta") - public class A { - // ... - ``` +```java +@Version(major = 1, minor = 0, patch = 0, prerelease = "beta") +public class A { +// ... +``` * Or using a [properties](https://docs.oracle.com/javase/tutorial/essential/environment/properties.html) file: - ```java - @Version(properties = "version.properties") - public class A { - // ... - ``` +```java +@Version(properties = "version.properties") +public class A { +// ... +``` - and `version.properties` containing: - - ```ini +```ini +# version.properties version.major=1 version.minor=0 version.patch=0 @@ -41,7 +40,9 @@ public class A { // ... ``` -The [default template]() implements the following static methods: +### Default Template + +The default template implements the following static methods: Method | Description | Example ------------------|----------------------------------|------------------ @@ -54,6 +55,28 @@ Method | Description | Example `getPreRelease` | The pre-release version, if any. | `alpha` `getBuildMetadata`| The build metadata, if any. | `001` +### Custom Template + +A very simple custom template might look something like: + +```java +/* myversion.vm */ +package ${packageName} + +import java.util.Date; + +public final class ${className} { + public final static String BUILDMETA = "${buildmeta}"; + public final static Date DATE = new Date(${epoch}L); + public final static int MAJOR = ${major}; + public final static int MINOR = ${minor}; + public final static int PATCH = ${patch}; + public final static String PRERELEASE = "${prerelease}"; + public final static String PROJECT = "${project}"; +} +``` +The Velocity variables are automatically filled in by the processor. + ## Elements & Properties The following annotation elements and properties are available: @@ -86,9 +109,8 @@ public class Example { // ... ``` -with `example.properties` containing: - ```ini +# example.properties example.project=Example example.major=1 example.minor=0 diff --git a/build.gradle b/build.gradle index 92b7bab..345ff2c 100644 --- a/build.gradle +++ b/build.gradle @@ -2,6 +2,8 @@ apply plugin: 'java' apply plugin: 'idea' apply plugin: 'maven' +import org.apache.tools.ant.taskdefs.condition.Os + defaultTasks 'deploy' def getVersion(isIncrement = false) @@ -92,4 +94,22 @@ task release(dependsOn: ['deploy', 'wrapper', 'uploadArchives']) << { group = 'Publishing' description = 'Releases new version.' isRelease = true +} + +task pandoc(type: Exec) { + group = 'Documentation' + def pandoc_args = ['--from', 'markdown_github', '--to', 'html5', '-s', '-o', 'README.html', 'README.md'] + if (Os.isFamily(Os.FAMILY_WINDOWS)) + { + commandLine(['cmd', '/c', 'pandoc'] + pandoc_args) + } + else + { + executable '/usr/local/bin/pandoc' + args pandoc_args + } + standardOutput = new ByteArrayOutputStream() + ext.output = { + return standardOutput.toString() + } } \ No newline at end of file