Giter VIP home page Giter VIP logo

shapeless's Introduction

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.

Build Status Stories in Ready Gitter Maven Central Scala.js codecov.io

Projects which use shapeless

There is a wide variety of projects which use shapeless in one way or another ... see the incomplete list of projects for ideas and inspiration. If you are using shapeless and your project isn't listed yet, please add it.

Finding out more about the project

The feature overview for shapeless-2.0.0 provides a very incomplete introduction to shapeless. Additional information can be found in subsequent release notes. If you are upgrading from shapeless-2.0.0 you will find the migration guide useful. We're not satisfied with the current state of the documentation and would love help in improving it.

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.

Most discussion of shapeless and generic programming in Scala happens on the shapeless Gitter channel. There is also a mailing list and IRC channel, but these are largely dormant now that most activity has moved to Gitter. 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.

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, 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 branch are built using Travis CI and automatically published to the Sonatype OSS Snapshot repository.

Try shapeless with an Ammonite instant REPL

The quickest way to get to a REPL prompt with the latest version of shapeless on the class path is to run the provided "try shapeless" script. This downloads and installs coursier and uses it to fetch the Ammonite REPL and the latest version of shapeless and drops you immediately into a REPL session to play around with,

miles@frege:shapeless (master)$ scripts/try-shapeless.sh
Loading...
Welcome to the Ammonite Repl 0.6.2
(Scala 2.11.8 Java 1.8.0_102)
@ 1 :: "foo" :: true :: HNil
res0: Int :: String :: Boolean :: HNil = 1 :: foo :: true :: HNil
@

shapeless-2.3.2 with SBT

To include the Sonatype repositories in your SBT build you should add,

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

Builds are available for Scala 2.10.x, 2.11.x and for 2.12.0-M4. The main line of development for shapeless 2.3.2 is Scala 2.11.8 with Scala 2.10.x supported via the macro paradise compiler plugin.

scalaVersion := "2.11.8"

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

If you are using Scala 2.10.x, you should also add the macro paradise plugin to your build,

scalaVersion := "2.10.6"

libraryDependencies ++= Seq(
  "com.chuusai" %% "shapeless" % "2.3.2",
  compilerPlugin("org.scalamacros" % "paradise" % "2.1.0" cross CrossVersion.full)
)

shapeless and Typelevel Scala

Typelevel Scala provides a partial fix for SI-7046 which can present obstacles to using shapeless's Generic and LabelledGeneric for the sealed trait at the root of an ADT. If it appears that these two type classes are unable to find (all of) the subclasses of the root trait then please try using Typelevel Scala and see if it resolves the issue.

To use Typelevel Scala you should,

  • Update your project/build.properties to require SBT 0.13.13-M1 or later,

    sbt.version=0.13.13-M1

  • Add the following to your build.sbt immediately next to where you set scalaVersion,

    scalaOrganization := "org.typelevel"

If this does resolve the problem, please lend your support to the pull request being merged in Lightbend Scala.

shapeless-2.3.2 with Maven

shapeless is also available for projects using the Maven build tool via the following dependency,

<dependency>
  <groupId>com.chuusai</groupId>
  <artifactId>shapeless_2.11</artifactId>
  <version>2.3.2</version>
</dependency>

If you are using Scala 2.10.x, you should also add the macro paradise plugin to your build,

<dependency>
  <groupId>com.chuusai</groupId>
  <artifactId>shapeless_2.10</artifactId>
  <version>2.2.5</version>
</dependency>

<plugins>
  ...
  <plugin>
    ...
    <configuration>
      ...
      <compilerPlugins>
        <compilerPlugin>
          <groupId>org.scala-lang.plugins</groupId>
          <artifactId>macro-paradise_2.10</artifactId>
          <version>2.1.0</version>
        </compilerPlugin>
      </compilerPlugins>
      ...
    </configuration>
    ...
  </plugin>
  ...
</plugins>

Avoid SBT 0.13.6

Please be aware that SBT 0.13.6 has an issue related to its name hashing feature which when compiling with shapeless might cause SBT to loop indefinitely consuming all heap. If possible move to a more recent version of SBT. If you must use SBT 0.13.6 a workaround is to disable name hashing by adding,

incOptions := incOptions.value.withNameHashing(false)

to your settings.

Older releases

Please use a current release if possible. If unavoidable, you can find usage information for older releases on the shapeless wiki.

Building shapeless

shapeless is built with SBT 0.13.11 or later, and its master branch is built with Scala 2.11.8 by default but also cross-builds for 2.10.6 and 2.12.x.

Contributors

shapeless's People

Contributors

alexarchambault avatar aloiscochard avatar aryairani avatar atry avatar beezee avatar bmjames avatar ceedubs avatar clhodapp avatar dwijnand avatar everson avatar fommil avatar fthomas avatar guersam avatar jedesah avatar kevinwright avatar larsrh avatar m50d avatar mandubian avatar milessabin avatar mpilquist avatar netvl avatar olivierblanvillain avatar reactormonk avatar s11001001 avatar stacycurl avatar tomasmikula avatar travisbrown avatar vil1 avatar vpavkin avatar xoltar avatar

Watchers

avatar avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.