mesv/format

The module containing the functions for building the Formatter, and for using a Formatter(a) to transform List(a) into a String, which can be directly written to file.

Examples

A basic example of formatting data

import gleam/int
import mesv/format

const data: List(#(String, Int, Bool)) = [
  #("Adam", 20, True),
  #("Beatrice", 25, True),
  #("Colin", 2, False),
]

pub fn main() -> Nil {
  let formatter =
    // First create a formatter
    format.build(fn(val: #(String, Int, Bool)) -> List(String) {
      let #(name, age, adult) = val
      [
        name,
        int.to_string(age),
        case adult {
          True -> "true"
          False -> "false"
        },
      ]
    })

  // Then, use that formatter on the data you want to format
  let formatted_data = format.format(formatter, data)

  // By default, the formatter uses the comma as a column separator,
  // newline as the row separator, and doublequotes for escaping cells
  assert formatted_data == "Adam,20,true\nBeatrice,25,true\nColin,2,false"
}

A cool party trick to impress your friends - computing data just in time when converting to string, minimizing the memory required!

// [...]
const data: List(#(String, Int)) = [
  #("Alex", 20),
  #("Betty", 25),
  #("Conrad", 2),
]

pub fn main() -> Nil {
  let formatted_data =
    format.build(fn(val: #(String, Int)) -> List(String) {
      let #(name, age) = val
      [
        name,
        int.to_string(age),
        bool.to_string(age >= 18),
      ]
    })
    |> format.format(data)

  assert formatted_data == "Alex,20,True\nBetty,25,True\nConrad,2,False"
}

Types

Formatter

opaque </>

The type describing how to convert a specified data type a into String form.

To create it, use the build function and the provided transformation functions (set_row_sep, set_col_sep, set_headers, set_escaper) to configure the specific behaviour.

Once you have the required Formatter(a), use the format function to convert a List(a) into a String.

pub opaque type Formatter(a)

Values

build

</>

pub fn build(f: fn(a) -> List(String)) -> Formatter(a)

Function for directly building a Formatter that outputs the specified elements in an exact order.

format

</>

pub fn format(
  formatter: Formatter(a),
  elements: List(a),
) -> String

Execution function that takes in a Formatter(a) as well as a List(a), and encodes it into a String.

All of the configuration options need to be set when building the Formatter, so this function is very simple to understand.

set_col_sep

</>

pub fn set_col_sep(
  formatter: Formatter(a),
  new_column_separator: String,
) -> Formatter(a)

Function to set a specific column separator, instead of the default comma (,)

If the column separator chosen is longer than a single character, it might cause problems with performance later during parsing.

set_escape_all

</>

pub fn set_escape_all(
  parser: Formatter(a),
  escape_all: Bool,
) -> Formatter(a)

Function to specify whether to wrap each value in an escaper, regardles of necessity.

By default false.

set_escaper

</>

pub fn set_escaper(
  formatter: Formatter(a),
  new_escaper: String,
) -> Formatter(a)

Function to set custom escaper (character that wraps the value if its’ string contains row or column separators, or the escaper itself)

set_headers

</>

pub fn set_headers(
  formatter: Formatter(a),
  new_headers: List(String),
) -> Formatter(a)

Function to manually set column headers in a particular order.

By default, no headers will be written to output String, and the first row will directly be the formatted data.

set_row_sep

</>

pub fn set_row_sep(
  formatter: Formatter(a),
  new_row_separator: String,
) -> Formatter(a)

Function to set a specific row separator, instead of the default newline (\n)

If the row separator chosen is longer than a single character, it might cause problems with performance later during parsing.