banner {bannerCommenter}

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

x

A string, first line of the comment. If "", the zero-length string, only the top lines of the banner are made. If missing, in an interactive session the user will be prompted for the input strings, one per line, in the console.

...

Zero or more additional strings as extra lines. Strings may contain newline characters resulting in further line breaks.

emph

A logical value: Do you want this to be an emphasised comment?

snug

A logical value: Do you want the decoration to hug the strings closely?

upper

A logical value: Do you want the strings converted to upper case?

centre

A logical value: Do you want the text strings centred? (alternative: left justified)

leftSideHashes

A positive integer: How many hashes go on the left side?

rightSideHashes

A non-negative integer: How many hashes go on the right side?

minHashes

A non-negative integer: What is the minimum number of hashes in the boundary lines?

numLines

A non-negative integer: How many lines of hashes above and below do you want?

bandChar

A single character. Used instead of # for all characters in the bands around the text, apart from the first character of every line.

center

Alternative spelling of centre.

fold

Logical: should the text be folded to ensure lines are not too long?

maxChar

Ingeter: maximum length allowed in any line if fold is TRUE.

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