Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/giacomocavalieri/prng

🎲 A Pure Random Number Generator for Gleam
https://github.com/giacomocavalieri/prng

prng random-number-generator

Last synced: 17 days ago
JSON representation

🎲 A Pure Random Number Generator for Gleam

Awesome Lists containing this project

README 

        
# prng



[![Package Version](https://img.shields.io/hexpm/v/prng)](https://hex.pm/packages/prng)

[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/prng/)



🎲 A Pure Random Number Generator (PRNG) for Gleam



> ⚙️ This package works for both the Erlang and JavaScript target



## Installation



To add this package to your Gleam project:



```sh

gleam add prng

```



## Generating random values



This package can help you generate any kind of random values you can think of.

It can be useful in many different scenarios: when you need to simulate

non-deterministic actions, like rolling a dice or flipping a coin; when you need

to write [property based tests](https://ferd.ca/property-based-testing-basics.html);

or to make fun interactive games where you can spawn randomly generated enemies!



### A mindset shift



The way random values are generated may be a bit confusing at first, especially

coming from other languages like JavaScript. In such languages, random number

generation can be as simple as this:



```ts

const random_value: number = Math.random()

```



However, this should raise a lot of questions: what if I need those numbers to

be in a certain range?

How can I generate more complex values, like lists of

numbers?

Can I set the random seed to get deterministic and _reproducible results_ in a

test environment?



The `random` package tries to address all these questions by providing a nice

interface to define random value _generators_.

Let's have a look at an example to get a taste of what generating random values

will look like:



```gleam

let generator: Generator(Float) = random.float(0.0, 1.0)

let random_value: Float = random.sample(generator)

```



Notice a subtle but fundamental difference: you're no longer simply generating

a value, you're _describing_ the values you want to generate and you can

take those out of a generator with a variety of functions, like `sample`.



This neat trick can give two great features:



- _Composability:_ it's easy to describe simple generators and compose them

  together to generate complex data structures in an expressive way. The library

  has a rich API to create and compose generators, you can have a look at it

  [here](https://hexdocs.pm/prng/).

- _Reproducibility:_ you can decide the random seed used to generate the random

  values from a generator. The algorithm for the pseudo number generation will

  always yield the same results given the same starting seed!  

  The `random` package also goes out of its way to make sure that the random

  number generation _works exactly the same on all Gleam targets,_ so you won't

  get any discrepancies just by compiling to different targets



## References



This package and its documentation are based on the awesome

[Elm implementation](https://package.elm-lang.org/packages/elm/random/1.0.0/)

of [Permuted Congruential Generators](https://www.pcg-random.org).

They have great documentation full of clear and useful examples; if you are

curious, give it a look and show Elm some love!



## 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 💜