ppp_help: All purpose property checking

In j-martineau/uj: Utilities by JAM

All purpose property checking

Description

This family of functions brings together a variety of families defined in this and gives users the ability to manage object properties in a granular and concise manner.

Property families defined by this package

bbb	basic properties
ccc	xclass (extended class)
ddd	defined.D (defined dimensionality)
eee	effective.D (effective dimensionality)
iii	integrity (completeness, uniqueness)
mmm	xmode (extended modes)
sss	shape (geometric shape)

This family uses concise and flexible property specs as defined in the following table.

single	3-char scalars (i.e., all(nchar(.) == 3) with all values in all_props(). For example, ⁠'ord', 'dtf', 'd2d',⁠ and 'rct' are single property specs.
combo	Character scalars containing multiple underscore-delimited single properties, indicating that those single properties must co-occur. For example, the combo property spec 'ord_dtf_d2d_rct' (or an equivalent underscore-delimited permutation) indicates that all four single properties must co-occur to satisfy the spec.
option	Character scalars containing multiple pipe-delimited combo and/or single property specs. For example, the option property spec 'ord|dtf_d2d|dtf_rct' would be satisfied by an object with single property 'ord', combo property 'dtf_d2d', or combo property 'dtf_rct'.
flex	A single, combo, or option property spec as defined above.

Usage

ppp_help()

ppp(x)

ppp_or_funs()

all_props(as.dtf = F)

prop_funs(as.dtf = F)

is_prop_fun(x)

is_prop(x)

is_prop_combo(x)

is_prop_spec(x)

props_from_spec(x, valid = all_props())

combos_from_spec(x)

props_from_combo(x)

PPP(x, spec, ...)

nll_or(x, spec, ...)

na0_or(x, spec, ...)

prop_defs()

prop_verbose(x, print = TRUE)

combo_concise(x)

spec_concise(x)

Arguments

x	An R object.
as.dtf	TRUE or FALSE indicating whether to return the result as a data.frame with column 1 containing property values and column 2 containing the property families.
valid	A complete character vec containing all properties considered valid.
spec	A complete character scalar containing one or more values from ppp_vals() separated by pipes and/or underscores. Combinations of properties can be specified by separating them with underscores. Separating properties or combinations of properties with pipes will result in a value of TRUE if any of them applies to x.
...	Arguments passed on to meets
print	TRUE or FALSE indicating whether to print the property definition to the console.

Details

Functions for property spec decomposition

props_from_combo	What are the constituent single properties of a combo property spec?
combo_from_spec	What are the constituent combo properties in a flex property spec?
props_from_spec	What are the unique constituent single properties in a flex property spec?

Functions to check whether a value is a valid property spec

is_prop_combo	Is combo a valid combo property spec?
is_prop_spec	Is spec a valid flex property spec?
is_prop_fun	Is fun the name of a dedicated property checking function?
is_prop	Is prop a valid single property?

Functions to define properties and property specs

combo_concise	How is a combo property spec (concisely) defined?
spec_concise	How is an options property spec (concisely) defined?
prop_verbose	How is a single property (verbosely) defined?
prop_defs	What are the definitions of all possible single properties (returned as a data.frame)?

Functions to list names of dedicated property-checking functions

ppp_or_funs	What dedicated functions check x for either special values or a match to a flex property spec?
prop_funs	What dedicated functions check x for a match to a specific single or combo property?
all_props	What is the complete set of all possible single properties?

Functions to check object against arbitrary property specs

nas_or	Is x either NA or a match to the flex property spec in Spec?
nll_or	Is x either NULL or a match to the flex property spec in Spec
ppp	Is x a match to the flex property spec in Spec?

Function to list all of an object's single properties across property families

ppp	What are all of x's single properties compiled from all property families?

For convenience, property functions from other function families are also described below.

Functions to list all single properties in a property family

bbb_props	basic
ccc_props	extended class
ddd_props	defined dimensionality
eee_props	effective dimensionality
iii_props	integrity
mmm_props	extended mode
sss_props	shape

Functions to list names of dedicated property-checking functions

cmp_mmm_ccc_funs	integrity = 'cmp' + extended mode + extended class
unq_mmm_ccc_funs	integrity = 'unq' + extended mode + extended class

cmp_ccc_funs	integrity = 'cmp' + extended class
cmp_mmm_funs	integrity = 'cmp' + extended mode
unq_ccc_funs	integrity = 'unq' + extended class
unq_mmm_funs	integrity = 'unq' + extended mode
bbb_ccc_funs	basic + extended class
bbb_mmm_funs	basic + extended mode
mmm_ccc_funs	extended mode + extended class

bbb_funs	basic
ccc_funs	extended class
ddd_funs	defined dimensionality
eee_funs	effective dimensionality
iii_funs	integrity
mmm_funs	extended mode
sss_funs	shape

Dedicated functions to check an object for a specific combo or single property

For these functions, {bbb}, {ccc}, {ddd}, {eee}, {iii}, {mmm}, and {sss} are placeholders for any given basic, extended class, defined.D, effective.D, integrity, xmode, and shape properties, respectively.

{bbb}	basic = '{bbb}'
{ccc}	extended class = '{ccc}'
{ddd}	defined dimensionality = '{ddd}'
{eee}	effective dimensionality = '{eee}'
{iii}	integrity = '{iii}'
{mmm}	extended mode = '{mmm}'
{sss}	shape = '{sss}'

⁠cmp_{ccc}⁠	integrity = 'cmp' + extended class = '{ccc}'
⁠cmp_{mmm}⁠	integrity = 'cmp' + extended mode = '{mmm}'
⁠unq_{ccc}⁠	integrity = 'unq' + extended class = '{ccc}'
⁠unq_{mmm}⁠	integrity = 'unq' + extended mode = '{mmm}'

⁠{bbb}_{ccc}⁠	basic = '{bbb}' + extended class = '{ccc}'
⁠{bbb}_{mmm}⁠	basic = '{bbb}' + extended mode = '{mmm}'
⁠{mmm}_{ccc}⁠	extended mode = '{mmm}' + extended class = '{ccc}'
⁠{sss}_{ccc}⁠	shape = '{sss}' + extended class = '{ccc}'

⁠cmp_{mmm}_{ccc}⁠	integrity = 'cmp' + extended mode = '{mmm}' + extended class = '{ccc}'
⁠unq_{mmm}_{ccc}⁠	integrity = 'unq' + extended mode = '{mmm}' + extended class = '{ccc}'

Functions to check an object against an arbitrary combo property spec

For these functions, an uppercase letter repeated three times is a placeholder for the value of an arbitrary single property from the associated property family.

bbb_ccc	basic property in arg bbb + extended class property in arg ccc
mmm_ccc	extended mode property in arg mmm + extended class property in arg ccc
cmp_ccc	integrity = 'cmp' + extended class property in arg ccc
sss_ccc	shape property in arg sss + extended class property in arg ccc
unq_ccc	integrity = 'unq' + extended class property in arg ccc
bbb_mmm	basic property in arg bbb + extended mode property in arg mmm
cmp_mmm	integrity = 'cmp' + extended mode property in arg mmm
unq_mmm	integrity = 'unq' + extended mode property in arg mmm

cmp_mmm_ccc	integrity = 'cmp' + extended mode property in arg mmm + extended class property in arg ccc
unq_mmm_ccc	integrity = 'unq' + extended mode property in arg mmm + extended class property in arg ccc

Functions to check objects against flex property specs in a single family

BBB	basic
CCC	extended class
DDD	defined dimensionality
EEE	effective dimensionality
III	integrity
MMM	extended mode
SSS	shape

Functions to retrieve all of an object's single properties of a specific family

bbb	basic
ccc	extended class
ddd	defined dimensionality
eee	effective dimensionality
iii	integrity
mmm	extended mode
sss	shape

Functions

• ppp(): Lists all properties of x. Returns a sorted, lowercase, character vector.

• ppp_or_funs(): Lists all property-or functions. Returns a sorted, lowercase, two-element, character vector.

• all_props(): Lists all possible properties. Returns a sorted, lowercase, character vector.

• prop_funs(): Lists all possible property checking functions. Includes both single-property and combination property checking functions. Returns a sorted, lowercase, character vector.

• is_prop_fun(): Checks whether x is the name of a property checking function. Returns a logical scalar.

• is_prop(): Checks whether x is a single property. Returns a logical scalar.

• is_prop_combo(): Checks whether x is a combination property spec. Returns a logical scalar. A combination property spec is two or more unique, valid, single properties separated by underscores.

• is_prop_spec(): Checks whether x is a valid property spec. Returns a logical scalar. A valid property spec must be a character scalar containing either a single property from all_props(), a combination property spec (two or more unique, valid, single properties separated by underscores), or a flexible property spec (two or more single properties or combination property specs separated by pipes).

• props_from_spec(): Converts a property spec to a unique list of its constituent single properties by splitting x along pipes and underscores, removing any blank values, sorting the remaining values, and returning the unique set of remaining values.

• combos_from_spec(): Converts a property spec into a vector of combination properties. Returns a character vector.

• props_from_combo(): Converts a combined property spec into a vector of single properties. Returns a character vector.

• PPP(): Checks x against the property spec spec subject to any count or value restrictions in .... Returns a logical scalar.

• nll_or(): Checks x against null-ness or the property spec spec subject to any count or value restrictions in .... Returns a logical scalar.

• na0_or(): Checks x against scalar missingness-ness or the property spec spec subject to any count or value restrictions in .... Returns a logical scalar.

• prop_defs(): Produces a data frame containing all properties with columns indicating property family, the value of the property, a short description of the property, and a long description of the property. Returns a tibble/data frame.

• prop_verbose(): Converts the property spec x into a verbose description of each constituent (combo) property, identifying each constituent (combo) property as an alternative to the others. Returns a character scalar.

• combo_concise(): Converts the (combo) property x to a concise description.

• spec_concise(): Converts the property spec x to a concise description.

Specifying count and value restrictions

Specifying restrictions in ... is optional. The full set of recognized arguments names are defined in the following table along with the properties each specifies:

⁠.max, .maxr, .maxc⁠	Scalar maximum valid numbers of elements, rows, and columns, respectively.
⁠.min, .minr, .minc⁠	Scalar minimum valid numbers of elements, rows, and columns, respectively.
⁠.lt, .le, .ge, .gt⁠	Complete sortable scalar less-than, less-than-or-equal, greater-than-or-equal, and greater-than bounds, respectively.
⁠.n, .nr, .nc⁠	A vector of valid numbers of elements, rows, and columns, respectively.
.vals	A vector of valid values.

See Also

Other properties: as_mmm(), bbb_ccc_help(), bbb_help(), bbb_mmm_prop_funs(), ccc_help(), cls(), cmp_ccc_help(), cmp_mmm_ccc_help(), cmp_mmm_help(), compatible(), ddd_prop_funs(), eee_help(), iii_help(), meets(), mmm_ccc_help(), mmm_help(), ppp_fast_help(), sss_ccc_help(), sss_prop_funs(), unq_ccc_prop_funs(), unq_mmm_ccc_help(), unq_mmm_help()

Examples

na0_or("5", "ch1")
na0_or(NA, "ch1")

nll_or(NULL, "ch1")
nll_or("1", "ch1")
nll_or(7, "ch1")

all_props()
prop_funs()

spec_concise("nll|cmp_psw_vls|ch1_scl")
combo_concise("cmp_psw_vls")
prop_verbose("srt")
prop_verbose("nnw")

combos_from_spec("nll|cmp_psw_vls|ch1_scl")
props_from_spec("nll|cmp_psw_vls|ch1_scl")
props_from_combo("cmp_psw_vls")

PPP("7", "nll|cmp_psw_vls|ch1_scl")
PPP(NULL, "nll|cmp_psw_vls|ch1_scl")
PPP("35", "nll|cmp_psw_vls|ch1_scl")

is_prop_combo("letter")
is_prop_combo("cmp_psw_vls")
is_prop_spec("nll|cmp_psw_vls|ch1_scl")

is_prop("vls")
is_prop("18")

is_prop_fun("cmp_psw_vls")
is_prop_fun("18")

ppp(letters)
prop_defs()

j-martineau/uj documentation built on Sept. 14, 2024, 4:40 a.m.