shapeless: generic programming for Scala

shapeless is a type class and dependent type based generic programming library for Scala. It had its origins in several talks by Miles Sabin (@milessabin), given over the course of 2011, on implementing scrap your boilerplate and higher rank polymorphism in Scala. Since then it has evolved from being a resolutely experimental project into library which, while still testing the limits of what's possible in Scala, is being used widely in production systems wherever there are arities to be abstracted over and boilerplate to be scrapped.

Finding out more about the project

A full feature overview of shapeless-2.1.0 is in preparation. In the meantime, please refer to the release notes and the feature overview for shapeless-2.0.0 which can be found here. If you are upgrading from shapeless-2.0.0 you will find the migration guide useful.

shapeless is part of the Typelevel family of projects. It is an Open Source project under the Apache License v2, hosted on github. Binary artefacts are published to the Sonatype OSS Repository Hosting service and synced to Maven Central.

Discussion of shapeless and generic programming in Scala in general happens on the Typelevel mailing list. You will also find many of the main shapeless contributors in its Gitter channel and on IRC in the #shapeless channel on freenode. Questions about shapeless are often asked and answered under the shapeless tag on StackOverflow. Some articles on the implementation techniques can be found on Miles's blog, and Olivera, Moors and Odersky, Type Classes as Object and Implicits is useful background material.

Support for Scala 2.9.x is still available via the shapeless-1.2.4 release (feature overview here). It isn't straightforward to bring the latest shapeless features to Scala versions which don't support implicit macros, and this release should be treated as a stopgap until you are able to move your project to Scala 2.11. It might, however, be feasible to backport some of the updates via a compiler plugin for Scala 2.9.x, and anyone interested in contributing or sponsoring such work should get in touch.

Participation

The shapeless project supports the Typelevel code of conduct and wants all of its channels (mailing list, Gitter, IRC, github, etc.) to be welcoming environments for everyone.

Whilst shapeless is a somewhat "advanced" Scala library, it is a lot more approachable than many people think. Contributors are usually available to field questions, give advice and discuss ideas on the Gitter channel, on #shapeless and the mailing list, and for people wanting to take their first steps at contributing we have a selection of open issues flagged up as being good candidates to take on. No contribution is too small, and guidance is always available.

Using shapeless

Binary release artefacts are published to the Sonatype OSS Repository Hosting service and synced to Maven Central. Snapshots of the master and scala-2.10.x branches are built using Travis CI and automatically published to the Sonatype OSS Snapshot repository. To include the Sonatype repositories in your SBT build you should add,

resolvers ++= Seq(
  Resolver.sonatypeRepo("releases"),
  Resolver.sonatypeRepo("snapshots")
)

Please be aware that SBT 0.13.6 has an issue related to its new name hashing feature which when compiling with shapeless might cause SBT to loop indefinitely consuming all heap. Workarounds are to move to an earlier (0.13.5) or later (0.13.7) SBT version or disable name hashing by adding,

incOptions := incOptions.value.withNameHashing(false)

to your settings.

shapeless-2.2.0-RC4

Builds are available for Scala 2.11.x and for Scala 2.10.x. The main line of development for shapeless 2.2.0 is Scala 2.11.6 with Scala 2.10.x supported via the macro paradise compiler plugin.

scalaVersion := "2.11.6"

libraryDependencies ++= Seq(
  "com.chuusai" %% "shapeless" % "2.2.0-RC4"
)

If you are using Scala 2.10.x, note that unlike earlier versions, it is no longer necessary to provide an explicit Scala version suffix for your shapeless dependency. You must however ensure that you are using Scala version 2.10.2 or greater, with Scala 2.10.5 (or switching to 2.11.x) strongly recommended. You should also add the macro paradise plugin to your build,

scalaVersion := "2.10.5"

libraryDependencies ++= Seq(
  "com.chuusai" %% "shapeless" % "2.2.0-RC4",
  compilerPlugin("org.scalamacros" % "paradise" % "2.0.1" cross CrossVersion.full)
)

shapeless-2.1.0

Builds are available for Scala 2.11.x and for Scala 2.10.4. The main line of development for shapeless 2.1.0 is Scala 2.11.6 with Scala 2.10.x supported via the macro paradise compiler plugin.

scalaVersion := "2.11.6"

libraryDependencies ++= Seq(
  "com.chuusai" %% "shapeless" % "2.1.0"
)

Note that for Scala 2.10.4 you must provide an explicit Scala version suffix to your shapeless dependency, and it is recommanded to add the macro paradise plugin to your build, for some macros provided by shapeless to work smoothly,

scalaVersion := "2.10.4"

libraryDependencies ++= Seq(
  "com.chuusai" % "shapeless_2.10.4" % "2.1.0",
  compilerPlugin("org.scalamacros" % "paradise_2.10.4" % "2.0.1")
)

shapeless-2.0.0

Builds are available for Scala 2.11.x and for Scala 2.10.4.

// For Scala 2.11.x
scalaVersion := "2.11.6"

libraryDependencies ++= Seq(
  "com.chuusai" %% "shapeless" % "2.0.0"
)

For Scala 2.10.x you must specify a Scala version of at least 2.10.2, and add either cross CrossVersion.full or provide an explicit Scala version suffix to your shapeless dependency,

// For Scala 2.10.x >= 2.10.2
scalaVersion := "2.10.4"

libraryDependencies ++= Seq(
  "com.chuusai" % "shapeless_2.10.4" % "2.0.0"
  // "com.chuusai" % "shapeless" % "2.0.0" cross CrossVersion.full  // Alternatively ...
)

Note that Scala 2.10.x releases are compatible with each other starting from 2.10.2, so a mismatch in minor versions above would be fine.

If your project is built with Scala 2.10.4 and Scala 2.11.0 and later, then you will need to add the following,

val shapeless = Def setting (
    CrossVersion partialVersion scalaVersion.value match {
    case Some((2, scalaMajor)) if scalaMajor >= 11 => 
      "com.chuusai" %% "shapeless" % "2.0.0"
    case Some((2, 10)) => 
      "com.chuusai" %  "shapeless" % "2.0.0" cross CrossVersion.full
  }
)

libraryDependencies ++= Seq(
  shapeless.value
)

This is needed because the shapeless binaries for Scala 2.10 includes the Scala bug fix digit. There specific binaries for 2.10.2, 2.10.3 and 2.10.4, while in the Scala 2.11 series the bug fix digit is omitted.

"com.chuusai" %  "shapeless_2.10.2" % "2.0.0"

"com.chuusai" %  "shapeless_2.10.3" % "2.0.0"

"com.chuusai" %  "shapeless_2.10.4" % "2.0.0"

"com.chuusai" %  "shapeless_2.11" % "2.0.0"

shapeless-1.2.4

Builds are available for Scala 2.9, 2.10 and 2.11. If you are working with Scala 2.10.2 or later you should use shapeless-2.1.0 instead.

If your project is built with Scala 2.9.3 or earlier, then you will need to specify the -Ydependent-method-types compiler flag,

scalaVersion := "2.9.3"

scalacOptions += "-Ydependent-method-types"

libraryDependencies ++= Seq(
  "com.chuusai" %% "shapeless" % "1.2.4"
)

This option isn't necessary or supported in Scala 2.10 and later, so you should omit it if you are building with Scala 2.10.2 or later,

scalaVersion := "2.10.4"

libraryDependencies ++= Seq(
  "com.chuusai" %% "shapeless" % "1.2.4"
)

If you want to be able to support building relative to both 2.9.3 and 2.10 and later then you should use the 2.10.4 configuration above and add the following,

scalacOptions <++= scalaVersion map { version =>
  val Some((major, minor)) = CrossVersion.partialVersion(version)
  if (major < 2 || (major == 2 && minor < 10)) 
    Seq("-Ydependent-method-types")
  else Nil
}

which will set the -Ydependent-method-types compiler flag conditionally on the actual Scala version in use.

Building shapeless

shapeless is built with 0.13.7 or later. SBT 0.13.6 has an issue related to its new name hashing feature which when compiling shapeless causes SBT to loop indefinitely consuming all heap. Workarounds are to move to an earlier or later SBT version or disable name hashing by adding,

incOptions := incOptions.value.withNameHashing(false)

to your settings.

The master branch of shapeless is built with Scala 2.11.6 by default. To build with Scala 2.10.x you should check out the scala-2.10.x branch. As a general rule all new features and bugfixes are made against master and Scala 2.11.6 and merged into the scala-2.10.x branch with only the minimal changes needed for forwards compatibility.

Contributors

• Alexandre Archambault [email protected] @alxarchambault
• Alois Cochard [email protected] @aloiscochard
• Andrew Brett [email protected] @Ephemerix
• Ben Hutchison [email protected] @ben_hutchison
• Ben James [email protected] @bmjames
• Brian McKenna [email protected] @puffnfresh
• Chris Hodapp [email protected] @clhodapp
• Cody Allen [email protected] @fourierstrick
• Dale Wijnand [email protected] @dwijnand
• Dario Rexin [email protected] @evonox
• Eugene Burmako [email protected] @xeno_by
• Filipe Nepomuceno [email protected]
• George Leontiev [email protected] @folone
• Howard Branch [email protected] @purestgreen
• Huw Giddens [email protected]
• Jason Zaugg [email protected] @retronym
• Jean-Remi Desjardins [email protected] @jrdesjardins
• Johannes Rudolph [email protected] @virtualvoid
• Johnny Everson [email protected] @johnny_everson
• Joni Freeman [email protected] @jonifreeman
• Julien Tournay [email protected] @skaalf
• Jules Gosnell [email protected]
• Kevin Wright [email protected] @thecoda
• Lars Hupel [email protected] @larsr_h
• Mario Pastorelli [email protected] @mapastr
• Mathias Doenitz [email protected] @sirthias
• Michael Donaghy [email protected]
• Michael Pilquist [email protected] @mpilquist
• Miles Sabin [email protected] @milessabin
• Nikolas Evangelopoulos [email protected]
• Oleg Aleshko [email protected] @OlegYch
• Owein Reese [email protected] @OweinReese
• Paolo G. Giarrusso [email protected] @blaisorblade
• Pascal Voitot [email protected] @mandubian
• Renato Cavalcanti [email protected] @renatocaval
• Sam Halliday [email protected] @fommil
• Sarah Gerweck [email protected] @SGerweck
• Simon Hafner [email protected] @reactormonk
• Stacy Curl [email protected] @stacycurl
• Stephen Compall [email protected] @S11001001
• Tom Switzer [email protected] @tixxit
• Travis Brown [email protected] @travisbrown
• Vladimir Matveev [email protected] @netvlm