Infer the notation(s) for a row or column label
infer_notation.Rd
It is convenient to know which notation is applicable to row or column labels.
This function infers which notations
are appropriate for x
.
Usage
infer_notation(
x,
inf_notation = TRUE,
notations = RCLabels::notations_list,
allow_multiple = FALSE,
retain_names = FALSE,
choose_most_specific = TRUE,
must_succeed = TRUE
)
Arguments
- x
A row or column label (or vector of labels).
- inf_notation
A boolean that tells whether to infer notation for
x
. Default isTRUE
.- notations
A list of notations from which matches will be inferred. This function might not work as expected if
notation
is not a list. Ifnotation
is not a list,notations
is returned in full. Default isRCLabels::notations_list
.- allow_multiple
A boolean that tells whether multiple notation matches are allowed. If
FALSE
(the default), multiple matches give an error.- retain_names
A boolean that tells whether to retain names from
notations
on the outgoing matches. Default isFALSE
. IfTRUE
, the return value is always a named list. If only one ofnotations
is returned (for example, becausechoose_most_specific = TRUE
), names are never supplied.- choose_most_specific
A boolean that indicates whether the most-specific notation will be returned when more than one of
notations
matchesx
andallow_multiple = FALSE
. WhenFALSE
, the first matching notation innotations
is returned whenallow_multiple = FALSE
. Default isTRUE
. See details.- must_succeed
A boolean that if
TRUE
(the default), causes an error to be thrown if a matching notation is not found for any label inx
. WhenFALSE
, an unsuccessful notation inference will returnNULL
.
Value
A single notation object (if x
is a single row or column label)
or a list of notation objects (if x
is a vector or a list).
If no notations
match x
, NULL
is returned,
either alone or in a list.
Details
This function is vectorized.
Thus, x
can be a vector, in which case the output is a list of notations.
notations
is treated as a store from which matches for each label in x
can be determined.
notations
should be a named list of notations.
When retain_names = TRUE
, the names on notations
will be retained,
and the return value is always a list.
By default (allow_multiple = FALSE
),
a single notation object is returned for each item in x
if only one notation in notations
is appropriate for x
.
If allow_multiple = FALSE
(the default) and more than one notation
is applicable to x
,
an error is thrown.
Multiple matches can be returned when allow_multiple = TRUE
.
If multiple notations are matched, the return value is a list.
When choose_most_specific = TRUE
(the default),
the most specific notation in notations
is returned.
"Most specific" is defined as the matching notation
whose sum of characters in the pref_start
, pref_end
,
suff_start
and suff_end
elements
is greatest.
If choose_most_specific = TRUE
and
two matching notations in notations
have the same number of characters,
only the first match is returned.
When choose_most_specific = TRUE
,
the value of allow_multiple
no longer matters.
allow_multiple = FALSE
is implied and
at most one of the notations
will be returned.
When inf_notation = FALSE
(default is TRUE
),
notations
are returned unmodified,
essentially disabling this function.
Although calling with inf_notation = FALSE
seems daft,
this behavior enables cleaner code elsewhere.
Examples
# Does not match any notations in RCLabels::notations_list
# and throws an error, because the default value for `must_succeed`
# is `TRUE`.
if (FALSE) {
infer_notation("abc")
}
# This returns `NULL`, because `must_succeed = FALSE`.
infer_notation("abc", must_succeed = FALSE)
#> NULL
# This succeeds, because the label is in the form of a
# notation in `RCLabels::notation_list`,
# the default value of the `notation` argument.
infer_notation("a -> b")
#> pref_start pref_end suff_start suff_end
#> "" " -> " " -> " ""
# Names of the notations can be retained, in which case
# the return value is always a list.
infer_notation("a -> b", retain_names = TRUE)
#> $arrow_notation
#> pref_start pref_end suff_start suff_end
#> "" " -> " " -> " ""
#>
# This function is vectorized.
# The list of labels matches
# all known notations in `RCLabels::notations_list`.
infer_notation(c("a -> b", "a (b)", "a [b]", "a [from b]", "a [of b]",
"a [to b]", "a [in b]", "a [-> b]", "a.b"),
retain_names = TRUE)
#> $arrow_notation
#> pref_start pref_end suff_start suff_end
#> "" " -> " " -> " ""
#>
#> $paren_notation
#> pref_start pref_end suff_start suff_end
#> "" " (" " (" ")"
#>
#> $bracket_notation
#> pref_start pref_end suff_start suff_end
#> "" " [" " [" "]"
#>
#> $from_notation
#> pref_start pref_end suff_start suff_end
#> "" " [from " " [from " "]"
#>
#> $of_notation
#> pref_start pref_end suff_start suff_end
#> "" " [of " " [of " "]"
#>
#> $to_notation
#> pref_start pref_end suff_start suff_end
#> "" " [to " " [to " "]"
#>
#> $in_notation
#> pref_start pref_end suff_start suff_end
#> "" " [in " " [in " "]"
#>
#> $bracket_arrow_notation
#> pref_start pref_end suff_start suff_end
#> "" " [-> " " [-> " "]"
#>
#> $first_dot_notation
#> pref_start pref_end suff_start suff_end
#> "" "." "." ""
#>
# By default, the most specific notation is returned.
# But when two or more matches are present,
# multiple notations can be returned, too.
infer_notation("a [from b]",
allow_multiple = TRUE, retain_names = TRUE,
choose_most_specific = FALSE)
#> $bracket_notation
#> pref_start pref_end suff_start suff_end
#> "" " [" " [" "]"
#>
#> $from_notation
#> pref_start pref_end suff_start suff_end
#> "" " [from " " [from " "]"
#>
infer_notation(c("a [from b]", "c [to d]"),
allow_multiple = TRUE, retain_names = TRUE,
choose_most_specific = FALSE)
#> [[1]]
#> [[1]]$bracket_notation
#> pref_start pref_end suff_start suff_end
#> "" " [" " [" "]"
#>
#> [[1]]$from_notation
#> pref_start pref_end suff_start suff_end
#> "" " [from " " [from " "]"
#>
#>
#> [[2]]
#> [[2]]$bracket_notation
#> pref_start pref_end suff_start suff_end
#> "" " [" " [" "]"
#>
#> [[2]]$to_notation
#> pref_start pref_end suff_start suff_end
#> "" " [to " " [to " "]"
#>
#>
# As shown above, "a \[from b\]" matches 2 notations:
# `RCLabels::bracket_notation` and `RCLabels::from_notation`.
# The default value for the notation argument is
# RCLabels::notations_list,
# which includes `RCLabels::bracket_notation`
# and `RCLabels::from_notation` in that order.
# Thus, there is some flexibility to how this function works
# if the value of the `notation` argument is a list of notations
# ordered from least specific to most specific,
# as `RCLabels::notations_list` is ordered.
# To review, the next call returns both `RCLabels::bracket_notation` and
# `RCLabels::from_notation`, because `allow_multiple = TRUE` and
# `choose_most_specific = FALSE`, neither of which are default.
infer_notation("a [from b]",
allow_multiple = TRUE,
choose_most_specific = FALSE,
retain_names = TRUE)
#> $bracket_notation
#> pref_start pref_end suff_start suff_end
#> "" " [" " [" "]"
#>
#> $from_notation
#> pref_start pref_end suff_start suff_end
#> "" " [from " " [from " "]"
#>
# The next call returns `RCLabels::from_notation`, because
# the most specific notation is requested, and
# `RCLabels::from_notation` has more characters in its specification than
# `RCLabels::bracket_notation`.
infer_notation("a [from b]",
choose_most_specific = TRUE,
retain_names = TRUE)
#> $from_notation
#> pref_start pref_end suff_start suff_end
#> "" " [from " " [from " "]"
#>
# The next call returns the `RCLabels::bracket_notation`, because
# `choose_most_specific = FALSE`, and the first matching
# notation in `RCLabels::notations_list` is `RCLabels::bracket_notation`.
infer_notation("a [from b]",
choose_most_specific = FALSE,
retain_names = TRUE)
#> $bracket_notation
#> pref_start pref_end suff_start suff_end
#> "" " [" " [" "]"
#>