<commit_before>ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

= GhostWriter
<NAME>
:toc: macro
:version: 0.5.0

image:https://travis-ci.org/GoodGrind/ghostwriter.svg?branch=master["Build Status", link="https://travis-ci.org/GoodGrind/ghostwriter"]
image:https://maven-badges.herokuapp.com/maven-central/io.ghostwriter/ghostwriter-jdk-v8/badge.svg["Maven Central", link="http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.ghostwriter%22%20v%3A{version}"]
image:https://img.shields.io/badge/license-LGPLv2.1-blue.svg?style=flat["License", link="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html"]
image:https://api.codacy.com/project/badge/Grade/c4506e0b2280433490ec6c23cbb36c0f["Codacy code quality", link="https://www.codacy.com/app/snorbi07/ghostwriter-instrumenter?utm_source=github.com&utm_medium=referral&utm_content=GoodGrind/ghostwriter-instrumenter&utm_campaign=Badge_Grade"]
image:https://badges.gitter.im/Join%20Chat.svg["Gitter",link="https://gitter.im/snorbi07/GhostWriter?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"]


toc::[]


= What is GhostWriter?
GhostWriter helps people to catch, pinpoint and fix bugs quickly without writing any lines of extra code or deploying additional services

== How does it work?
GhostWriter takes a different approach of debugging and bug tracking by writing code instead of you at the creation of the application. When you launch the GhostWriter-augmented final product it catches unexpected errors, tracks variable states and method calls so you or your team can see what's the problem but more importantly, _why_ is it happening. You can attach any application or tool to the interface of the application and receive the messages that GhostWriter creates.

== Can you give me a more technical description?
GhostWriter is a non-invasive solution for adding common application event handler stubs to your Java code.
Essentially what you would end up writing by hand if you would like to have proper tracking of your application workflow.
After the instrumentation you will have the chance to provide custom handlers for all:

* method calls, including entering, return and exiting events
* state changes of your application, such as value assignment and other side-effectful operations
* unexpected errors

A "pseudo" before-after setup with GhostWriter (more or less readable decompiled code):

image::media/beforeAfter.png[ghostwriter-tracer]

NOTE: You always see and work with your original source. The above picture is just an illustration.



= Installation

Just add the necessary dependencies to your application and GhostWriter will take care of instrumenting the https://github.com/GoodGrind/ghostwriter-api[`ghostwriter-api`] calls.

IMPORTANT: You have to choose the dependency that is inline with your Java compiler (JDK) version.

For Java 7 this means `ghostwriter-jdk-v7`, for Java 8 it is `ghostwriter-jdk-v8`.

GhostWriter is tested and verified with both Oracle JDK and Open JDK versions.

=== Maven

Add another `dependency` entry to the `dependencies` section.
This means that for JDK8, you will have the following entry in you `pom.xml` file.

[source, subs="verbatim,attributes"]
----
<dependency>
    <groupId>io.ghostwriter</groupId>
    <artifactId>ghostwriter-jdk-v8</artifactId>
    <version>{version}</version>
    <scope>compile</scope>
</dependency>
----

Your are done! Time to recompile your application!

=== Gradle ===

The provided snippets work with Gradle 3+.
The dependencies of GhostWriter are fetched from Maven Central. So you have to add it to your list of repositories if its not there yet.
For a project that uses JDK8, you'll will have to add the following lines to your `build.gradle` file.

[source, subs="verbatim,attributes"]
----
repositories {
    mavenCentral()
}

dependencies {
    compileOnly "io.ghostwriter:ghostwriter-jdk-v8:{version}"
}
----

Your are done! Time to recompile your application!


==== For older Java versions (Java 7)

If you are still using an older Java/JDK version such as Java 7, you'll need a different set of dependencies.

*Maven*

[source, subs="verbatim,attributes"]
----
<dependency>
    <groupId>io.ghostwriter</groupId>
    <artifactId>ghostwriter-jdk-v7</artifactId> // <1>
    <version>{version}</version>
    <scope>compile</scope>
</dependency>
----
<1> Note the use of `ghostwriter-jdk-v7`.

*Gradle*

[source, subs="verbatim,attributes"]
----
repositories {
    mavenCentral()
}

dependencies {
    compileOnly "io.ghostwriter:ghostwriter-jdk-v7:{version}" // <1>
}
----
<1> Note the use of `ghostwriter-jdk-v7`


Now recompile your application and if all goes well, you should now have support for plugging in runtime implementations.


==== Explicitly specifying the compile time annotation
This steps should only be done in case you manually set annotation processors (for whatever reason).
By default the compiler should pick up the GhostWriter annotation processor based on the service loader contract.

*Maven*

To have it explicitly set, you'll need to add the following lines to your `pom.xml`.

----
<build>
     <plugins>
         <plugin>
             <groupId>org.apache.maven.plugins</groupId>
             <artifactId>maven-compiler-plugin</artifactId>
             <version>3.6.0</version>
             <executions>
                 <execution>
                     <id>default-compile</id>
                     <phase>compile</phase>
                     <goals>
                         <goal>compile</goal>
                     </goals><commit_msg>Fix Gradle build dependency declaration in README<commit_after>ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

= GhostWriter
<NAME>
:toc: macro
:version: 0.5.0

image:https://travis-ci.org/GoodGrind/ghostwriter.svg?branch=master["Build Status", link="https://travis-ci.org/GoodGrind/ghostwriter"]
image:https://maven-badges.herokuapp.com/maven-central/io.ghostwriter/ghostwriter-jdk-v8/badge.svg["Maven Central", link="http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.ghostwriter%22%20v%3A{version}"]
image:https://img.shields.io/badge/license-LGPLv2.1-blue.svg?style=flat["License", link="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html"]
image:https://api.codacy.com/project/badge/Grade/c4506e0b2280433490ec6c23cbb36c0f["Codacy code quality", link="https://www.codacy.com/app/snorbi07/ghostwriter-instrumenter?utm_source=github.com&utm_medium=referral&utm_content=GoodGrind/ghostwriter-instrumenter&utm_campaign=Badge_Grade"]
image:https://badges.gitter.im/Join%20Chat.svg["Gitter",link="https://gitter.im/snorbi07/GhostWriter?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"]


toc::[]


= What is GhostWriter?
GhostWriter helps people to catch, pinpoint and fix bugs quickly without writing any lines of extra code or deploying additional services

== How does it work?
GhostWriter takes a different approach of debugging and bug tracking by writing code instead of you at the creation of the application. When you launch the GhostWriter-augmented final product it catches unexpected errors, tracks variable states and method calls so you or your team can see what's the problem but more importantly, _why_ is it happening. You can attach any application or tool to the interface of the application and receive the messages that GhostWriter creates.

== Can you give me a more technical description?
GhostWriter is a non-invasive solution for adding common application event handler stubs to your Java code.
Essentially what you would end up writing by hand if you would like to have proper tracking of your application workflow.
After the instrumentation you will have the chance to provide custom handlers for all:

* method calls, including entering, return and exiting events
* state changes of your application, such as value assignment and other side-effectful operations
* unexpected errors

A "pseudo" before-after setup with GhostWriter (more or less readable decompiled code):

image::media/beforeAfter.png[ghostwriter-tracer]

NOTE: You always see and work with your original source. The above picture is just an illustration.



= Installation

Just add the necessary dependencies to your application and GhostWriter will take care of instrumenting the https://github.com/GoodGrind/ghostwriter-api[`ghostwriter-api`] calls.

IMPORTANT: You have to choose the dependency that is inline with your Java compiler (JDK) version.

For Java 7 this means `ghostwriter-jdk-v7`, for Java 8 it is `ghostwriter-jdk-v8`.

GhostWriter is tested and verified with both Oracle JDK and Open JDK versions.

=== Maven

Add another `dependency` entry to the `dependencies` section.
This means that for JDK8, you will have the following entry in you `pom.xml` file.

[source, subs="verbatim,attributes"]
----
<dependency>
    <groupId>io.ghostwriter</groupId>
    <artifactId>ghostwriter-jdk-v8</artifactId>
    <version>{version}</version>
    <scope>compile</scope>
</dependency>
----

Your are done! Time to recompile your application!

=== Gradle ===

The provided snippets work with Gradle 3+.
The dependencies of GhostWriter are fetched from Maven Central. So you have to add it to your list of repositories if its not there yet.
For a project that uses JDK8, you'll will have to add the following lines to your `build.gradle` file.

[source, subs="verbatim,attributes"]
----
repositories {
    mavenCentral()
}

dependencies {
    compile "io.ghostwriter:ghostwriter-jdk-v8:{version}"
}
----

Your are done! Time to recompile your application!


==== For older Java versions (Java 7)

If you are still using an older Java/JDK version such as Java 7, you'll need a different set of dependencies.

*Maven*

[source, subs="verbatim,attributes"]
----
<dependency>
    <groupId>io.ghostwriter</groupId>
    <artifactId>ghostwriter-jdk-v7</artifactId> // <1>
    <version>{version}</version>
    <scope>compile</scope>
</dependency>
----
<1> Note the use of `ghostwriter-jdk-v7`.

*Gradle*

[source, subs="verbatim,attributes"]
----
repositories {
    mavenCentral()
}

dependencies {
    compile "io.ghostwriter:ghostwriter-jdk-v7:{version}" // <1>
}
----
<1> Note the use of `ghostwriter-jdk-v7`


Now recompile your application and if all goes well, you should now have support for plugging in runtime implementations.


==== Explicitly specifying the compile time annotation
This steps should only be done in case you manually set annotation processors (for whatever reason).
By default the compiler should pick up the GhostWriter annotation processor based on the service loader contract.

*Maven*

To have it explicitly set, you'll need to add the following lines to your `pom.xml`.

----
<build>
     <plugins>
         <plugin>
             <groupId>org.apache.maven.plugins</groupId>
             <artifactId>maven-compiler-plugin</artifactId>
             <version>3.6.0</version>
             <executions>
                 <execution>
                     <id>default-compile</id>
                     <phase>compile</phase>
                     <goals>
                         <goal>compile</goal>
                     </goals>
{'fraction_non_alphanumeric': 0.10303668597507461, 'fraction_numerical': 0.012111637704054766, 'mean_word_length': 4.205573321151211, 'pattern_counts': {'":': 0, '<': 91, '<?xml version=': 0, '>': 91, 'https://': 18, 'lorem ipsum': 0, 'www.': 4, 'xml': 4}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2580781', 'n_tokens_mistral': 3540, 'n_tokens_neox': 3293, 'n_words': 1121}