Summarize the code structure

Create a summary of one or multiple code files based on the section separators and their titles.

sum_str(path_in = getSourceEditorContext()$path, file_in_extension = ".R",
  dir_out = "", file_out = NULL, file_out_extension = "", width = NULL,
  rm_rh_hashes = TRUE, rm_rh_spaces = TRUE, rm_break_anchors = TRUE,
  line_nr = TRUE, granularity = 3, last_sep = FALSE, title = TRUE,
  header = TRUE, ...)

Arguments

path_in
Either a path to a directory or to a single file. If it is a directory path, all files in that directory will be summarised. If it is a single file path, only the resepective file will be summarised. The default value uses the RStudio API to produce a summary of content from the source editor. This requires that the file is saved before sum_str is called.
file_in_extension
If file_in is NULL, all files with the file_in_extension are considered, defaults to ".R".
dir_out
The directory to print the output to. "" implies the console.
file_out
A connection or character string naming the file to print to. If set to NULL, the name will be paste0("code-summary_", file_in). If dir_out is set to "", file_out can be set to "object" and the output of the function will be returned as an object instead of just printed to the console with cat. This is useful if output should be assigned to an object. If not set to "object", cat will be used.
file_out_extension
A file extension for the file to be created.
width
The character width of the output. If NULL, it is set to the length of the longest separator title.
rm_rh_hashes
Boolean value indicating whether or not to remove righthand hashes in section titles for the summary (see section Removing spaces and hashes).
rm_rh_spaces
Boolean value indicating whether or not to remove righthand spaces in section titles for the summary (see section Removing spaces and hashes).
rm_break_anchors
Boolean value indicating whether or not the anchors inserted in code separators should be removed for the summary.
line_nr
A boolean value that indicates whether the line numbers should be printed along with the structure summary.
granularity
Indicates the lowest level of granularity that should be included in the summary.
last_sep
A boolean value indicating whether or not the separating lines of the highest granularity should be printed.
title
A boolean value indicating whether the reported summary should contain a title or not.
header
A boolean value indicating whether a column header should indicate the name of the columns (line, level, section).
...
futher arguments to be passed from and to other methods, in particular list.files for reading in multiple files.

Details

To create the summary, sum_str uses regular expressions. Hence it is crucial that the code separators and the separator titles match the regular expression pattern. We recommend inserting separators and their titles using the RStudio Add-in that is contained in this package. The definition is rather intuitive as can be seen in the example section below. However, we shall provide a formal definition here as well.

  • A code separator is defined as a line that starts with n hashes, followed by 4-n spaces where 0 < n < 4. This sequence is followed by one or more either . or _.
  • A title associated with a code separator is defined as a line that starts with n hashes, followed by 4-n spaces where 0 < n < 4. This sequence is not followed by . or _.

Lines that do not satisfy these requirements (e.g. do not start with #s, do not contain the right number of spaces after the #, indent before any # ect.) are not considered by sum_str.

Removing spaces and hashes

The add-in contained in this package inserts section titles in a way that that they are recognised by RStudio as sections (for details, see https://support.rstudio.com/hc/en-us/articles/200484568-Code-Folding-and-Sections. One structure that is recognised by RStudio as section is a line starting with a hash and ending with four hashes. This structure is implemented with strcode. Hence when creating the summary, it might be desired to remove the right hand hashes and spaces, which can be specified with the respective options rm_rh_hashes and rm_rh_spaces.

See also

insert_l_break

Examples

# the following separator is an example of a valid
# separator and associated title

#   __________________________________________________
#   this is a level 1 title                     ####
##  . . . . . . . . . . . . . . . . . . . . . . . . .
##  note that the title or the separator character (_, .)
##  always starts at indention 4.

## Not run: ------------------------------------
# # Open a new .R file in RStudio, insert some code breaks
# # using the Add-in of this package, save the file and run:
# sum_str() # get a summary of the source editor.
## ---------------------------------------------