checkmark

Keep code blocks in markdown files or Gleam comments up to date.

Types

CheckError

Any error that can happen while using checkmark. The error type depends on the IO library used.

pub type CheckError(e) {
  CouldNotReadFile(error: e)
  CouldNotWriteFile(error: e)
  TagNotFound(tag: String)
  MultipleTagsFound(tag: String, lines: List(Int))
  ContentDidNotMatch(tag: String)
  FailedToLoadCodeSegment(file: String, reason: String)
  CouldNotParseSnippetSource
}

Constructors

```
CouldNotReadFile(error: e)
```
Could not read a source or target file.
```
CouldNotWriteFile(error: e)
```
While updating, could not write a file.
```
TagNotFound(tag: String)
```
Could not find a code snippet with the given tag.

MultipleTagsFound(tag: String, lines: List(Int))

Found multiple code blocks with the same tag.

```
ContentDidNotMatch(tag: String)
```
While checking, the content didn’t match expectations.

FailedToLoadCodeSegment(file: String, reason: String)

Could not load a code segment from a Gleam source file.

```
CouldNotParseSnippetSource
```
Could not parse a Gleam source file as a snippet source.

Checker

opaque </>

Contains the configuration for checking files. Not tied to a single file. The error type depends on the IO library used.

pub opaque type Checker(e)

CodeSegment

</>

Specifies a code segment to extract from a Gleam source file.

pub type CodeSegment {
  Function(name: String)
  FunctionBody(name: String)
  TypeDefinition(name: String)
}

Constructors

```
Function(name: String)
```
The full definition of the function with the given name.
```
FunctionBody(name: String)
```
The body of the function with the given name. Content is unindented based on the indentation of the first line.
```
TypeDefinition(name: String)
```
The full type definition of the type with the given name.

CodeSnippetSource

opaque </>

A Gleam source file, from which snippets can be loaded.

pub opaque type CodeSnippetSource

File

opaque </>

A markdown or source file to check, which can be linked to snippets in multiple other files. The error type depends on the IO library used.

pub opaque type File(e)

Values

check

</>

pub fn check(file: File(e)) -> Result(Nil, List(CheckError(e)))

Checks that the target file contain the expected code blocks. See should_contain_contents_of and should_contain_snippet_from to configure the content.

check_or_update

</>

pub fn check_or_update(
  file: File(e),
  when should_update: Bool,
) -> Result(Nil, List(CheckError(e)))

Convenience function for either checking or updating depending on a boolean.

comments_in

</>

pub fn comments_in(
  checker: Checker(e),
  filename: String,
) -> File(e)

Starts configuring code blocks in comments of a Gleam source file to be checked or updated. See should_contain_contents_of and should_contain_snippet_from to configure the content.

document

</>

pub fn document(checker: Checker(e), filename: String) -> File(e)

Starts configuring a markdown file to be checked or updated. See should_contain_contents_of and should_contain_snippet_from to configure the content.

load_snippet_source

</>

pub fn load_snippet_source(
  checker: Checker(e),
  filename: String,
) -> Result(CodeSnippetSource, CheckError(e))

Loads a Gleam source file to extract snippets from.

new

</>

pub fn new(
  read_file: fn(String) -> Result(String, e),
  write_file: fn(String, String) -> Result(Nil, e),
) -> Checker(e)

Builds a new checker with the provided file IO functions.

should_contain_contents_of

</>

pub fn should_contain_contents_of(
  file: File(e),
  filename: String,
  tagged tag: String,
) -> File(e)

Specify that the file should contain the contents of another file as a code block. For example

checker
|> checkmark.document("README.md")
|> checkmark.should_contain_contents_of("./example.sh", tagged: "sh deps")

will replace the code block starting with ```sh deps with the contents of example.sh. Whitespace is trimmed off the tag when matching it. Note that you still need to call check, update or check_or_update after this - this function only adds to the configuration.

should_contain_snippet_from

</>

pub fn should_contain_snippet_from(
  file: File(e),
  source: CodeSnippetSource,
  segment: CodeSegment,
  tagged tag: String,
) -> File(e)

Specify that the file should contain a code snippet from another file. For example

checker
|> checkmark.document("README.md")
|> checkmark.should_contain_snippet_from(
  snippets,
  checkmark.Function("wibble"),
  tagged: "wibble",
)

will replace the code block starting with ```gleam wibble with the full definition of the wibble function. Whitespace is trimmed off the tag when matching it. Note that you still need to call check, update or check_or_update after this - this function only adds to the configuration.

update

</>

pub fn update(file: File(e)) -> Result(Nil, List(CheckError(e)))

Updates the code blocks in the target file. See should_contain_contents_of and should_contain_snippet_from to configure the content.