validate_headings: Validate headings

In carpentries/pegboard: Explore and Manipulate Markdown Curricula from the Carpentries

Validate headings

Description

This will validate the following aspects of all headings:

Usage

validate_headings(headings, title = NULL, offset = 5L)

heading_tests

heading_info

headings_first_heading_is_second_level(VAL)

headings_greater_than_first_level(VAL)

headings_are_sequential(VAL)

headings_have_names(VAL)

headings_are_unique(VAL)

Arguments

headings	an object of xml_nodelist.
title	the title of the document
offset	the number of lines to offset the position (equal to the size of the yaml header).
VAL	a data frame that contains the results of make_heading_table() and logical columns that match the name of the test.

Format

An object of class character of length 5.

An object of class character of length 5.

Details

• first heading starts at level 2 (first_heading_is_second_level)

• greater than level 1 (all_are_greater_than_first_level)

• increse sequentially (e.g. no jumps from 2 to 4) (all_are_sequential)

• have names (all_have_names)

• unique in their own hierarchy (all_are_unique)

Value

a list with two elements:

1. a data frame that contains the results of make_heading_table() and logical columns for each test where FALSE indicates a failed test for a given heading.

2. a data frame that can be printed as a tree with show_heading_tree()

Note

This is an internal function implemented for the Episode and Lesson classes.

Examples

l <- Lesson$new(lesson_fragment())
e <- l$episodes[[3]]
# Our headings validators run a series of tests on headings and return a data
# frame with information about the headings along with the results of the
# tests
v <- pegboard:::validate_headings(e$headings, e$get_yaml()$title, length(e$yaml))
names(v)
v$results
v$results$path <- fs::path_rel(e$path, e$lesson)
# The validator does not produce any warnings or messages, but this data
# frame can be passed on to other functions that will throw them for us. We
# have a function that will throw a warning/message for each heading that
# fails the tests. These messages are controlled by `heading_tests` and 
# `heading_info`.
pegboard:::heading_tests
pegboard:::heading_info
pegboard:::throw_heading_warnings(v$results)
# Because the headings are best understood in tree form we have a utility
# that will print the heading tree with the associated errors:
pegboard:::show_heading_tree(v$tree)

carpentries/pegboard documentation built on Nov. 13, 2024, 8:53 a.m.