Merge branch 'release-0.3.1'

README.md

@@ -1,23 +1,84 @@
 Lorenz
 ======
 
-Lorenz is a library for interacting with Java deobfuscation mappings, within the Java
-programming language. Licensed MIT.
+Lorenz is a library intended for creating and altering de-obfuscation mappings for Java
+programs (compiled or otherwise), this is done independent of the format being used. Lorenz
+supports a variety of mapping formats itself:
+
+- SRG
+- CSRG
+- TSRG
+
+There are also plans to support the following mapping formats for the (eventual) 1.0.0
+release:
+
+- Engima
+- JAM
+
+## Branches
+
+Lorenz makes use of the [git-flow] branching structure, briefly put:
+
+- **master** is the source for the latest released version
+- **develop** is the source of the latest developments
+
+All releases will also be tagged, with further descriptions in their GitHub release.
+These descriptions will include information such as migration advice.
 
 ## Usage
 
-Lorenz is available through my Maven repository (repo.jamiemansfield.me).
+Lorenz is centred around the `MappingSet`, the root container of mappings. A provided
+implementation can be constructed through `MappingSet.create()`.
+
+Lorenz releases can be obtained through Maven Central:
+
+### Maven
+
+```xml
+<dependency>
+    <groupId>me.jamiemansfield</groupId>
+    <artifactId>lorenz</artifactId>
+    <version>0.3.0</version>
+</dependency>
+```
+
+### Gradle
+
+```groovy
+compile 'me.jamiemansfield:lorenz:0.3.0'
+```
+
+Lorenz snapshots are also available through my own Maven repository
+(repo.jamiemansfield.me), under the same group/artifact id.
+
+## License
 
-```gradle
-repositories {
-    mavenCentral()
-    maven {
-        name = 'jamiemansfield'
-        url = 'https://repo.jamiemansfield.me/'
-    }
-}
+Lorenz is licensed under the MIT License, this was chosen for its permissive nature -
+giving developers the freedom to do as they please with it, with no assurances from myself.
 
-dependencies {
-    compile 'me.jamiemansfield:lorenz:0.1.0-SNAPSHOT'
-}
 ```
+The MIT License (MIT)
+
+Copyright (c) Jamie Mansfield <https://www.jamierocks.uk/>
+Copyright (c) contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```
+
+[git-flow]: https://nvie.com/posts/a-successful-git-branching-model/

build.gradle

@@ -21,7 +21,7 @@ targetCompatibility = '1.8'
 
 group = 'me.jamiemansfield'
 archivesBaseName = project.name.toLowerCase()
-version = '0.3.0'
+version = '0.3.1'
 
 repositories {
     mavenCentral()

src/main/java/me/jamiemansfield/lorenz/impl/model/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of Lorenz, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) Jamie Mansfield <https://www.jamierocks.uk/>
+ * Copyright (c) contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+/**
+ * The default Lorenz model implementation.
+ */
+package me.jamiemansfield.lorenz.impl.model;

src/main/java/me/jamiemansfield/lorenz/impl/package-info.java

@@ -0,0 +1,34 @@
+/*
+ * This file is part of Lorenz, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) Jamie Mansfield <https://www.jamierocks.uk/>
+ * Copyright (c) contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+/**
+ * The default Lorenz implementation.
+ *
+ * <p>Lorenz is split into API and implementation to allow for callbacks and
+ * special-casing by external tools to be made easily. External tools can even
+ * replace single components, by using the
+ * {@link me.jamiemansfield.lorenz.MappingSetModelFactory}</p>.
+ */
+package me.jamiemansfield.lorenz.impl;

src/main/java/me/jamiemansfield/lorenz/io/reader/package-info.java

@@ -0,0 +1,36 @@
+/*
+ * This file is part of Lorenz, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) Jamie Mansfield <https://www.jamierocks.uk/>
+ * Copyright (c) contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+/**
+ * A collection of pre-built readers for common mapping formats.
+ *
+ * <p>There are readers for the following formats:</p>
+ * <ul>
+ *     <li>SRG</li>
+ *     <li>CSRG</li>
+ *     <li>TSRG</li>
+ * </ul>
+ */
+package me.jamiemansfield.lorenz.io.reader;

src/main/java/me/jamiemansfield/lorenz/io/writer/package-info.java

@@ -0,0 +1,36 @@
+/*
+ * This file is part of Lorenz, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) Jamie Mansfield <https://www.jamierocks.uk/>
+ * Copyright (c) contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+/**
+ * A collection of pre-built writers for common mapping formats.
+ *
+ * <p>There are writers for the following formats:</p>
+ * <ul>
+ *     <li>SRG</li>
+ *     <li>CSRG</li>
+ *     <li>TSRG</li>
+ * </ul>
+ */
+package me.jamiemansfield.lorenz.io.writer;

src/main/java/me/jamiemansfield/lorenz/model/jar/MethodDescriptor.java

@@ -33,7 +33,12 @@
 import java.util.Objects;
 
 /**
- * A representation of a method's descriptor.
+ * A model of a method descriptor, a text representation of a method's
+ * parameter type and return type.
+ *
+ * <p>The format is simply {@code "(ParamTypes...)ReturnType"}, for example
+ * given a method with two integer parameters and a {@link String} return
+ * type - the descriptor would be {@code "(II)Ljava/lang/String;"}.</p>
  *
  * @see <a href="https://docs.oracle.com/javase/specs/jvms/se8/html/jvms-4.html#jvms-4.3.3">Method Descriptors</a>
  *

src/main/java/me/jamiemansfield/lorenz/model/jar/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of Lorenz, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) Jamie Mansfield <https://www.jamierocks.uk/>
+ * Copyright (c) contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+/**
+ * A model for Java-specific types, often based on entries from the jvms manual.
+ */
+package me.jamiemansfield.lorenz.model.jar;

src/main/java/me/jamiemansfield/lorenz/model/jar/signature/FieldSignature.java

@@ -32,7 +32,7 @@
 import java.util.Optional;
 
 /**
- * A representation of the signature of a field.
+ * Represents a field within a class, by its name and descriptor.
  *
  * @author Jamie Mansfield
  * @since 0.2.0

src/main/java/me/jamiemansfield/lorenz/model/jar/signature/MemberSignature.java

@@ -46,7 +46,7 @@ public abstract class MemberSignature {
      *
      * @param name The name of the member
      */
-    public MemberSignature(final String name) {
+    protected MemberSignature(final String name) {
         this.name = name;
     }
 

src/main/java/me/jamiemansfield/lorenz/model/jar/signature/MethodSignature.java

@@ -31,7 +31,7 @@
 import java.util.Objects;
 
 /**
- * Represents a method within a class.
+ * Represents a method within a class, by its name and descriptor.
  *
  * @author Jamie Mansfield
  * @since 0.2.0

src/main/java/me/jamiemansfield/lorenz/model/jar/signature/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of Lorenz, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) Jamie Mansfield <https://www.jamierocks.uk/>
+ * Copyright (c) contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+/**
+ * A model for method and field signatures.
+ */
+package me.jamiemansfield.lorenz.model.jar.signature;

src/main/java/me/jamiemansfield/lorenz/model/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * This file is part of Lorenz, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) Jamie Mansfield <https://www.jamierocks.uk/>
+ * Copyright (c) contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+/**
+ * A model of the various mappings types that Lorenz represents.
+ */
+package me.jamiemansfield.lorenz.model;