giacomocavalieri/glam

✨ A package to help you easily pretty print structured data

✨ A package to help you easily pretty print structured data

⚙️ This package works with both the Erlang and Javascript target

Installation

To add this package to your Gleam project:

gleam add glam

Pretty printing

When working with structured data (like JSON, XML, lists, ASTs, ...) it can be useful to print it in a nice and tidy way. Of course, one could go the quick and dirty way and just string.inspect the data structure and call it a day. However, the result would hardly be readable for complex data structures.

On the other hand, handwriting a pretty printing function can be quite difficult (I sure have spent my fair share of time writing those) and error-prone: there are a lot of moving pieces to juggle and it's easy for bugs to sneak in.

A pretty printing package like Glam provides some basic building blocks to describe the structure of your data and takes care of the heavy lifting of actually finding the best layout to format the data, gracefully handling line limits and indentation.

Getting started

If you want to get started with Glam, a great starting point is the learning materials page! There you'll find a lot of step-by-step tutorials that will guide you through some awesome pretty printers and get you up and running with Glam.

By the end of the tutorials you'll know most of the package's API and you'll have implemented pretty printers for lists, JSON and error messages:

pretty_list(["Gleam", "is", "fun!"])
|> doc.to_string(10) // Fit the list on lines of width 10

// [
//   "Gleam",
//   "is",   
//   "fun!",   
// ]

You can also have a look at the examples folder in the GitHub repo, there you'll also find a JSON pretty printer.

Contributing

If you think there's any way to improve this package, or if you spot a bug don't be afraid to open PRs, issues or requests of any kind! Any contribution is welcome 💜

glam's Issues

Port tests from Elixir's `Inspect.Algebra`

Since this package is so similar to Elixir's Inspect.Algebra I could add more tests taking as a reference the ones they use. The API is quite similar so it wouldn't be too hard to port those

Why is this a good first issue and how can you help?

Adding this shouldn't be too hard if you can read a bit of Elixir.
Basically, what one would need to do is:

• look at Inspect.Algebra's tests
• rewrite each test in Gleam
  • the tests can be added to the glam/doc_test module
  • most likely you'll need to have a look at Inspect.Algebra's documentation
  • mapping each of Inspect.Algebra's functions into the corresponding glam one. The API is quite similar but things may have different names

Add zero width string support

I should add support for zero width strings, that is strings that are simply appended to the text without increasing the width of the string. This would be really useful to properly handle ansi color codes

Document Int argument of `doc.to_string`

Hello! Thanks for this library. It was super nice to use on stream.

The second argument of to_string was a bit unclear, and it isn't documented as far as I can see. Could we add some please? 🙏

Thanks,
Louis

Add `doc.nest_docs`

@bcpeinhardt pointed out that it may be handy to have a doc.nest_docs that can take a list of documents and concat them together adding a given nesting. This would be analogous to doc.append/doc.append_docs

Why is this a good first issue and how can you help?

Closing this issue would require

• implementing a doc.nest_docs function
• adding relevant tests to check that it behaves like a normal nest

I think the function should have the following signature:

pub fn nest_docs(docs: List(Document), by nesting: Int) -> Document { ... }

And the implementation could be as simple as concatenating the docs and wrapping everything with a doc.nest. There should be some tests to check that it works properly, though :)

Add a cute logo

I'm weak for packages with logos like Nakai and I'd love to add one here as well

Also if I ever do this I should remember to use it for the social preview

Add a `doc.debug` function

It would be lovely to add a debug function that turns a document into a pretty document showing its structure with a nice format to help debugging complex documents.

Informally:

doc.group(•)         ~> [•]
doc.concat([•,…,•])  ~> • . … . •
doc.nest(•, by: n)   ~> ⟨•⟩ⁿ
doc.break(•, •)      ~> {•, •}
doc.flex_break(•, •) ~> {•, •}
doc.from_string(•)   ~> "•"
doc.force_break(•)   ~> force(•)
doc.lines(n)         ~> lfⁿ

An example with a concrete document:

[
  doc.from_string("foo"),
  doc.space,
  doc.from_string("bar"),
  [ 
    doc.from_string("baz"),
    doc.space,
    doc.from_string("foo again"),
  ]
  |> doc.concat
  |> doc.nest(by: 1)
  |> doc.group
]
|> doc.join(with: doc.line)
|> doc.nest(by: 12)
|> doc.debug
|> doc.to_string(45)

// ->
// ⟨   
//   "foo" . lf . {" ", ""} . lf . "bar" . lf .
//   [ ⟨ "baz" . {" ", ""} . "foo again" ⟩¹ ]
// ⟩¹²

Maybe since doc.space is quite common it could be turned into something shorter like ~:

// ->
// ⟨   
//   "foo" . lf . ~ . lf . "bar" . lf .
//   [ ⟨ "baz" . ~ . "foo again" ⟩¹ ]
// ⟩¹²

Add a useful resources section in the README

I could add a "useful resources" section to list all the tutorials/examples/libraries that use glam

Ideally I should add at least a couple more tutorials before doing that, a list with a single bullet point would be sad :(

Add some tests for the provided examples

I'd like to add some tests for the examples that are shown in the library.
This would be beneficial in two ways:

• act as some sort of "integration testing" to make sure that future changes do not break the pretty printing algorithm
• make sure I do not show buggy code in the tutorials :P

Why is this a good first issue and how can you help?

I feel like this shouldn't be too complicated, especially if one has already walked through the package's tutorials.
Basically, what one would need to do is:

• read the examples' code
• make the x_to_doc functions to test public
• create a new module in the tests folder to add the tests for each pretty printer
• write some tests that test different data structures at different line widths
  • you can use the tutorials' examples as a reference for how the pretty printed documents should look