Added guide

gradle/guide.gradle

@@ -0,0 +1,60 @@
+apply plugin: 'org.asciidoctor.gradle.asciidoctor'
+
+javadoc {
+    excludes = ['**/*.html', 'META-INF/**']
+
+    options.use         = true
+    options.splitIndex  = true
+    options.encoding    = 'UTF-8'
+    options.author      = true
+    options.version     = true
+    options.windowTitle = "${project.name} ${project.version} API"
+    options.docTitle    = "${project.name} ${project.version} API"
+    options.footer      = javadocFooter
+    options.links       = ['http://www.slf4j.org/apidocs/',
+                           'http://junit.org/javadoc/latest/',
+                           'http://docs.oracle.com/javase/7/docs/api/']
+}
+
+task jarApi(type: Jar, dependsOn: javadoc) {
+    archiveName    = "${project.name}-${project.version}-javadoc.jar"
+    destinationDir = "$buildDir/assemble/jars" as File
+    from "$buildDir/api"
+}
+
+asciidoctor {
+    baseDir   = project.file('guide/src/asciidoc')
+    sourceDir = project.file('guide/src/asciidoc')
+    options = [
+        attributes: [
+            toc                     : 'left',
+            doctype                 : 'book',
+            icons                   : 'font',
+            encoding                : 'utf-8',
+            sectlink                : true,
+            sectanchors             : true,
+            numbered                : true,
+            linkattrs               : true,
+            imagesdir               : 'images',
+            linkcss                 : true,
+            'source-highlighter'    : 'coderay',
+            'coderay-linenums-mode' : 'inline',
+            'project-author'        : 'Andres Almiray',
+            'project-url'           : project.project_url,
+            'project-vcs'           : project.project_scm,
+            'project-issue-tracker' : project.project_issues,
+        ]
+    ]
+    sourceDocumentNames = files('guide/src/asciidoc/index.adoc')
+}
+
+task guide(type: Copy, dependsOn: [javadoc, asciidoctor]) {
+    destinationDir = "$buildDir/guide" as File
+    from(javadoc.outputs) { into 'api' }
+    from("$buildDir/asciidoc")
+}
+
+task guideZip(type: Zip, dependsOn: guide) {
+    baseName = "${project.name}-guide"
+    from "$buildDir/guide"
+}

guide/src/asciidoc/configuration.adoc

@@ -0,0 +1,26 @@
+
+[[_configuration]]
+= Build Configuration
+
+== Gradle
+
+[source,groovy,options="nowrap"]
+[subs="attributes"]
+----
+dependencies {
+    compile '{project-group}:{project-name}:{project-version}'
+}
+----
+
+== Maven
+
+[source,xml,options="nowrap"]
+[subs="attributes,verbatim"]
+----
+<dependency>
+    <groupId>{project-group}</groupId>
+    <artifactId>{project-name}</artifactId>
+    <version>{project-version}</version>
+</dependency>
+----
+

guide/src/asciidoc/index.adoc

@@ -0,0 +1,15 @@
+= EZMorph {project-version}
+:author: {project-author}
+:revnumber: {project-version}
+:toclevels: 10
+
+include::_links.adoc[]
+
+:leveloffset: 1
+include::introduction.adoc[]
+include::usage.adoc[]
+include::configuration.adoc[]
+
+= Links
+
+link:api/index.html[Javadoc, window="_blank"]

guide/src/asciidoc/introduction.adoc

@@ -0,0 +1,57 @@
+
+[[_introduction]]
+= Introduction
+
+EZMorph is simple java library for transforming an Object to another Object.
+
+EZMorph's key strenghts are:
+
+ * Supports transformations for primitives and Objects
+ * Supports transformations for multidimensional arrays
+ * Supports transformations with DynaBeans
+ * Small memory footprint (~80K)
+
+EZMorph comes with another feature: `ArrayAssertions`. JUnit 3.x does not have an `assertEquals()` method for asserting
+array equality, and JUnit 4.x has a limited one (it only supports Object[] not primitive arrays). With ArrayAssertions
+is possible to compare a boolean[] with a boolean[] or even a Boolean[], an those arrays can be multidimensional too.
+
+EZMorph began life as the converter package on https://github.com/aalmiray/json-lib[Json-lib, window="_blank"] but seeing
+that the features provided were more generic than JSON parsing, it became a project on its own.
+
+== Related projects
+
+There are other projects that perform Objetc to Object conversion:
+
+[cols="1,3", options="header"]
+|===
+
+| Project Name | Description
+
+| http://commons.apache.org/proper/commons-beanutils/["Commons Beanutils", window="_blank"]
+| `ConvertUtils`: Utility methods for converting scalar String values to objects of the specified Class, String arrays
+  to arrays of the specified Class.
+
+| http://commons.apache.org/proper/commons-lang/["Commons Lang", window="_blank"]
+| `ArrayUtils`: Operations on arrays, primitive arrays (like int[]) and primitive wrapper arrays (like Integer[]).
+
+| http://commons.apache.org/dormant/convert/["Commons Convert", window="_blank"]
+| Commons-Convert aims to provide a single library dedicated to the task of converting an object of one type to another.
+  The first stage will focus on Object to String and String to Object conversions.
+
+| http://morph.sourceforge.net/[Morph, window="_blank"]
+| Morph is a Java framework that eases the internal interoperability of an application. As information flows through an
+  application, it undergoes multiple transformations. Morph provides a standard way to implement these transformations.
+
+| http://gleamynode.net/dev/lorentz/docs/index.html["Lorentz", window="_blank"]
+| Lorentz is a generic object-to-object conversion framework. It provides a simple API to convert a Java objects of one
+  type into an object of another type.
+
+| http://projects.spring.io/spring-framework/["Spring Framework", window="_blank"]
+| Spring has an excellent support for PropertyEditors, that can also be used to transform Objects to/from Strings.
+
+| http://dozer.sourceforge.net/["Dozer", window="_blank"]
+| Dozer is a powerful, yet simple Java Bean to Java Bean mapper that recursively copies data from one object to another.
+  Typically, these Java Beans will be of different complex types.
+
+|===
+

guide/src/asciidoc/usage.adoc

@@ -0,0 +1,59 @@
+
+[[_usage]]
+= Usage
+
+Morphing Objects is as easy as calling `morph()` on a `Morpher` or `ObjectMorpher` instance. You may have noticed that
+`Morpher` does not have a `morph()` method but `ObjectMorpher` does, that is because `Morpher` is used on primitive Morphers
+and we want to avoid the prize of auto-boxing.
+
+Using EZMorph is as straight forward as shown in the next example
+
+[source,java]
+----
+int i = new IntMorpher().morph("123");
+assertEquals(123, i); // true!
+
+String str = new StringMorpher().morph(Integer.valueOf(123));
+assertEquals("123", str); // true!
+----
+
+You can morph arrays too. It doesn't matter how many dimensions the arrays may have, EZMorph will take care of the rest.
+
+[source,java]
+----
+Boolean[] bools = new ObjectArrayMorpher(
+                        new BooleanObjectMorpher()).morph(
+                             new String[]{"true", "false"});
+assertEquals(Boolean.TRUE, bools[0]);  // true!
+assertEquals(Boolean.FALSE, bools[1]); // true!
+----
+
+EZMorph can also transform beans of different types, even `DynaBeans` from apache commons-beanutils
+
+[source,java]
+----
+// will morph a BeanA into a BeanB, where a property of BeanB is also a property of BeanA
+BeanA beanA = ... // initialized elsewhere
+morpherRegistry.registerMorpher(new BeanMorpher(BeanB.class, morpherRegistry));
+BeanB beanB = (BeanB) morpherRegistry.morph(BeanB.class, beanA);
+
+// will morph a DynaBean into a MyBean instance
+DynaBean dynaBean = ... // initialized elsewhere
+morpherRegistry.registerMorpher( new BeanMorpher(MyBean.class, morpherRegistry));
+MyBean myBean = (MyBean) morpherRegistry.moprh(MyBean.class, dynaBean);
+----
+
+EZMorph comes with a handy class for working with Morphers named `MorpherRegistry`. It works much like ConvertUtils on
+commons-beanutils. This class is not a singleton like ConvertUtils, so it is possible to have multiple registries with
+different Morphers that support the same target class, but take different default values or support different source classes.
+Another convenient class is `MorphUtils`, you can register standard Morphers to any MorpherRegistry with it.
+
+[source,java]
+----
+MorpherRegistry morperRegistry = new MorpherRegistry();
+MorphUtils.registerStandardMorphers(morpherRegistry);
+Integer i = (Integer) morpherRegistry.morph(Integer.class, "A");
+// "A" is not a number, so morph() returns Integer(0)
+assertEquals(Integer.valueOf(0), i);
+----
+