<commit_before>= s_mach.codetools: Macro, codegen and code utility library
<NAME> <<EMAIL>>
v1,27-Dec-2014
:blogpost-status: unpublished
:blogpost-categories: s_mach, scala

image:https://travis-ci.org/S-Mach/s_mach.codetools.svg[Build Status, link="https://travis-ci.org/S-Mach/s_mach.codetools"]  image:https://coveralls.io/repos/S-Mach/s_mach.codetools/badge.png?branch=master[Test Coverage,link="https://coveralls.io/r/S-Mach/s_mach.codetools"] https://github.com/S-Mach/s_mach.codetools[Code] http://s-mach.github.io/s_mach.codetools/#s_mach.codetools.package[Scaladoc]

+s_mach.codetools+ is an open-source Scala macro, codegen and code utility
library.

+s_mach.codetools+ currently provides:

* +Result[A]+: a better +scala.util.Try+ that allows accumulating errors,
warnings and other issues in addition to storing failure or success. Returned
by most +BlackboxHelper+ methods.
* +BlackboxHelper+: a wrapper trait that provides utility types and methods to
assist in macro generation, specifically for generating type-class.
implementations for product types
** +BlackboxHelper.ProductType+: a case class for storing the matching
apply/unapply methods and field names of a product type. Works for all case
classes, tuple types and any other type whose companion object contains a
matching apply/unapply method pair (See +ProductType+ below for
details). Has utility methods for type-class implementation generation.
** +BlackboxHlper.calcProductType+: method to attempt to compute a +ProductType+
for a given type.
* +ReflectPrint+: a demonstration type-class which can create the Scala code
necessary for recreating an instance with the same value (See
+reflectPrint.printApply+).
* +ReflectPrintMacroBuilderImpl+: a reference implementation of a type-class
blackbox macro generator that uses +BlackboxHelper+. The macro implementation
can generate a +ReflectPrint+ implementation for any product type.
* +ReflectPrintTest+: tests for the generated +ReflectPrint+ for various common
ADT patterns (See +testdata+) in lieu of direct testing of +BlackboxHelper+
since there is currently no blackbox.Context mock available.

== Include in SBT
1. Add to +build.sbt+
+
[source,sbt,numbered]
----
libraryDependencies += "net.s_mach" %% "codetools" % "1.0.3"
----
NOTE: +s_mach.codetools+ is currently only compiled for Scala 2.11 (though
2.10.4 support can be added if there is interest)

== Versioning
+s_mach.codetools+ uses semantic versioning (http://semver.org/).
+s_mach.codetools+ does not use the package private modifier. Instead, all code
files outside of the +s_mach.codetools.impl+ package form the public interface
and are governed by the rules of semantic versioning. Code files inside the
+s_mach.codetools.impl+ package may be used by downstream applications and
libraries. However, no guarantees are made as to the stability or interface of
code in the +s_mach.codetools.impl+ package between versions.

== In Detail: +Product Type+
A +product type+ is any type that can be expressed as sequence of fields whose
types are either data types (e.g. Int, String, etc) or other product types.
Product types are
http://en.wikipedia.org/wiki/Algebraic_data_type[algebraic data types] that can
be decomposed into an ordered sequence of fields. Each field consists of an
index within the sequence, a field name and a field type.

In +s_mach.codetools+, product types are computed by finding the first
unapply/apply method pair in the type's companion object with matching type
signatures. The type signature of an apply method is equal to the sequence of
the types of its arguments. Unapply methods may have one or two type signatures
based on their return type. First, the outer Option return type is discarded,
leaving only the inner type. If the inner type is a tuple type, then both the
tuple type and the list of tuple type parameters form possible type signatures
for the unapply method. Otherwise, if the inner type parameter is not a tuple type
then the type signature is equal to the single type parameter. Once an
apply/unapply match is made, the symbols of the apply method's argument list are
returned as  the product type fields for the type. For tuple types and case
classes, this will be the list of its fields.

.Example 1:
----
class A(...) { ... }
object A {
    def apply(i: Int, s: String) : A = ???
    def apply(i: Int, s: String, f: Float) : A = ???
    def unapply(a: A) : Option[(Int,String)] = ???
}
----
* The first apply method's type signature = +Int :: String :: Nil+
* The unapply method's type signature = +((Int,String) :: Nil) :: Int :: String :: Nil+
* Product type fields = +List(i:Int,s:String)+

.Example 2:
----
class B(...) { ... }
object B {<commit_msg>updated readme/docs [skip ci]<commit_after>= s_mach.codetools: Macro, codegen and code utility library
<NAME> <<EMAIL>>
v1,27-Dec-2014
:blogpost-status: unpublished
:blogpost-categories: s_mach, scala

image:https://travis-ci.org/S-Mach/s_mach.codetools.svg[Build Status, link="https://travis-ci.org/S-Mach/s_mach.codetools"]  image:https://coveralls.io/repos/S-Mach/s_mach.codetools/badge.png?branch=master[Test Coverage,link="https://coveralls.io/r/S-Mach/s_mach.codetools"] https://github.com/S-Mach/s_mach.codetools[Code] http://s-mach.github.io/s_mach.codetools/#s_mach.codetools.package[Scaladoc]

+s_mach.codetools+ is an open-source Scala macro, codegen and code utility
library.

+s_mach.codetools+ currently provides:

* +Result[A]+: a better +scala.util.Try+ that allows accumulating errors,
warnings and other issues in addition to storing failure or success. Returned
by most +BlackboxHelper+ methods.
* +BlackboxHelper+: a wrapper trait that provides utility types and methods to
assist in macro generation, specifically for generating type-class.
implementations for product types
** +BlackboxHelper.ProductType+: a case class for storing the matching
apply/unapply methods and field names of a product type. Works for all case
classes, tuple types and any other type whose companion object contains a
matching apply/unapply method pair (See +ProductType+ below for
details). Has utility methods for type-class implementation generation.
** +BlackboxHlper.calcProductType+: method to attempt to compute a +ProductType+
for a given type.
* +ReflectPrint+: a demonstration type-class which can create the Scala code
necessary for recreating an instance with the same value (See
+reflectPrint.printApply+).
* +ReflectPrintMacroBuilderImpl+: a reference implementation of a type-class
blackbox macro generator that uses +BlackboxHelper+. The macro implementation
can generate a +ReflectPrint+ implementation for any product type.
* +ReflectPrintTest+: tests for the generated +ReflectPrint+ for various common
ADT patterns (See +testdata+) in lieu of direct testing of +BlackboxHelper+
since there is currently no blackbox.Context mock available.

== Include in SBT
1. Add to +build.sbt+
+
[source,sbt,numbered]
----
libraryDependencies += "net.s_mach" %% "codetools" % "1.0.3"
----
NOTE: +s_mach.codetools+ is currently only compiled for Scala 2.11 (though
2.10.4 support can be added if there is interest)

== Versioning
+s_mach.codetools+ uses semantic versioning (http://semver.org/).
+s_mach.codetools+ does not use the package private modifier. Instead, all code
files outside of the +s_mach.codetools.impl+ package form the public interface
and are governed by the rules of semantic versioning. Code files inside the
+s_mach.codetools.impl+ package may be used by downstream applications and
libraries. However, no guarantees are made as to the stability or interface of
code in the +s_mach.codetools.impl+ package between versions.

== In Detail: +Product Type+
A +product type+ is any type that can be expressed as sequence of fields whose
types are either data types (e.g. Int, String, etc) or other product types.
Product types are
http://en.wikipedia.org/wiki/Algebraic_data_type[algebraic data types] that can
be decomposed into an ordered sequence of fields. Each field consists of an
index within the sequence, a field name and a field type.

In +s_mach.codetools+, product types are computed by finding the first
unapply/apply method pair in the type's companion object with matching type
signatures. The type signature of an apply method is equal to the sequence of
the types of its arguments. Unapply methods may have one or two type signatures
based on their return type. First, the outer Option return type is discarded,
leaving only the inner type. If the inner type is a tuple type, then both the
tuple type and the list of tuple type parameters form possible type signatures
for the unapply method. Otherwise, if the inner type parameter is not a tuple type
then the type signature is equal to the single type parameter. Once an
apply/unapply match is made, the symbols of the apply method's argument list are
returned as  the product type fields for the type. For tuple types and case
classes, this will be the list of its fields.

.Example 1:
----
class A(...) { ... }
object A {
    def apply(i: Int, s: String) : A = ???
    def apply(i: Int, s: String, f: Float) : A = ???
    def unapply(a: A) : Option[(Int,String)] = ???
}
----
* The first apply method's type signature = +Int :: String :: Nil+
* The unapply method's type signature = +((Int,String) :: Nil) ::: (Int :: String :: Nil)+
* Product type fields = +("i",Int) :: ("s",String) :: Nil+

.Example 2:
----
class B(...) { ... }
object B {
{'fraction_non_alphanumeric': 0.09268086007838153, 'fraction_numerical': 0.00423683931786887, 'mean_word_length': 4.664067186562687, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 10, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, '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': '2796203', 'n_tokens_mistral': 2813, 'n_tokens_neox': 2731, 'n_words': 1187}