Reads a .sframe JSON file, or the same JSON held as text, and
reconstructs an sframe instrument object. The SHA-256 integrity hash is
verified by default, and content must match its hash. The hash covers a canonical form of the
content, so it detects a change to the content of a written file, and it
ignores whitespace and key order. It is unsigned, so anyone who edits a file
can also recompute it.
Arguments
- path
Character. The path to a
.sframefile. Leave itNULLand givetextto read a payload held in memory.- validate
Logical. Whether to validate the loaded instrument with
validate_sframe(). Defaults toTRUE. This controls structural validation only.verifycontrols the integrity hash.- text
Character. The
.sframeJSON itself, for example a payload a host keeps in a database, read directly from memory. One string, or lines to be joined.- verify
Logical. Whether to refuse content whose hash is missing or differs. Defaults to
TRUE. WithFALSE, such content is read with a warning of classsframe_unverified_warningand the instrument is marked unverified (see the Unverified reads section).
Details
The hash's canonical field names the form it was taken in. A file naming
"rfc8785" is checked in RFC 8785 alone. A file with an empty form was written
before the field existed: it is checked in RFC 8785 and then in the forms
surveyframe used before 0.4.3, and any match is accepted with a message of
class sframe_locale_order_hash asking you to save it again. A file naming
any other form is refused, since it needs a newer surveyframe.
The instrument remembers the content and amendment log it was read with, so
write_sframe() can refuse an undisclosed revision.
Unverified reads
verify = FALSE lets a host preserve every field in a payload whose
integrity it has not established. The result
carries the attribute sframe_verified, FALSE (it is TRUE on every
verified read), and print() says so. write_sframe() refuses to write an
unverified instrument unless new_instrument = TRUE declares it new, since
its content lacks a link to a state someone wrote. That holds with the
amendment log it was read with too, since the log was read unchecked: a
sign-off, a tier or a timestamp edited as text would otherwise be written
back and read verified. A new instrument starts a new log, so clear the old
one first with instrument$amendments <- list(). No amendment can start
from it: amend_sframe() refuses it.
See also
write_sframe(), validate_sframe()
Other Design functions:
as_sframe(),
launch_builder(),
sframe_attention_check(),
sframe_branch(),
sframe_choice_set(),
sframe_conjoint_design(),
sframe_get_study(),
sframe_instrument(),
sframe_item(),
sframe_sampling_methods(),
sframe_scale(),
sframe_validation,
validate_sframe(),
write_sframe()
Examples
instr <- read_sframe(
system.file("extdata", "tourism_services_demo.sframe",
package = "surveyframe")
)
print(instr)