Convert Figma logo to code with AI

milessabin logoshapeless

Generic programming for Scala

3,377
530
3,377
33
View on GitHub

Top Related Projects

pureconfig's avatar

pureconfig

1,477

A boilerplate-free library for loading configuration files

circe's avatar

circe

2,483

Yet another JSON library for Scala

Quick Overview

Shapeless is a type-level programming library for Scala that provides advanced generic programming capabilities. It enables developers to write highly reusable and type-safe code by leveraging features like heterogeneous lists, polymorphic function values, and generic representations of algebraic data types.

Pros

  • Powerful type-level programming capabilities
  • Enables writing highly generic and reusable code
  • Strong type safety and compile-time checks
  • Extensive ecosystem and integration with other Scala libraries

Cons

  • Steep learning curve for beginners
  • Can lead to increased compilation times
  • Complex error messages can be difficult to interpret
  • May introduce additional complexity to codebases if not used judiciously

Code Examples

  1. Creating and using heterogeneous lists (HLists):
import shapeless._

val hlist = 1 :: "hello" :: true :: HNil
val first: Int = hlist.head
val tail: String :: Boolean :: HNil = hlist.tail
  1. Generic programming with case classes:
import shapeless._

case class Person(name: String, age: Int)

val gen = Generic[Person]
val repr = gen.to(Person("Alice", 30)) // "Alice" :: 30 :: HNil
val person = gen.from("Bob" :: 25 :: HNil) // Person("Bob", 25)
  1. Polymorphic functions:
import shapeless._

object size extends Poly1 {
  implicit def caseInt = at[Int](x => 1)
  implicit def caseString = at[String](_.length)
  implicit def caseList[T] = at[List[T]](_.size)
}

val result = size(10) :: size("hello") :: size(List(1, 2, 3)) :: HNil
// 1 :: 5 :: 3 :: HNil

Getting Started

To use Shapeless in your Scala project, add the following dependency to your build.sbt file:

libraryDependencies += "com.chuusai" %% "shapeless" % "2.3.10"

Then, import the necessary Shapeless features in your Scala code:

import shapeless._

// Your Shapeless-powered code here

Start by exploring HLists, Generic derivation, and Poly functions to get familiar with Shapeless's core concepts.

Competitor Comparisons

pureconfig logo

pureconfig

1,477

A boilerplate-free library for loading configuration files

Pros of PureConfig

  • Focused specifically on configuration management, making it more user-friendly for this use case
  • Simpler API and easier learning curve for developers new to the library
  • Built-in support for common configuration formats like HOCON, properties files, and JSON

Cons of PureConfig

  • Less flexible and powerful for generic programming tasks outside of configuration
  • More limited in terms of advanced type-level programming capabilities
  • Smaller ecosystem and community compared to Shapeless

Code Comparison

PureConfig:

import pureconfig._
import pureconfig.generic.auto._

case class AppConfig(host: String, port: Int)
val config = ConfigSource.default.load[AppConfig]

Shapeless:

import shapeless._

val gen = Generic[AppConfig]
val repr = gen.to(AppConfig("localhost", 8080))
val config = gen.from(repr)

While both libraries can handle case class transformations, PureConfig is more focused on configuration loading, whereas Shapeless provides a more general-purpose approach to generic programming in Scala.

circe logo

circe

2,483

Yet another JSON library for Scala

Pros of circe

  • Focused specifically on JSON encoding/decoding, making it more user-friendly for this common task
  • Provides automatic derivation of encoders and decoders for case classes and sealed traits
  • Offers better performance for JSON processing compared to more general-purpose libraries

Cons of circe

  • Limited to JSON processing, whereas Shapeless is a more versatile generic programming library
  • May have a steeper learning curve for users unfamiliar with type-level programming concepts
  • Less flexibility for advanced type manipulations compared to Shapeless

Code Comparison

circe example:

import io.circe._, io.circe.generic.auto._, io.circe.parser._, io.circe.syntax._

case class Person(name: String, age: Int)
val json = Person("Alice", 30).asJson
val decodedPerson = json.as[Person]

Shapeless example:

import shapeless._

case class Person(name: String, age: Int)
val generic = Generic[Person]
val repr = generic.to(Person("Alice", 30))
val person = generic.from(repr)

Both libraries leverage compile-time code generation, but circe focuses on JSON processing while Shapeless provides more general-purpose generic programming capabilities. circe is easier to use for JSON tasks, while Shapeless offers greater flexibility for complex type-level operations.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

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 a 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.

Discord Gitter Maven Central Scala.js

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. You can find an excellent guide to Shapeless here: The Type Astronaut's Guide to Shapeless.

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 #shapless channel of the Typelevel Discord. There is also a mailing list and Gitter, but these are largely dormant now that most activity has moved to Discord. 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 #shapeless Discord 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 main branch are built using GitHub actions 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, which has no dependencies other than an installed JDK. This script downloads and installs coursier and uses it to fetch the Ammonite REPL and the latest version of shapeless. It then drops you immediately into a REPL session,

% curl -s https://raw.githubusercontent.com/milessabin/shapeless/main/scripts/try-shapeless.sh | bash
Loading...
Compiling (synthetic)/ammonite/predef/interpBridge.sc
Compiling (synthetic)/ammonite/predef/replBridge.sc
Compiling (synthetic)/ammonite/predef/DefaultPredef.sc
Compiling /home/miles/projects/shapeless/(console)
Welcome to the Ammonite Repl 1.6.8
(Scala 2.13.1 Java 1.8.0_212)
If you like Ammonite, please support our development at www.patreon.com/lihaoyi
@ 23 :: "foo" :: true :: HNil 
res0: Int :: String :: Boolean :: HNil = 23 :: "foo" :: true :: HNil

@ Bye!
%

shapeless-2.3.3 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.11.x, 2.12.x and 2.13.x. The main line of development for shapeless 2.3.3 is Scala 2.13.2.

scalaVersion := "2.13.5"

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

For using snapshots of Shapeless you should add,

scalaVersion := "2.13.5"

libraryDependencies ++= Seq(
  "com.chuusai" %% "shapeless" % "2.4.0-SNAPSHOT"
)

shapeless-2.3.3 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.13</artifactId>
  <version>2.3.3</version>
</dependency>

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 1.3.10 or later, and its main branch is built with Scala 2.13.2 by default but also cross-builds for 2.11.12 and 2.12.12.

Contributors