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.
collect_coded_fragments(
x,
codes = ".*",
context = 0,
includeDescendents = FALSE,
attributes = NULL,
heading = NULL,
headingLevel = 3,
add_html_tags = TRUE,
cleanUtterances = FALSE,
output = NULL,
outputViewer = "viewer",
template = "default",
rawResult = FALSE,
includeCSS = TRUE,
codeHeadingFormatting = rock::opts$get("codeHeadingFormatting"),
includeBootstrap = rock::opts$get("includeBootstrap"),
preventOverwriting = rock::opts$get("preventOverwriting"),
silent = rock::opts$get("silent")
)
The parsed source(s) as provided by rock::parse_source
or rock::parse_sources
.
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).
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.
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).
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.
Optionally, a title to include in the output. The title
will be prefixed with headingLevel
hashes (#
), and the codes with
headingLevel+1
hashes. If NULL
(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 not NULL
or a character vector (e.g. FALSE
).
If no heading is used, the code prefix will be headingLevel
hashes,
instead of headingLevel+1
hashes.
The number of hashes to insert before the headings.
Whether to add HTML tags to the result.
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 have add_html_tags
be of the most use.
Here, a path and filename can be provided where the result will be written. If provided, the result will be returned invisibly.
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 to FALSE
to not output anything to the console or the viewer.
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.
Whether to return the raw result, a list of the fragments, or one character value in markdown format.
Whether to include the ROCK CSS in the returned 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.
Whether to include the default bootstrap CSS.
Whether to prevent overwriting of output files.
Whether to provide (FALSE
) or suppress (TRUE
) more detailed progress updates.
Either a list of character vectors, or a single character value.
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.
### Get path to example source
examplePath <-
system.file("extdata", package="rock");
### Get a path to one example file
exampleFile <-
file.path(
examplePath, "example-1.rock"
);
### Parse single example source
parsedExample <-
rock::parse_source(
exampleFile
);
### Show organised coded fragments in Markdown
cat(
rock::collect_coded_fragments(
parsedExample
)
);
#>
#> <style>
#>
#>
#> .code {
#> border-radius: .25em;
#> box-sizing: border-box;
#> margin-left: 10px;
#> padding: 2px;
#> }
#>
#> .codeValue {
#> border-radius: .25em;
#> box-sizing: border-box;
#> margin-left: 10px;
#> padding: 2px;
#> }
#>
#> .identifier {
#> border-radius: .25em;
#> box-sizing: border-box;
#> margin-left: 10px;
#> padding: 2px;
#> }
#>
#> .sectionBreak {
#> border-radius: .25em;
#> box-sizing: border-box;
#> display: block;
#> }
#>
#> .uid {
#> border-radius: 0;
#> box-sizing: border-box;
#> }
#>
#> .utterance {
#> display: block;
#> }
#>
#> .code {
#> background-color: #f4d142;
#> }
#>
#> .codeValue {
#> background-color: #d2af20;
#> }
#>
#> .identifier {
#> background-color: #aaaaff;
#> }
#>
#> .sectionBreak {
#> background-color: #eeeeff;
#> }
#>
#> .uid {
#> background-color: #eeeeee;
#> color: #bbbbbb;
#> }
#>
#> .utterance {
#> border-top: 1px dotted black;
#> border-bottom: 1px dotted black;
#> }
#>
#> .utterance + .utterance {
#> margin-top: -1px;
#> }
#>
#> .context {
#> color: #bbbbbb;
#> }
#> </style>
#>
#>
#> <h3>Collected coded fragments with 0 lines of context</h3>
#>
#> #### childCode1 *(path: childCode1)*
#>
#> -----
#>
#> <div class="utterance">Lorem Ipsum is simply dummy text of the printing and typesetting industry. <span class="code codes">[[parentCode1>childCode1]]</span></div>
#>
#>
#> -----
#>
#> <div class="utterance">~specimen book. <span class="code codes">[[parentCode1>childCode2]]</span> <span class="code codes">[[childCode1]]</span> <span class="codeValue codeValues">[[intensity||2]]</span></div>
#>
#>
#> -----
#>
#>
#> #### grandchildCode2 *(path: childCode1>grandchildCode2)*
#>
#> -----
#>
#> <div class="utterance">~still in their infancy. <span class="code codes">[[parentCode1>childCode1>grandchildCode2]]</span></div>
#>
#>
#> -----
#>
#> <div class="utterance">accompanied by English versions from the 1914 translation by H. Rackham. <span class="code codes">[[childCode1>grandchildCode2]]</span></div>
#>
#>
#> -----
#>
#> <div class="utterance">reasonable. The generated Lorem Ipsum is therefore always free from <span class="code codes">[[grandchildCode2]]</span></div>
#>
#>
#> -----
#>
#>
#> #### childCode5 *(path: parentCode2>childCode5)*
#>
#> -----
#>
#> <div class="utterance">content of a page when looking at its layout. <span class="code codes">[[parentCode2>childCode5]]</span></div>
#>
#>
#> -----
#>
#>
#> #### grandchildCode7 *(path: childCode5>grandchildCode7)*
#>
#> -----
#>
#> <div class="utterance">repetition, injected humour, or non-characteristic words etc. <span class="code codes">[[childCode5>grandchildCode7]]</span></div>
#>
#>
#> -----
#>
#>
#> #### grandchildCode1 *(path: parentCode1>childCode1>grandchildCode1)*
#>
#> -----
#>
#> <div class="utterance">using 'Content here, content here', making it look like readable English. <span class="code codes">[[parentCode1>childCode1>grandchildCode1]]</span></div>
#>
#>
#> -----
#>
#>
#> #### grandchildCode3 *(path: parentCode1>childCode1>grandchildCode3)*
#>
#> -----
#>
#> <div class="utterance">by accident, sometimes on purpose (injected humour and the like). <span class="code codes">[[parentCode1>childCode1>grandchildCode3]]</span></div>
#>
#>
#> -----
#>
#>
#> #### childCode2 *(path: parentCode1>childCode2)*
#>
#> -----
#>
#> <div class="utterance">~specimen book. <span class="code codes">[[parentCode1>childCode2]]</span> <span class="code codes">[[childCode1]]</span> <span class="codeValue codeValues">[[intensity||2]]</span></div>
#>
#>
#> -----
#>
#>
#> #### childCode3 *(path: parentCode1>childCode3)*
#>
#> -----
#>
#> <div class="utterance">~~electronic typesetting, remaining essentially unchanged. <span class="code codes">[[parentCode1>childCode3]]</span> <span class="code codes">[[someOtherCode]]</span></div>
#>
#>
#> -----
#>
#>
#> #### childCode4 *(path: parentCode2>childCode4)*
#>
#> -----
#>
#> <div class="utterance">~~including versions of Lorem Ipsum. <span class="code codes">[[parentCode2>childCode4]]</span></div>
#>
#>
#> -----
#>
#>
#> #### grandchildCode4 *(path: parentCode2>childCode4>grandchildCode4)*
#>
#> -----
#>
#> <div class="utterance">Where does it come from? <span class="code codes">[[parentCode2>childCode4>grandchildCode4]]</span></div>
#>
#>
#> -----
#>
#>
#> #### grandchildCode5 *(path: parentCode2>childCode4>grandchildCode5)*
#>
#> -----
#>
#> <div class="utterance">old. <span class="code codes">[[parentCode2>childCode4>grandchildCode5]]</span></div>
#>
#>
#> -----
#>
#>
#> #### grandchildCode6 *(path: parentCode2>childCode4>grandchildCode6)*
#>
#> -----
#>
#> <div class="utterance">discovered the undoubtable source. <span class="code codes">[[parentCode2>childCode4>grandchildCode6]]</span></div>
#>
#>
#> -----
#>
#>
#> #### someOtherCode *(path: someOtherCode)*
#>
#> -----
#>
#> <div class="utterance">~~electronic typesetting, remaining essentially unchanged. <span class="code codes">[[parentCode1>childCode3]]</span> <span class="code codes">[[someOtherCode]]</span></div>
#>
#>
#> -----
#>
### Only for the codes containing 'Code2'
cat(
rock::collect_coded_fragments(
parsedExample,
'Code2'
)
);
#>
#> <style>
#>
#>
#> .code {
#> border-radius: .25em;
#> box-sizing: border-box;
#> margin-left: 10px;
#> padding: 2px;
#> }
#>
#> .codeValue {
#> border-radius: .25em;
#> box-sizing: border-box;
#> margin-left: 10px;
#> padding: 2px;
#> }
#>
#> .identifier {
#> border-radius: .25em;
#> box-sizing: border-box;
#> margin-left: 10px;
#> padding: 2px;
#> }
#>
#> .sectionBreak {
#> border-radius: .25em;
#> box-sizing: border-box;
#> display: block;
#> }
#>
#> .uid {
#> border-radius: 0;
#> box-sizing: border-box;
#> }
#>
#> .utterance {
#> display: block;
#> }
#>
#> .code {
#> background-color: #f4d142;
#> }
#>
#> .codeValue {
#> background-color: #d2af20;
#> }
#>
#> .identifier {
#> background-color: #aaaaff;
#> }
#>
#> .sectionBreak {
#> background-color: #eeeeff;
#> }
#>
#> .uid {
#> background-color: #eeeeee;
#> color: #bbbbbb;
#> }
#>
#> .utterance {
#> border-top: 1px dotted black;
#> border-bottom: 1px dotted black;
#> }
#>
#> .utterance + .utterance {
#> margin-top: -1px;
#> }
#>
#> .context {
#> color: #bbbbbb;
#> }
#> </style>
#>
#>
#> <h3>Collected coded fragments for codes 'grandchildCode2' & 'childCode2' with 0 lines of context</h3>
#>
#> #### grandchildCode2 *(path: childCode1>grandchildCode2)*
#>
#> -----
#>
#> <div class="utterance">~still in their infancy. <span class="code codes">[[parentCode1>childCode1>grandchildCode2]]</span></div>
#>
#>
#> -----
#>
#> <div class="utterance">accompanied by English versions from the 1914 translation by H. Rackham. <span class="code codes">[[childCode1>grandchildCode2]]</span></div>
#>
#>
#> -----
#>
#> <div class="utterance">reasonable. The generated Lorem Ipsum is therefore always free from <span class="code codes">[[grandchildCode2]]</span></div>
#>
#>
#> -----
#>
#>
#> #### childCode2 *(path: parentCode1>childCode2)*
#>
#> -----
#>
#> <div class="utterance">~specimen book. <span class="code codes">[[parentCode1>childCode2]]</span> <span class="code codes">[[childCode1]]</span> <span class="codeValue codeValues">[[intensity||2]]</span></div>
#>
#>
#> -----
#>