add get_protected()

[zkamvar]

This adds the get_protected() function, which provides a way to access the protected nodes that are labelled "@asis" or "@curly". See #109 for motivation. It will allow me to implement #107 without too much damage.

It also uses attributes to distinguish between protections.

I think this would help with {babeldown} by providing explicit accessors so that these lines of code will turn into:

  ## protect content inside curly braces and math ----
  woolish$protect_math()$protect_curly()

  curlies <- woolish$get_protected("curly")
  purrr::walk(curlies, protect_curly)

  maths <- woolish$get_protected("math")
  purrr::walk(maths, protect_math)

Here's an example of what it returns:

path <- system.file("extdata", "basic-curly.md", package = "tinkr")
ex <- tinkr::yarn$new(path, sourcepos = TRUE)
# we should have two protected elements right off due to the braces
ex$get_protected()
#> {xml_nodeset (2)}
#> [1] <text asis="true">[</text>
#> [2] <text asis="true">]</text>
# protect curly braces
ex$protect_curly()
# we should have six protected curly nodes
ex$get_protected()
#> {xml_nodeset (8)}
#> [1] <text curly="true">{#pre-face .unnumbered}</text>
#> [2] <text curly="true">{xml2}</text>
#> [3] <text curly="true">{tinkr}</text>
#> [4] <text curly="true" alt="a picture of a kitten">{#kitteh alt='a picture of ...
#> [5] <text curly="true" alt="a picture of a dog">{#dog alt="a picture\nof a do ...
#> [6] <text asis="true">[</text>
#> [7] <text asis="true">]</text>
#> [8] <text curly="true">{.span-with-attributes\nstyle='color: red;'}</text>
# add math and protect it
ex$add_md(c("## math\n", 
  "$c^2 = a^2 + b^2$\n", 
  "$$",
  "\\sum_{i}^k = x_i + 1",
  "$$\n")
)
ex$protect_math()
# one inline math, two softbreaks, one line of block
ex$get_protected()
#> {xml_nodeset (12)}
#>  [1] <text asis="true" math="true">$c^2 = a^2 + b^2$</text>
#>  [2] <softbreak math="true"/>
#>  [3] <text xml:space="preserve" asis="true" math="true">\\sum_{i}^k = x_i + 1 ...
#>  [4] <softbreak math="true"/>
#>  [5] <text curly="true">{#pre-face .unnumbered}</text>
#>  [6] <text curly="true">{xml2}</text>
#>  [7] <text curly="true">{tinkr}</text>
#>  [8] <text curly="true" alt="a picture of a kitten">{#kitteh alt='a picture o ...
#>  [9] <text curly="true" alt="a picture of a dog">{#dog alt="a picture\nof a d ...
#> [10] <text asis="true">[</text>
#> [11] <text asis="true">]</text>
#> [12] <text curly="true">{.span-with-attributes\nstyle='color: red;'}</text>
# they can be gotten singly
ex$get_protected("curly")
#> {xml_nodeset (6)}
#> [1] <text curly="true">{#pre-face .unnumbered}</text>
#> [2] <text curly="true">{xml2}</text>
#> [3] <text curly="true">{tinkr}</text>
#> [4] <text curly="true" alt="a picture of a kitten">{#kitteh alt='a picture of ...
#> [5] <text curly="true" alt="a picture of a dog">{#dog alt="a picture\nof a do ...
#> [6] <text curly="true">{.span-with-attributes\nstyle='color: red;'}</text>
ex$get_protected("math")
#> {xml_nodeset (4)}
#> [1] <text asis="true" math="true">$c^2 = a^2 + b^2$</text>
#> [2] <softbreak math="true"/>
#> [3] <text xml:space="preserve" asis="true" math="true">\\sum_{i}^k = x_i + 1< ...
#> [4] <softbreak math="true"/>
ex$get_protected("unescaped")
#> {xml_nodeset (2)}
#> [1] <text asis="true">[</text>
#> [2] <text asis="true">]</text>
# or combined
ex$get_protected(c("curly", "math"))
#> {xml_nodeset (10)}
#>  [1] <text asis="true" math="true">$c^2 = a^2 + b^2$</text>
#>  [2] <softbreak math="true"/>
#>  [3] <text xml:space="preserve" asis="true" math="true">\\sum_{i}^k = x_i + 1 ...
#>  [4] <softbreak math="true"/>
#>  [5] <text curly="true">{#pre-face .unnumbered}</text>
#>  [6] <text curly="true">{xml2}</text>
#>  [7] <text curly="true">{tinkr}</text>
#>  [8] <text curly="true" alt="a picture of a kitten">{#kitteh alt='a picture o ...
#>  [9] <text curly="true" alt="a picture of a dog">{#dog alt="a picture\nof a d ...
#> [10] <text curly="true">{.span-with-attributes\nstyle='color: red;'}</text>
# a warning pops up if the choices are not correct
ex$get_protected(c("curly", "shemp", "moe"))
#> the type options shemp, and moe are not one of math, curly, or unescaped
#> {xml_nodeset (6)}
#> [1] <text curly="true">{#pre-face .unnumbered}</text>
#> [2] <text curly="true">{xml2}</text>
#> [3] <text curly="true">{tinkr}</text>
#> [4] <text curly="true" alt="a picture of a kitten">{#kitteh alt='a picture of ...
#> [5] <text curly="true" alt="a picture of a dog">{#dog alt="a picture\nof a do ...
#> [6] <text curly="true">{.span-with-attributes\nstyle='color: red;'}</text>

^{Created on 2024-05-09 with reprex v2.1.0}

[maelle]

Awesome! 👏

Now I'll go try it out in babeldown and report back!

[maelle]

My report is #113

[zkamvar]

This works for both carpentries/pegboard@1d1be7b and ropensci-review-tools/babeldown#70, so I will go ahead and merge this so that the maintainers of babeldown and pegboard can move forward.

[maelle]

Thank you!!