collect_coded_fragments {rock}

Create an overview of coded fragments

Description

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,
  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")
)

Arguments

x

The parsed source(s) as provided by rock::parse_source or rock::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 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.

headingLevel

The number of hashes to insert before the headings.

add_html_tags

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 have add_html_tags be of the most use.

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 to FALSE 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.

codeHeadingFormatting

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.

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.

Value

Either a list of character vectors, or a single character value.

Examples

### 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
  )
);

### Only for the codes containing 'Code2'
cat(
  rock::collect_coded_fragments(
    parsedExample,
    'Code2'
  )
);