Make a decorated comment in an R script

Description

Make a decorated multi-line comment from input strings and, if possible, transfer it to the clipboard ready for pasting into an R script (via the print method).

Usage

banner(
  x,
  ...,
  emph = FALSE,
  snug = FALSE,
  upper = emph,
  centre = !fold,
  leftSideHashes = 2 + emph,
  rightSideHashes = leftSideHashes,
  minHashes = (!snug) * (65 + 10 * emph),
  numLines = 1 + emph,
  bandChar = "#",
  center = centre,
  fold = FALSE,
  maxChar = 75
)

section(..., emph = TRUE, centre = TRUE, fold = TRUE)

boxup(..., rightSideHashes = 1, bandChar = "-")

open_box(
  ...,
  minHashes = 0,
  rightSideHashes = 0,
  centre = FALSE,
  bandChar = "-",
  center
)

block(
  ...,
  leftSideHashes = 3,
  rightSideHashes = 0,
  centre = FALSE,
  minHashes = 0,
  numLines = 0,
  center
)

Arguments

Value

A character string vector returned invisibly, but automatically displayed in the console

Functions

• section: Make a prominent banner such as might be useful at the beginning of a major code section

• boxup: Make a minimally boxed banner comment

• open_box: Make a boxed banner coment open at the right

• block: Make a simple block of comment lines

Examples

banner("This should appear clearly and stand out.",
       "The lines are left justified by default.")
section("This is the first line in a section heading",
        "and this is the second\nand this the third.")
boxup("This is a less obtrusive comment",
      "centred on multiple lines", center = TRUE, bandChar = ".")
banner("This is an important side issue.", "Take note!",
      snug = TRUE, bandChar = "=")
open_box("This is a succinctly presented comment",
         "left justified and open at the right",
         "on multiple lines")

block("This is a chatty comment.  Entering it this way just",
      "saves a tiny bit of typing but it can be useful if",
      "you need multiple initial hash marks, as you may when",
      "using Emacs/ESS, for example.",
      "Or if you want the lines centred for some odd reason.",
      center = TRUE)
## some authors like to use lines of a uniform length to separate code sections:
boxup("")

Transfer text strings to the clipboard ready for paste

Description

This is only guaranteed for Windows; in the case of Linux you will need to have the xclip command installed and visible on the PATH and for Mac OS you will need to have pbcopy similarly available. In any case the transfer to the clipboard is only activated while in an interactive session.

Usage

copy_to_clipboard(x, ..., file = con)

Arguments

Details

It behaves like base::cat but differs in three respects.

First, if file is left missing, in an interactive session, the default file is a clipboard device, if possible.

Second, the return value is invisible(x) rather than invisible(NULL) as it is for base::cat.

Third, it only has a copying side-effect if used in an interactive session. In a non-interactive session it merely returns the x argument, invisibly.

Note the on Windows the function utils::writeClipboard offers a much more extensive range of possibilities for communicating with the clipboard device, but this facility is only available on Windows.

Value

x, invisibly (as for a print method)

Print method for banner objects

Description

As well as printing the comment string in the console window the same text strings are transferred to a clipboard, if possible, ready for pasting into the R script currently being drafted.

Usage

## S3 method for class 'banner'
print(x, ...)

Arguments

Value

x itself, invisibly. A side effect is that x is transferred to a clipboard device, if possible

Functions for YAML comments

Description

A facility for generating a comment block for inserting at the top of an R script to insert a yaml header and for setting chunk options within scripts to use the RStudio facility for automatically rendering scripts into documents.

Usage

yaml_header(title, author, ...)

chunk_options(...)

Arguments

Value

An incomplete yaml header, or a line of chunk options, in the clipboard by default

Examples

yaml_header(title = "My script",
            author = "Bill Venables")
chunk_options(comment="",
              fig.height=7,
              fig.width=8,
              out.width="90%")