
Create an overview of coded fragments
Source:R/collect_coded_fragments.R
collect_coded_fragments.Rd
Collect all coded utterances and optionally add some context (utterances before and utterances after) to create an overview of all coded fragments per code.
Usage
collect_coded_fragments(
x,
codes = ".*",
context = 0,
includeDescendents = FALSE,
attributes = NULL,
heading = NULL,
headingLevel = 3,
add_html_tags = TRUE,
cleanUtterances = FALSE,
omitEmptyCodes = TRUE,
output = NULL,
outputViewer = "viewer",
template = "default",
rawResult = FALSE,
includeCSS = TRUE,
preserveSpaces = TRUE,
codeHeadingFormatting = rock::opts$get("codeHeadingFormatting"),
codeHeadingFormatting_html = rock::opts$get("codeHeadingFormatting_html"),
includeBootstrap = rock::opts$get("includeBootstrap"),
preventOverwriting = rock::opts$get("preventOverwriting"),
silent = rock::opts$get("silent")
)
Arguments
- x
The parsed source(s) as provided by
rock::parse_source
orrock::parse_sources
.- codes
The regular expression that matches the codes to include, or a character vector with codes or regular expressions for codes (which will be prepended with "
^
" and appended with "$
", and then concatenated using "|
" as a separator, to create a regular expression matching all codes).- context
How many utterances before and after the target utterances to include in the fragments. If two values, the first is the number of utterances before, and the second, the number of utterances after the target utterances.
- includeDescendents
Whether to also collect the fragments coded with descendent codes (i.e. child codes, 'grand child codes', etc; in other words, whether to collect the fragments recursively).
- attributes
To only select coded utterances matching one or more values for one or more attributes, pass a list where every element's name is a valid (i.e. occurring) attribute name, and every element is a character value with a regular expression specifying all values for that attribute to select.
- heading
Optionally, a title to include in the output. The title will be prefixed with
headingLevel
hashes (#
), and the codes withheadingLevel+1
hashes. IfNULL
(the default), a heading will be generated that includes the collected codes if those are five or less. If a character value is specified, that will be used. To omit a heading, set to anything that is notNULL
or a character vector (e.g.FALSE
). If no heading is used, the code prefix will beheadingLevel
hashes, instead ofheadingLevel+1
hashes.- headingLevel
The number of hashes to insert before the headings.
Whether to add HTML tags to the result.
- cleanUtterances
Whether to use the clean or the raw utterances when constructing the fragments (the raw versions contain all codes). Note that this should be set to
FALSE
to haveadd_html_tags
be of the most use.- omitEmptyCodes
Whether to still show the title for codes that do not occur or not.
- output
Here, a path and filename can be provided where the result will be written. If provided, the result will be returned invisibly.
- outputViewer
If showing output, where to show the output: in the console (
outputViewer='console'
) or in the viewer (outputViewer='viewer'
), e.g. the RStudio viewer. You'll usually want the latter when outputting HTML, and otherwise the former. Set toFALSE
to not output anything to the console or the viewer.- template
The template to load; either the name of one of the ROCK templates (currently, only 'default' is available), or the path and filename of a CSS file.
- rawResult
Whether to return the raw result, a list of the fragments, or one character value in markdown format.
- includeCSS
Whether to include the ROCK CSS in the returned HTML.
- preserveSpaces
Whether to preserve spaces in the output (replacing double spaces with "
").- codeHeadingFormatting, codeHeadingFormatting_html
A character value of the form
%s *(path: %s)*
(the default) or\n\n### %s\n\n*path:* ``%s``\n\n
. The first%s
is replaced by the code identifier; the second%s
by the corresponding path in the code tree; for markdown/console and html output, respectively.- includeBootstrap
Whether to include the default bootstrap CSS.
- preventOverwriting
Whether to prevent overwriting of output files.
- silent
Whether to provide (
FALSE
) or suppress (TRUE
) more detailed progress updates.
Details
By default, the output is optimized for inclusion in an R Markdown
document. To optimize output for the R console or a plain text
file, without any HTML codes, set add_html_tags
to FALSE, and
potentially set cleanUtterances
to only return the utterances,
without the codes.
Examples
### Get path to example source
examplePath <-
system.file("extdata", package="rock");
### Get a path to one example file
exampleFile <-
file.path(
examplePath, "example-.rock"
);
### Parse single example source
parsedExample <-
rock::parse_source(
exampleFile
);
### Show organised coded fragments in Markdown
cat(
rock::collect_coded_fragments(
parsedExample
)
);
#>
#>
#> ### Collected coded fragments for codes '' with a total of 0 lines of context (0+0)
#>
#>
#>
#> -----
#>
#>
#>
#> -----
#>
### Only for the codes containing 'Code2', with
### 2 lines of context (both ways)
cat(
rock::collect_coded_fragments(
parsedExample,
'Code2',
context = 2
)
);
#>
#>
#> ### Collected coded fragments for codes '' with a total of 4 lines of context (2+2)
#>
#>
#>
#> -----
#>
#>
#>
#> -----
#>
### Parse multiple example sources
### Load two example sources
parsedExamples <- rock::parse_sources(
examplePath,
regex = "example-[1234].rock"
);
#> Warning: For instance '1' of class 'caseId', attribute 'age' has different values: '60s' & '50s'. Taking the first element: '60s'.
#> Warning: For instance '2' of class 'caseId', attribute 'age' has different values: '20s' & '30s'. Taking the first element: '20s'.
#> Warning: For instance '1' of class 'caseId', attribute 'age' has different values: '60s' & '50s'. Taking the first element: '60s'.
#> Warning: For instance '2' of class 'caseId', attribute 'age' has different values: '20s' & '30s'. Taking the first element: '20s'.
#> Warning: For instance '1' of class 'caseId', attribute 'age' has different values: '60s' & '50s'. Taking the first element: '60s'.
#> Warning: For instance '2' of class 'caseId', attribute 'age' has different values: '20s' & '30s'. Taking the first element: '20s'.
cat(
rock::collect_coded_fragments(
parsedExamples,
'[cC]ode2',
context = 2
)
);
#>
#>
#> ### Collected coded fragments for codes 'code2', 'grandchildCode2', 'childCode2' & 'grandChildCode2' with a total of 4 lines of context (2+2)
#>
#>
#>
#> #### code2 *(path: codes>code2)*
#>
#>
#>
#> -----
#>
#> **Source: `anchor-example-1.rock`**
#>
#> What is Lorem Ipsum? [[code1]]
#> Lorem Ipsum is simply dummy text of the
#> printing and typesetting industry. [[code2]]
#> --+-{ 2022-11-26 21:02:00.000 CET (UTC+1) }-+--
#> Lorem Ipsum has been the industry's [[code3]]
#>
#> -----
#>
#>
#>
#>
#> #### grandchildCode2 *(path: codes>parentCode1>childCode1>grandchildCode2)*
#>
#>
#>
#> -----
#>
#> **Source: `example-1.rock`**
#>
#> ~~desktop publishing packages and web page editors now use Lorem Ipsum as their
#> ~~default model text, and a search for 'lorem ipsum' will uncover many web sites
#> ~still in their infancy. [[parentCode1>childCode1>grandchildCode2]]
#>
#>
#>
#> -----
#>
#> **Source: `example-1.rock`**
#>
#> those interested. Sections 1.10.32 and 1.10.33 from \"de Finibus Bonorum et
#> Malorum\" by Cicero are also reproduced in their exact original form,
#> accompanied by English versions from the 1914 translation by H. Rackham. [[childCode1>grandchildCode2]]
#>
#>
#>
#> -----
#>
#> **Source: `example-1.rock`**
#>
#> the Internet. It uses a dictionary of over 200 Latin words, combined with a
#> handful of model sentence structures, to generate Lorem Ipsum which looks
#> reasonable. The generated Lorem Ipsum is therefore always free from [[grandchildCode2]]
#> repetition, injected humour, or non-characteristic words etc. [[childCode5>grandchildCode7]]
#>
#>
#> -----
#>
#>
#>
#>
#> #### childCode2 *(path: codes>parentCode1>childCode2)*
#>
#>
#>
#> -----
#>
#> **Source: `example-1.rock`**
#>
#> Lorem Ipsum has been the industry's standard dummy text ever since the 1500s,
#> ~when an unknown printer took a galley of type and scrambled it to make a type
#> ~specimen book. [[parentCode1>childCode2]] [[childCode1]] [[intensity||2]]
#> ~
#> ~It has survived not only five centuries, but also the leap into
#>
#> -----
#>
#>
#>
#>
#> #### grandChildCode2 *(path: codes>parentCode>childCode>grandChildCode2)*
#>
#>
#>
#> -----
#>
#> **Source: `example-2.rock`**
#>
#> [[uid=7ghf801h]] ~Aliquam erat volutpat. [[childCode>grandChildCode]]
#> [[uid=7ghf801k]] Maecenas in massa quis tellus viverra consequat.
#> [[uid=7ghf801l]] ~Vestibulum ante ipsum primis in faucibus orci.
#> [[uid=7ghf801m]] ~Vivamus ut sapien leo. [[childCode>grandChildCode2]]
#> [[uid=7ghf801n]]
#>
#> -----
#>