Skip to content

Latest commit

 

History

History
157 lines (115 loc) · 5.08 KB

README.md

File metadata and controls

157 lines (115 loc) · 5.08 KB
Raw

Paiges

Overview

Paiges is an implementation of Wadler's "A Prettier Printer".

The library is useful any time you find yourself generating text or source code where you'd like to control the length of lines (e.g. paragraph wrapping). See the documentation site for some examples.

The name Paiges is a reference to the Paige compositor and the fact that it helps you layout pages.

CI codecov.io Latest version

Quick Start

Paiges supports Scala 2.11, 2.12, 2.13, and 3. It supports JVM, Scala.js, and Scala Native platforms.

To use Paiges in your own project, you can include this snippet in your build.sbt file:

// use this snippet for the JVM
libraryDependencies += "org.typelevel" %% "paiges-core" % "0.4.2"

// use this snippet for JS, Native, or cross-building
libraryDependencies += "org.typelevel" %%% "paiges-core" % "0.4.2"

Paiges also provides types to work with Cats via the paiges-cats module:

// use this snippet for the JVM
libraryDependencies += "org.typelevel" %% "paiges-cats" % "0.4.2"

// use this snippet for JS, Native, or cross-building
libraryDependencies += "org.typelevel" %%% "paiges-cats" % "0.4.2"

Description

This code is a direct port of the code in section 7 of this paper, with an attempt to be idiomatic in scala while preserving the original code's properties, including laziness.

This algorithm is optimal and bounded. From the paper:

Say that a pretty printing algorithm is optimal if it chooses line breaks so as to avoid overflow whenever possible; say that it is bounded if it can make this choice after looking at no more than the next w characters, where w is the line width. Hughes notes that there is no algorithm to choose line breaks for his combinators that is optimal and bounded, while the layout algorithm presented here has both properties.

Some selling points of this code:

  1. Lazy, O(1) concatenation
  2. Competitive performance (e.g. 3-5x slower than mkString)
  3. Elegantly handle indentation
  4. Flexible line-wrapping strategies
  5. Functional cred ;)

Examples

Here's an example of using Paiges to generate the source code for a case class:

import org.typelevel.paiges._

/**
 * Produces a case class given a name and zero-or-more
 * field/type pairs.
 */
def mkCaseClass(name: String, fields: (String, String)*): Doc = {
  val prefix = Doc.text("case class ") + Doc.text(name) + Doc.char('(')
  val suffix = Doc.char(')')
  val types = fields.map { case (k, v) =>
    Doc.text(k) + Doc.char(':') + Doc.space + Doc.text(v)
  }
  val body = Doc.intercalate(Doc.char(',') + Doc.line, types)
  body.tightBracketBy(prefix, suffix)
}

val c = mkCaseClass(
  "Dog", "name" -> "String", "breed" -> "String",
  "height" -> "Int", "weight" -> "Int")

c.render(80)
// case class Dog(name: String, breed: String, height: Int, weight: Int)

c.render(60)
// case class Dog(
//   name: String,
//   breed: String,
//   height: Int,
//   weight: Int
// )

For more examples, see the tutorial.

Benchmarks

The Paiges benchmarks are written against JMH. To run them, you'll want to use a command like this from SBT:

benchmark/jmh:run -wi 5 -i 5 -f1 -t1 bench.PaigesBenchmark

By default the values reported are ops/ms (operations per millisecond), so higher numbers are better.

The parameters used here are:

  • -wi: the number of times to run during warmup
  • -i: the number of times to benchmark
  • -f: the number of processes to use during benchmarking
  • -t: the number of threads to use during benchmarking

In other words, the example command-line runs one thread in one process, with a relatively small number of warmups + runs (so that it will finish relatively quickly).

Organization

The current Paiges maintainers are:

People are expected to follow the Typelevel Code of Conduct when discussing Paiges on the Github page or other official venues.

Concerns or issues can be sent to any of Paiges' maintainers, or to the Typelevel organization.

License

Paiges is licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.