Struct Policy 

pub struct Policy {
    pub rules: Vec<Rule>,
    pub posture: Posture,
    pub unrecognised: Unrecognised,
}

An ordered list of rules, plus what to do with everything they do not name.

Rules apply in order, each to the message as it stands (D7, spec §2.4). The Posture then runs over every leaf that no rule named (D9, spec §2.6), and Unrecognised covers a payload that is not ER7 at all (D21, spec §2.8).

A reject beats an accept (D19)

A rule whose action is Action::Keep accepts the position it names; any other action rejects it. Where a leaf is named by both, the rejecting rule wins — whichever order the two rules are in, and at whatever depth, so a reject naming a whole segment beats an accept naming one field inside it.

A leaf named by both is a policy somebody got wrong, and redacting it is the direction that fails safely (spec §1.5, priority 1): a value redacted by mistake costs a policy edit, and a value left behind by mistake cannot be recalled.

The mirror of that rule: an accept naming a whole segment is not narrowed by the posture. MSH keep exempts every leaf of the header, including ones the policy’s author never saw. Only a reject rule reaches back into it.

Example:

use er7_redact::{Action, Policy, Redactor};

// Redact what is listed...
let listed = Policy::accept_all()
    .with("PID-5", Action::redacted())?
    .with("PID-7", Action::First(4))?;

// ...or redact everything that is not.
let everything_else = Policy::reject_all().with("MSH", Action::Keep)?;

let mut message = er7::parse("MSH|^~\\&|LAB\rPID|1||9||SMITH^JOHN||19610615")?;
Redactor::new(listed).redact(&mut message);
assert_eq!(message.to_er7(), "MSH|^~\\&|LAB\rPID|1||9||REDACTED^REDACTED||1961");

Fields

rules: Vec<Rule>

The rules, in the order they apply.

posture: Posture

What every leaf no rule named gets.

unrecognised: Unrecognised

What a payload that is not ER7 gets.

Implementations

impl Policy

pub fn accept_all() -> Policy

Accept everything: no rules, nothing redacted, and a payload that is not ER7 passed through unchanged (spec §5.6).

This is the starting point for building a policy rule by rule. On its own it does nothing at all, and it says so: a policy named “accept all” that quietly replaced an unparseable payload with *** would be the one surprise it has no excuse for.

A policy file that states no defaults is not quite this: it accepts by default too, but it refuses an unrecognised payload, because it was written by somebody who did not think about one (spec §6.1). Ask for Unrecognised::Pass in the file to get it.

Example:

use er7_redact::{Action, Policy, Posture, Redactor, Unrecognised};

let policy = Policy::accept_all();
assert_eq!(policy.posture, Posture::Accept);
assert_eq!(policy.unrecognised, Unrecognised::Pass);
assert!(policy.is_empty());

// It changes nothing, and reports nothing.
let mut message = er7::parse("MSH|^~\\&|LAB\rPID|1||9||SMITH")?;
let report = Redactor::new(policy).redact(&mut message);
assert_eq!(message.to_er7(), "MSH|^~\\&|LAB\rPID|1||9||SMITH");
assert!(report.is_empty());

Examples found in repository

examples/redact_absent_empty_null.rs (line 16)

fn main() -> Result<(), er7_redact::Error> {
    // PID-1 has a value, PID-2 was sent blank, PID-3 is the explicit null,
    // and PID-4 onwards was never sent at all.
    let text = "MSH|^~\\&|LAB\rPID|1||\"\"";

    let policy = Policy::accept_all()
        .with("PID-1", Action::redacted())?
        .with("PID-2", Action::redacted())?
        .with("PID-3", Action::redacted())?
        .with("PID-9", Action::redacted())?;

    let mut message = er7::parse(text)?;
    let report = Redactor::new(policy).redact(&mut message);

    // Only the field that carried a value changed.
    assert_eq!(message.to_er7(), "MSH|^~\\&|LAB\rPID|REDACTED||\"\"");
    assert_eq!(report.len(), 1);

    // Why each of the other three was left alone:
    //
    // PID-2 was empty. Writing REDACTED into it would invent a value, and
    // would announce that one used to be there — which is a disclosure.
    assert!(message.segment("PID").unwrap().field(2).unwrap().is_empty());
    //
    // PID-3 is the explicit null: an instruction to the receiver to clear
    // its stored value, not patient data. Overwriting it would turn
    // "clear this" into a value, and leave a withdrawn record standing.
    assert!(message.segment("PID").unwrap().field(3).unwrap().is_null());
    //
    // PID-9 was never sent. Redaction does not lengthen a segment to reach
    // a position that is not there: padding would change what the message
    // says, and eleven new trailing pipes would announce the redaction.
    assert!(message.segment("PID").unwrap().field(9).is_none());

    // To *make* a position null — to tell the receiver to clear it — ask
    // for that, which is the one action that changes the shape of a
    // message, because an HL7 null is a single `""`.
    let mut message = er7::parse("MSH|^~\\&|LAB\rPID|1||9||SMITH^JOHN")?;
    let policy = Policy::accept_all().with("PID-5", Action::Null)?;
    Redactor::new(policy).redact(&mut message);
    assert_eq!(message.to_er7(), "MSH|^~\\&|LAB\rPID|1||9||\"\"");

    // Compare with `clear`, which says nothing rather than saying "delete".
    let mut message = er7::parse("MSH|^~\\&|LAB\rPID|1||9||SMITH^JOHN")?;
    let policy = Policy::accept_all().with("PID-5", Action::Clear)?;
    Redactor::new(policy).redact(&mut message);
    assert_eq!(message.to_er7(), "MSH|^~\\&|LAB\rPID|1||9||^");

    println!("absent, empty, and null all survived redaction unchanged");
    Ok(())
}

examples/write_a_policy.rs (line 14)

fn main() -> Result<(), er7_redact::Error> {
    // 1. Built in Rust, rule by rule. Order matters: rules apply in the
    //    order they are listed. `accept_all` is the starting point that
    //    redacts nothing until a rule says so — the other one is
    //    `reject_all`, which redacts everything until a `keep` rule says
    //    otherwise.
    let built = Policy::accept_all()
        .with("PID-3.1", Action::Pseudonym)?
        .with("PID-5", Action::redacted())?
        .with("PID-7", Action::First(4))?
        .with("PID-19", Action::Clear)?;

    // 2. Read from a policy file — the same thing, in the form a team
    //    reviews in a pull request.
    let read = Policy::parse(
        "
        PID-3.1  pseudonym    # keep linkage, lose the record number
        PID-5    replace REDACTED
        PID-7    first 4      # the birth year is enough for most tests
        PID-19   clear
        ",
    )?;
    assert_eq!(built.rules, read.rules);

    // Both accept by default: a position no rule names is left alone.
    assert_eq!(built.posture, Posture::Accept);
    assert_eq!(read.posture, Posture::Accept);

    // They differ on one thing, and it is worth knowing about. A payload
    // that is not ER7 at all has no positions in it, so no rule can speak
    // to it. `accept_all` passes one through, because it is a policy that
    // redacts nothing and says so. A policy *file* that mentions no
    // disposition refuses one instead: it was written by somebody who may
    // simply not have considered the case, and refusing loses no value
    // quietly.
    assert_eq!(built.unrecognised, Unrecognised::Pass);
    assert_eq!(read.unrecognised, Unrecognised::Refuse);

    // Either way, say it outright and the two agree.
    let built = built.on_unrecognised(Unrecognised::Refuse);
    assert_eq!(built, read);

    // 3. Start from a built-in and add to it. `--show-policy` on the
    //    command line writes the built-in out as a file to edit.
    let extended = Policy::patient_identifiers()
        .with("NTE-3", Action::Clear)? // free text: nothing positional finds what is in here
        .with("OBX-5", Action::Clear)?;
    assert_eq!(
        extended.rules.len(),
        Policy::patient_identifiers().rules.len() + 2
    );

    // A policy writes itself back out in the file format, so the one that
    // ran can be recorded beside the message it redacted.
    println!("{built}");
    assert_eq!(Policy::parse(&built.to_string())?, built);

    let text = "MSH|^~\\&|LAB\rPID|1||PATID1234||EVERYWOMAN^EVE||19610615|F";
    let mut message = er7::parse(text)?;
    Redactor::new(built).redact(&mut message);
    assert_eq!(message.query("PID-5.1")?.as_deref(), Some("REDACTED"));

    // A malformed policy is rejected at load time, with the line number:
    // a typo here means a value that silently was not redacted.
    let error = Policy::parse("PID-5 obfuscate").unwrap_err();
    println!("{error}");
    assert!(error.to_string().contains("policy line 1"));

    Ok(())
}

pub fn reject_all() -> Policy

Reject everything: no rules, replace REDACTED over every leaf, and a payload that is not ER7 masked whole (spec §5.6).

The strictest thing in the crate, and it takes the header with it: everything from MSH-3 on reads REDACTED, so the message is no longer routable or identifiable. Policy::all_but_the_header is the same posture with the header kept, and is usually what is wanted.

MSH-1 and MSH-2 survive, as they survive everything: they are the delimiters themselves (D5, spec §4.4).

Example:

use er7_redact::{Action, Policy, Redactor};

let policy = Policy::reject_all().with("OBX-2", Action::Keep)?;
let mut message = er7::parse("MSH|^~\\&|LAB\rOBX|1|NM|2093-3||187")?;
Redactor::new(policy).redact(&mut message);

assert_eq!(
    message.to_er7(),
    "MSH|^~\\&|REDACTED\rOBX|REDACTED|NM|REDACTED||REDACTED",
);

Examples found in repository

examples/reject_by_default.rs (line 60)

fn main() -> Result<(), er7_redact::Error> {
    let text = "MSH|^~\\&|LAB|ACME|EHR|CLINIC|20260815120000||ORU^R01|MSG9|P|2.5\r\
                PID|1||PATID1234||EVERYWOMAN^EVE||19610615|F\r\
                OBX|1|NM|2093-3^Cholesterol^LN||187|mg/dL|100-199|H|||F\r\
                ZPD|1|LOCAL^EXTENSION^SEGMENT";

    // Rejecting by default covers every leaf no rule named; a `keep` rule
    // accepts a position, exempting it from that. A rejecting rule would
    // beat the `keep` whichever order the two were written in (D19).
    let policy = Policy::all_but_the_header()
        .with("OBX-2", Action::Keep)? // value type
        .with("OBX-3", Action::Keep)? // observation identifier
        .with("OBX-5", Action::Keep)? // the number the test asserts on
        .with("OBX-6", Action::Keep)?; // units

    let mut message = er7::parse(text)?;
    let report = Redactor::new(policy).redact(&mut message);
    println!("{}\n", message.to_er7().replace('\r', "\n"));

    // The header is untouched, so the message still routes and still says
    // which version it is.
    assert_eq!(message.query("MSH-9")?.as_deref(), Some("ORU^R01"));
    assert_eq!(message.version().as_deref(), Some("2.5"));

    // The result is intact, because four rules said so.
    assert_eq!(message.query("OBX-3.2")?.as_deref(), Some("Cholesterol"));
    assert_eq!(message.query("OBX-5")?.as_deref(), Some("187"));

    // Everything else is gone — including the local segment, which no
    // curated policy could have known about.
    assert_eq!(message.query("PID-5.1")?.as_deref(), Some("REDACTED"));
    assert_eq!(message.query("ZPD-2.1")?.as_deref(), Some("REDACTED"));

    // The cost: values a positional policy would have kept are gone too.
    assert_eq!(message.query("PID-8")?.as_deref(), Some("REDACTED"));
    assert_eq!(message.query("OBX-8")?.as_deref(), Some("REDACTED"));

    println!("{} positions changed", report.len());

    // And what this posture is really for: a payload that is not ER7 at
    // all has no positions to name, so the policy says outright what
    // becomes of it. The curated policy above refuses one, which is what
    // makes the CLI exit non-zero rather than write it out.
    let redactor = Redactor::new(Policy::all_but_the_header());
    assert_eq!(redactor.unrecognised("{\"name\": \"EVERYWOMAN\"}"), None);

    // `Policy::reject_all` masks it whole instead — nothing routable
    // survives, and neither does anything else.
    let redactor = Redactor::new(Policy::reject_all());
    assert_eq!(
        redactor.unrecognised("EVERYWOMAN").as_deref(),
        Some("**********")
    );
    Ok(())
}

pub fn patient_identifiers() -> Policy

The curated policy: the positions that carry a patient identifier in PID, NK1, PV1, GT1, and IN1.

It accepts by default, so a position the table does not name is left as it is, and it refuses a payload that is not ER7: a list of positions has no opinion about input with no positions in it, and refusing is the fail-closed answer (spec §2.8).

The whole table is written out in spec §5.1, with a reason for each action. It is a starting point, not a compliance certification (D14): it does not touch free text, quasi-identifiers, or local Z segments, and it does not know which positions your senders actually use. Read spec §5.4 and §5.5 before relying on it.

Example:

use er7_redact::{Policy, Redactor};

let mut message = er7::parse(
    "MSH|^~\\&|LAB\rPID|1||PATID1234||EVERYWOMAN^EVE||19610615|F|||12 ELM ST^^BOSTON",
)?;
let report = Redactor::new(Policy::patient_identifiers()).redact(&mut message);

assert_eq!(message.query("PID-5.1")?.as_deref(), Some("REDACTED"));
assert_eq!(message.query("PID-7")?.as_deref(), Some("1961"));
assert_eq!(message.query("PID-11.1")?.as_deref(), Some(""));
assert_ne!(message.query("PID-3")?.as_deref(), Some("PATID1234"));

// The sex is not an identifier, so the default policy leaves it.
assert_eq!(message.query("PID-8")?.as_deref(), Some("F"));
assert!(!report.is_empty());

Panics

Only if the table below is edited to hold something that is not an HL7 path — every entry is a literal, and the_documented_positions_match_the_built_in_policy in tests/integration.rs checks the whole table against spec §5.1.

Examples found in repository

examples/redact_a_message.rs (line 14)

fn main() -> Result<(), er7_redact::Error> {
    let text = "MSH|^~\\&|ADT1|MCM|LABADT|MCM|20260815140000||ADT^A08|MSG00001|P|2.5\r\
                PID|1||PATID1234^^^ADT1^MR||EVERYWOMAN^EVE^E||19610615|F|||\
                1200 N ELM STREET^^GREENSBORO^NC^27401-1020||(919)379-1212\r\
                OBX|1|NM|2093-3^Cholesterol^LN||187|mg/dL|100-199|H|||F";

    let mut message = er7::parse(text)?;
    let report = Redactor::new(Policy::patient_identifiers()).redact(&mut message);

    println!("{}\n", message.to_er7().replace('\r', "\n"));
    println!("{} positions changed:\n{report}", report.len());

    // The identifiers are gone.
    assert_eq!(
        message.query("PID-5")?.as_deref(),
        Some("REDACTED^REDACTED^REDACTED")
    );
    assert_eq!(message.query("PID-7")?.as_deref(), Some("1961"));
    assert_eq!(message.query("PID-11")?.as_deref(), Some("^^^^"));
    assert_eq!(message.query("PID-13")?.as_deref(), Some(""));
    assert_ne!(message.query("PID-3.1")?.as_deref(), Some("PATID1234"));

    // The message is not.
    assert_eq!(message.control_id().as_deref(), Some("MSG00001"));
    assert_eq!(message.query("PID-3.4")?.as_deref(), Some("ADT1")); // assigning authority
    assert_eq!(message.query("PID-8")?.as_deref(), Some("F")); // not an identifier
    assert_eq!(message.query("OBX-5")?.as_deref(), Some("187")); // the clinical content
    assert!(er7::parse(&message.to_er7()).is_ok());

    // And the shape did not move: every position that held a value still
    // exists, so a test that asserted on PID-11.3 still finds it.
    assert_eq!(message.query("PID-11.3")?.as_deref(), Some(""));

    Ok(())
}

examples/read_the_report.rs (line 15)

fn main() -> Result<(), er7_redact::Error> {
    let text = "MSH|^~\\&|ADT1|MCM||||||ADT^A08|MSG1|P|2.5\r\
                PID|1||PATID1234^^^ADT1^MR||EVERYWOMAN^EVE^E||19610615|F|||\
                12 ELM ST^^BOSTON^MA^02101||555-555-1111~555-555-2222\r\
                NK1|1|EVERYMAN^ADAM|SPO";

    let mut message = er7::parse(text)?;
    let report = Redactor::new(Policy::patient_identifiers()).redact(&mut message);

    for change in &report.changes {
        println!("{:<18} {}", change.path.to_string(), change.action);
    }

    // One row per leaf that actually changed — so a name in three
    // components is three rows, and a repeated field is one row per
    // repetition.
    let paths: Vec<String> = report.changes.iter().map(|c| c.path.to_string()).collect();
    assert!(paths.contains(&"PID[1]-5[1].1.1".to_string()));
    assert!(paths.contains(&"PID[1]-5[1].3.1".to_string()));
    assert!(paths.contains(&"PID[1]-13[2].1.1".to_string()));

    // Every path is fully qualified, which means it is also a valid
    // `er7 --query` argument: paste one in to see what is there now.
    for change in &report.changes {
        assert!(message.query(&change.path.to_string()).is_ok());
    }

    // A report carries no values — not the old text, and not the new. A
    // log line quoting the old value puts the patient's name into the log.
    let printed = report.to_string();
    for value in ["EVERYWOMAN", "PATID1234", "19610615", "BOSTON"] {
        assert!(!printed.contains(value));
    }

    // And nothing that was not there contributes a row: this message has
    // no GT1 segment, so the guarantor rules matched nothing, which is not
    // an error.
    assert!(!paths.iter().any(|p| p.starts_with("GT1")));

    println!("\n{} positions changed", report.len());
    Ok(())
}

examples/pseudonyms_and_linkage.rs (line 21)

fn main() -> Result<(), er7_redact::Error> {
    let admit = "MSH|^~\\&|ADT1|MCM||||||ADT^A01|MSG1|P|2.5\r\
                 PID|1||PATID1234^^^ADT1^MR||EVERYWOMAN^EVE";
    let result = "MSH|^~\\&|LAB|ACME||||||ORU^R01|MSG2|P|2.5\r\
                  PID|1||PATID1234^^^ADT1^MR||EVERYWOMAN^EVE\r\
                  OBX|1|NM|2093-3^Cholesterol^LN||187";

    let redactor = Redactor::new(Policy::patient_identifiers()).with_key(KEY);

    let mut admit = er7::parse(admit)?;
    let mut result = er7::parse(result)?;
    redactor.redact(&mut admit);
    redactor.redact(&mut result);

    // The record number is gone from both...
    let one = admit.query("PID-3.1")?.expect("a value");
    let two = result.query("PID-3.1")?.expect("a value");
    assert_ne!(one, "PATID1234");

    // ...and the two messages still agree that this is the same patient,
    // which is what makes them useful as a test case.
    assert_eq!(one, two);
    println!("both messages now say PID-3.1 = {one}");

    // A different key produces an unrelated mapping, so two data sets
    // redacted under different keys cannot be joined.
    let mut other = er7::parse("MSH|^~\\&|ADT1|MCM\rPID|1||PATID1234^^^ADT1^MR")?;
    Redactor::new(Policy::patient_identifiers())
        .with_key(1)
        .redact(&mut other);
    assert_ne!(other.query("PID-3.1")?.expect("a value"), one);

    // The function is available directly, for building an expected value
    // in a test.
    assert_eq!(pseudonym(KEY, "PATID1234"), one);

    // What it costs. A pseudonym preserves equality on purpose, so anyone
    // holding the redacted data can count how many messages each patient
    // generated — and anyone holding the key can invert the mapping by
    // trying every candidate identifier, because record numbers come from
    // small spaces. Inside your own trust boundary, that is a fair trade;
    // for data leaving it, clear the value instead.
    let mut leaving = er7::parse("MSH|^~\\&|ADT1|MCM\rPID|1||PATID1234^^^ADT1^MR")?;
    let policy = Policy::patient_identifiers().with("PID-3.1", Action::Clear)?;
    Redactor::new(policy).redact(&mut leaving);
    assert_eq!(leaving.query("PID-3.1")?.as_deref(), Some(""));

    Ok(())
}

examples/write_a_policy.rs (line 52)

fn main() -> Result<(), er7_redact::Error> {
    // 1. Built in Rust, rule by rule. Order matters: rules apply in the
    //    order they are listed. `accept_all` is the starting point that
    //    redacts nothing until a rule says so — the other one is
    //    `reject_all`, which redacts everything until a `keep` rule says
    //    otherwise.
    let built = Policy::accept_all()
        .with("PID-3.1", Action::Pseudonym)?
        .with("PID-5", Action::redacted())?
        .with("PID-7", Action::First(4))?
        .with("PID-19", Action::Clear)?;

    // 2. Read from a policy file — the same thing, in the form a team
    //    reviews in a pull request.
    let read = Policy::parse(
        "
        PID-3.1  pseudonym    # keep linkage, lose the record number
        PID-5    replace REDACTED
        PID-7    first 4      # the birth year is enough for most tests
        PID-19   clear
        ",
    )?;
    assert_eq!(built.rules, read.rules);

    // Both accept by default: a position no rule names is left alone.
    assert_eq!(built.posture, Posture::Accept);
    assert_eq!(read.posture, Posture::Accept);

    // They differ on one thing, and it is worth knowing about. A payload
    // that is not ER7 at all has no positions in it, so no rule can speak
    // to it. `accept_all` passes one through, because it is a policy that
    // redacts nothing and says so. A policy *file* that mentions no
    // disposition refuses one instead: it was written by somebody who may
    // simply not have considered the case, and refusing loses no value
    // quietly.
    assert_eq!(built.unrecognised, Unrecognised::Pass);
    assert_eq!(read.unrecognised, Unrecognised::Refuse);

    // Either way, say it outright and the two agree.
    let built = built.on_unrecognised(Unrecognised::Refuse);
    assert_eq!(built, read);

    // 3. Start from a built-in and add to it. `--show-policy` on the
    //    command line writes the built-in out as a file to edit.
    let extended = Policy::patient_identifiers()
        .with("NTE-3", Action::Clear)? // free text: nothing positional finds what is in here
        .with("OBX-5", Action::Clear)?;
    assert_eq!(
        extended.rules.len(),
        Policy::patient_identifiers().rules.len() + 2
    );

    // A policy writes itself back out in the file format, so the one that
    // ran can be recorded beside the message it redacted.
    println!("{built}");
    assert_eq!(Policy::parse(&built.to_string())?, built);

    let text = "MSH|^~\\&|LAB\rPID|1||PATID1234||EVERYWOMAN^EVE||19610615|F";
    let mut message = er7::parse(text)?;
    Redactor::new(built).redact(&mut message);
    assert_eq!(message.query("PID-5.1")?.as_deref(), Some("REDACTED"));

    // A malformed policy is rejected at load time, with the line number:
    // a typo here means a value that silently was not redacted.
    let error = Policy::parse("PID-5 obfuscate").unwrap_err();
    println!("{error}");
    assert!(error.to_string().contains("policy line 1"));

    Ok(())
}

pub fn all_but_the_header() -> Policy

The other posture, curated: reject every value, and keep the MSH header so the message stays routable (spec §5.2).

Use it when the message is unfamiliar, or when the answer to “is there anything else in here?” has to be “no” rather than “not that I listed”. The cost is that nothing below MSH is clinically meaningful afterwards; add Keep rules for what a test needs.

Like Policy::patient_identifiers it refuses a payload that is not ER7 rather than guessing (spec §2.8).

The header exception is an ordinary accept rule, so an ordinary reject rule overrides it (D19) — .with("MSH", Action::redacted()) takes the header too.

Example:

use er7_redact::{Action, Policy, Redactor};

let policy = Policy::all_but_the_header().with("OBX-2", Action::Keep)?;
let mut message = er7::parse("MSH|^~\\&|LAB\rOBX|1|NM|2093-3||187")?;
Redactor::new(policy).redact(&mut message);

assert_eq!(
    message.to_er7(),
    "MSH|^~\\&|LAB\rOBX|REDACTED|NM|REDACTED||REDACTED",
);

Panics

Only if the MSH literal below stops being an HL7 path, which no caller can cause.

Examples found in repository

examples/reject_by_default.rs (line 21)

fn main() -> Result<(), er7_redact::Error> {
    let text = "MSH|^~\\&|LAB|ACME|EHR|CLINIC|20260815120000||ORU^R01|MSG9|P|2.5\r\
                PID|1||PATID1234||EVERYWOMAN^EVE||19610615|F\r\
                OBX|1|NM|2093-3^Cholesterol^LN||187|mg/dL|100-199|H|||F\r\
                ZPD|1|LOCAL^EXTENSION^SEGMENT";

    // Rejecting by default covers every leaf no rule named; a `keep` rule
    // accepts a position, exempting it from that. A rejecting rule would
    // beat the `keep` whichever order the two were written in (D19).
    let policy = Policy::all_but_the_header()
        .with("OBX-2", Action::Keep)? // value type
        .with("OBX-3", Action::Keep)? // observation identifier
        .with("OBX-5", Action::Keep)? // the number the test asserts on
        .with("OBX-6", Action::Keep)?; // units

    let mut message = er7::parse(text)?;
    let report = Redactor::new(policy).redact(&mut message);
    println!("{}\n", message.to_er7().replace('\r', "\n"));

    // The header is untouched, so the message still routes and still says
    // which version it is.
    assert_eq!(message.query("MSH-9")?.as_deref(), Some("ORU^R01"));
    assert_eq!(message.version().as_deref(), Some("2.5"));

    // The result is intact, because four rules said so.
    assert_eq!(message.query("OBX-3.2")?.as_deref(), Some("Cholesterol"));
    assert_eq!(message.query("OBX-5")?.as_deref(), Some("187"));

    // Everything else is gone — including the local segment, which no
    // curated policy could have known about.
    assert_eq!(message.query("PID-5.1")?.as_deref(), Some("REDACTED"));
    assert_eq!(message.query("ZPD-2.1")?.as_deref(), Some("REDACTED"));

    // The cost: values a positional policy would have kept are gone too.
    assert_eq!(message.query("PID-8")?.as_deref(), Some("REDACTED"));
    assert_eq!(message.query("OBX-8")?.as_deref(), Some("REDACTED"));

    println!("{} positions changed", report.len());

    // And what this posture is really for: a payload that is not ER7 at
    // all has no positions to name, so the policy says outright what
    // becomes of it. The curated policy above refuses one, which is what
    // makes the CLI exit non-zero rather than write it out.
    let redactor = Redactor::new(Policy::all_but_the_header());
    assert_eq!(redactor.unrecognised("{\"name\": \"EVERYWOMAN\"}"), None);

    // `Policy::reject_all` masks it whole instead — nothing routable
    // survives, and neither does anything else.
    let redactor = Redactor::new(Policy::reject_all());
    assert_eq!(
        redactor.unrecognised("EVERYWOMAN").as_deref(),
        Some("**********")
    );
    Ok(())
}

pub fn with(self, path: &str, action: Action) -> Result<Policy, Error>

Add a rule, for building a policy in one expression.

Errors

Error::Er7 when path is not an HL7 path; see Rule::new.

Examples found in repository

examples/pseudonyms_and_linkage.rs (line 57)

fn main() -> Result<(), er7_redact::Error> {
    let admit = "MSH|^~\\&|ADT1|MCM||||||ADT^A01|MSG1|P|2.5\r\
                 PID|1||PATID1234^^^ADT1^MR||EVERYWOMAN^EVE";
    let result = "MSH|^~\\&|LAB|ACME||||||ORU^R01|MSG2|P|2.5\r\
                  PID|1||PATID1234^^^ADT1^MR||EVERYWOMAN^EVE\r\
                  OBX|1|NM|2093-3^Cholesterol^LN||187";

    let redactor = Redactor::new(Policy::patient_identifiers()).with_key(KEY);

    let mut admit = er7::parse(admit)?;
    let mut result = er7::parse(result)?;
    redactor.redact(&mut admit);
    redactor.redact(&mut result);

    // The record number is gone from both...
    let one = admit.query("PID-3.1")?.expect("a value");
    let two = result.query("PID-3.1")?.expect("a value");
    assert_ne!(one, "PATID1234");

    // ...and the two messages still agree that this is the same patient,
    // which is what makes them useful as a test case.
    assert_eq!(one, two);
    println!("both messages now say PID-3.1 = {one}");

    // A different key produces an unrelated mapping, so two data sets
    // redacted under different keys cannot be joined.
    let mut other = er7::parse("MSH|^~\\&|ADT1|MCM\rPID|1||PATID1234^^^ADT1^MR")?;
    Redactor::new(Policy::patient_identifiers())
        .with_key(1)
        .redact(&mut other);
    assert_ne!(other.query("PID-3.1")?.expect("a value"), one);

    // The function is available directly, for building an expected value
    // in a test.
    assert_eq!(pseudonym(KEY, "PATID1234"), one);

    // What it costs. A pseudonym preserves equality on purpose, so anyone
    // holding the redacted data can count how many messages each patient
    // generated — and anyone holding the key can invert the mapping by
    // trying every candidate identifier, because record numbers come from
    // small spaces. Inside your own trust boundary, that is a fair trade;
    // for data leaving it, clear the value instead.
    let mut leaving = er7::parse("MSH|^~\\&|ADT1|MCM\rPID|1||PATID1234^^^ADT1^MR")?;
    let policy = Policy::patient_identifiers().with("PID-3.1", Action::Clear)?;
    Redactor::new(policy).redact(&mut leaving);
    assert_eq!(leaving.query("PID-3.1")?.as_deref(), Some(""));

    Ok(())
}

examples/redact_absent_empty_null.rs (line 17)

fn main() -> Result<(), er7_redact::Error> {
    // PID-1 has a value, PID-2 was sent blank, PID-3 is the explicit null,
    // and PID-4 onwards was never sent at all.
    let text = "MSH|^~\\&|LAB\rPID|1||\"\"";

    let policy = Policy::accept_all()
        .with("PID-1", Action::redacted())?
        .with("PID-2", Action::redacted())?
        .with("PID-3", Action::redacted())?
        .with("PID-9", Action::redacted())?;

    let mut message = er7::parse(text)?;
    let report = Redactor::new(policy).redact(&mut message);

    // Only the field that carried a value changed.
    assert_eq!(message.to_er7(), "MSH|^~\\&|LAB\rPID|REDACTED||\"\"");
    assert_eq!(report.len(), 1);

    // Why each of the other three was left alone:
    //
    // PID-2 was empty. Writing REDACTED into it would invent a value, and
    // would announce that one used to be there — which is a disclosure.
    assert!(message.segment("PID").unwrap().field(2).unwrap().is_empty());
    //
    // PID-3 is the explicit null: an instruction to the receiver to clear
    // its stored value, not patient data. Overwriting it would turn
    // "clear this" into a value, and leave a withdrawn record standing.
    assert!(message.segment("PID").unwrap().field(3).unwrap().is_null());
    //
    // PID-9 was never sent. Redaction does not lengthen a segment to reach
    // a position that is not there: padding would change what the message
    // says, and eleven new trailing pipes would announce the redaction.
    assert!(message.segment("PID").unwrap().field(9).is_none());

    // To *make* a position null — to tell the receiver to clear it — ask
    // for that, which is the one action that changes the shape of a
    // message, because an HL7 null is a single `""`.
    let mut message = er7::parse("MSH|^~\\&|LAB\rPID|1||9||SMITH^JOHN")?;
    let policy = Policy::accept_all().with("PID-5", Action::Null)?;
    Redactor::new(policy).redact(&mut message);
    assert_eq!(message.to_er7(), "MSH|^~\\&|LAB\rPID|1||9||\"\"");

    // Compare with `clear`, which says nothing rather than saying "delete".
    let mut message = er7::parse("MSH|^~\\&|LAB\rPID|1||9||SMITH^JOHN")?;
    let policy = Policy::accept_all().with("PID-5", Action::Clear)?;
    Redactor::new(policy).redact(&mut message);
    assert_eq!(message.to_er7(), "MSH|^~\\&|LAB\rPID|1||9||^");

    println!("absent, empty, and null all survived redaction unchanged");
    Ok(())
}

examples/reject_by_default.rs (line 22)

fn main() -> Result<(), er7_redact::Error> {
    let text = "MSH|^~\\&|LAB|ACME|EHR|CLINIC|20260815120000||ORU^R01|MSG9|P|2.5\r\
                PID|1||PATID1234||EVERYWOMAN^EVE||19610615|F\r\
                OBX|1|NM|2093-3^Cholesterol^LN||187|mg/dL|100-199|H|||F\r\
                ZPD|1|LOCAL^EXTENSION^SEGMENT";

    // Rejecting by default covers every leaf no rule named; a `keep` rule
    // accepts a position, exempting it from that. A rejecting rule would
    // beat the `keep` whichever order the two were written in (D19).
    let policy = Policy::all_but_the_header()
        .with("OBX-2", Action::Keep)? // value type
        .with("OBX-3", Action::Keep)? // observation identifier
        .with("OBX-5", Action::Keep)? // the number the test asserts on
        .with("OBX-6", Action::Keep)?; // units

    let mut message = er7::parse(text)?;
    let report = Redactor::new(policy).redact(&mut message);
    println!("{}\n", message.to_er7().replace('\r', "\n"));

    // The header is untouched, so the message still routes and still says
    // which version it is.
    assert_eq!(message.query("MSH-9")?.as_deref(), Some("ORU^R01"));
    assert_eq!(message.version().as_deref(), Some("2.5"));

    // The result is intact, because four rules said so.
    assert_eq!(message.query("OBX-3.2")?.as_deref(), Some("Cholesterol"));
    assert_eq!(message.query("OBX-5")?.as_deref(), Some("187"));

    // Everything else is gone — including the local segment, which no
    // curated policy could have known about.
    assert_eq!(message.query("PID-5.1")?.as_deref(), Some("REDACTED"));
    assert_eq!(message.query("ZPD-2.1")?.as_deref(), Some("REDACTED"));

    // The cost: values a positional policy would have kept are gone too.
    assert_eq!(message.query("PID-8")?.as_deref(), Some("REDACTED"));
    assert_eq!(message.query("OBX-8")?.as_deref(), Some("REDACTED"));

    println!("{} positions changed", report.len());

    // And what this posture is really for: a payload that is not ER7 at
    // all has no positions to name, so the policy says outright what
    // becomes of it. The curated policy above refuses one, which is what
    // makes the CLI exit non-zero rather than write it out.
    let redactor = Redactor::new(Policy::all_but_the_header());
    assert_eq!(redactor.unrecognised("{\"name\": \"EVERYWOMAN\"}"), None);

    // `Policy::reject_all` masks it whole instead — nothing routable
    // survives, and neither does anything else.
    let redactor = Redactor::new(Policy::reject_all());
    assert_eq!(
        redactor.unrecognised("EVERYWOMAN").as_deref(),
        Some("**********")
    );
    Ok(())
}

examples/write_a_policy.rs (line 15)

fn main() -> Result<(), er7_redact::Error> {
    // 1. Built in Rust, rule by rule. Order matters: rules apply in the
    //    order they are listed. `accept_all` is the starting point that
    //    redacts nothing until a rule says so — the other one is
    //    `reject_all`, which redacts everything until a `keep` rule says
    //    otherwise.
    let built = Policy::accept_all()
        .with("PID-3.1", Action::Pseudonym)?
        .with("PID-5", Action::redacted())?
        .with("PID-7", Action::First(4))?
        .with("PID-19", Action::Clear)?;

    // 2. Read from a policy file — the same thing, in the form a team
    //    reviews in a pull request.
    let read = Policy::parse(
        "
        PID-3.1  pseudonym    # keep linkage, lose the record number
        PID-5    replace REDACTED
        PID-7    first 4      # the birth year is enough for most tests
        PID-19   clear
        ",
    )?;
    assert_eq!(built.rules, read.rules);

    // Both accept by default: a position no rule names is left alone.
    assert_eq!(built.posture, Posture::Accept);
    assert_eq!(read.posture, Posture::Accept);

    // They differ on one thing, and it is worth knowing about. A payload
    // that is not ER7 at all has no positions in it, so no rule can speak
    // to it. `accept_all` passes one through, because it is a policy that
    // redacts nothing and says so. A policy *file* that mentions no
    // disposition refuses one instead: it was written by somebody who may
    // simply not have considered the case, and refusing loses no value
    // quietly.
    assert_eq!(built.unrecognised, Unrecognised::Pass);
    assert_eq!(read.unrecognised, Unrecognised::Refuse);

    // Either way, say it outright and the two agree.
    let built = built.on_unrecognised(Unrecognised::Refuse);
    assert_eq!(built, read);

    // 3. Start from a built-in and add to it. `--show-policy` on the
    //    command line writes the built-in out as a file to edit.
    let extended = Policy::patient_identifiers()
        .with("NTE-3", Action::Clear)? // free text: nothing positional finds what is in here
        .with("OBX-5", Action::Clear)?;
    assert_eq!(
        extended.rules.len(),
        Policy::patient_identifiers().rules.len() + 2
    );

    // A policy writes itself back out in the file format, so the one that
    // ran can be recorded beside the message it redacted.
    println!("{built}");
    assert_eq!(Policy::parse(&built.to_string())?, built);

    let text = "MSH|^~\\&|LAB\rPID|1||PATID1234||EVERYWOMAN^EVE||19610615|F";
    let mut message = er7::parse(text)?;
    Redactor::new(built).redact(&mut message);
    assert_eq!(message.query("PID-5.1")?.as_deref(), Some("REDACTED"));

    // A malformed policy is rejected at load time, with the line number:
    // a typo here means a value that silently was not redacted.
    let error = Policy::parse("PID-5 obfuscate").unwrap_err();
    println!("{error}");
    assert!(error.to_string().contains("policy line 1"));

    Ok(())
}

pub fn posture(self, posture: Posture) -> Policy

Set what every leaf no rule named gets (spec §2.6).

Posture::Reject with Action::Keep is normalised to Posture::Accept, so that the policy file’s reject keep and this method agree about what they mean.

This is the only way to make a policy less strict: appending one policy to another never weakens it (D20, Policy::append).

pub fn on_unrecognised(self, unrecognised: Unrecognised) -> Policy

Set what a payload that is not ER7 gets (spec §2.8).

Unrecognised::Apply with an action that writes nothing — Action::Keep or Action::Null — is normalised to Unrecognised::Pass, which is what it does.

Examples found in repository

examples/write_a_policy.rs (line 47)

fn main() -> Result<(), er7_redact::Error> {
    // 1. Built in Rust, rule by rule. Order matters: rules apply in the
    //    order they are listed. `accept_all` is the starting point that
    //    redacts nothing until a rule says so — the other one is
    //    `reject_all`, which redacts everything until a `keep` rule says
    //    otherwise.
    let built = Policy::accept_all()
        .with("PID-3.1", Action::Pseudonym)?
        .with("PID-5", Action::redacted())?
        .with("PID-7", Action::First(4))?
        .with("PID-19", Action::Clear)?;

    // 2. Read from a policy file — the same thing, in the form a team
    //    reviews in a pull request.
    let read = Policy::parse(
        "
        PID-3.1  pseudonym    # keep linkage, lose the record number
        PID-5    replace REDACTED
        PID-7    first 4      # the birth year is enough for most tests
        PID-19   clear
        ",
    )?;
    assert_eq!(built.rules, read.rules);

    // Both accept by default: a position no rule names is left alone.
    assert_eq!(built.posture, Posture::Accept);
    assert_eq!(read.posture, Posture::Accept);

    // They differ on one thing, and it is worth knowing about. A payload
    // that is not ER7 at all has no positions in it, so no rule can speak
    // to it. `accept_all` passes one through, because it is a policy that
    // redacts nothing and says so. A policy *file* that mentions no
    // disposition refuses one instead: it was written by somebody who may
    // simply not have considered the case, and refusing loses no value
    // quietly.
    assert_eq!(built.unrecognised, Unrecognised::Pass);
    assert_eq!(read.unrecognised, Unrecognised::Refuse);

    // Either way, say it outright and the two agree.
    let built = built.on_unrecognised(Unrecognised::Refuse);
    assert_eq!(built, read);

    // 3. Start from a built-in and add to it. `--show-policy` on the
    //    command line writes the built-in out as a file to edit.
    let extended = Policy::patient_identifiers()
        .with("NTE-3", Action::Clear)? // free text: nothing positional finds what is in here
        .with("OBX-5", Action::Clear)?;
    assert_eq!(
        extended.rules.len(),
        Policy::patient_identifiers().rules.len() + 2
    );

    // A policy writes itself back out in the file format, so the one that
    // ran can be recorded beside the message it redacted.
    println!("{built}");
    assert_eq!(Policy::parse(&built.to_string())?, built);

    let text = "MSH|^~\\&|LAB\rPID|1||PATID1234||EVERYWOMAN^EVE||19610615|F";
    let mut message = er7::parse(text)?;
    Redactor::new(built).redact(&mut message);
    assert_eq!(message.query("PID-5.1")?.as_deref(), Some("REDACTED"));

    // A malformed policy is rejected at load time, with the line number:
    // a typo here means a value that silently was not redacted.
    let error = Policy::parse("PID-5 obfuscate").unwrap_err();
    println!("{error}");
    assert!(error.to_string().contains("policy line 1"));

    Ok(())
}

pub fn parse(text: &str) -> Result<Policy, Error>

Read a policy file (spec §6).

Blank lines and # comments are ignored; every other line is either a path, whitespace, and an action, in the order they apply, or one of the three reserved first words — accept, reject, and unrecognised — that set what the policy does by default.

A file that states no defaults accepts by default and refuses a payload that is not ER7: unlike Policy::accept_all, a file was written by somebody who may simply not have considered one, and refusing is the answer that cannot lose a value quietly.

Example:

use er7_redact::{Action, Policy, Posture, Unrecognised};

let policy = Policy::parse("
    MSH    keep      # everything but the header...
    OBX-5  keep      # ...and the numbers the test asserts on

    reject replace REDACTED
    unrecognised mask *
")?;

assert_eq!(policy.rules.len(), 2);
assert_eq!(policy.posture, Posture::Reject(Action::redacted()));
assert_eq!(policy.unrecognised, Unrecognised::Apply(Action::Mask('*')));

// A file that says nothing accepts, and refuses what it cannot read.
let quiet = Policy::parse("PID-5 clear")?;
assert_eq!(quiet.posture, Posture::Accept);
assert_eq!(quiet.unrecognised, Unrecognised::Refuse);

// A malformed line names itself.
let e = Policy::parse("PID-5 obfuscate").unwrap_err();
assert_eq!(e.to_string(), "policy line 1: \"PID-5 obfuscate\": unknown action \"obfuscate\"");

Errors

Error::BadPolicy naming the line number, the line, and the problem. Reading a policy is the one place this crate is strict, because a typo means a value that silently was not redacted (spec §6.4).

Examples found in repository

examples/write_a_policy.rs (lines 22-29)

fn main() -> Result<(), er7_redact::Error> {
    // 1. Built in Rust, rule by rule. Order matters: rules apply in the
    //    order they are listed. `accept_all` is the starting point that
    //    redacts nothing until a rule says so — the other one is
    //    `reject_all`, which redacts everything until a `keep` rule says
    //    otherwise.
    let built = Policy::accept_all()
        .with("PID-3.1", Action::Pseudonym)?
        .with("PID-5", Action::redacted())?
        .with("PID-7", Action::First(4))?
        .with("PID-19", Action::Clear)?;

    // 2. Read from a policy file — the same thing, in the form a team
    //    reviews in a pull request.
    let read = Policy::parse(
        "
        PID-3.1  pseudonym    # keep linkage, lose the record number
        PID-5    replace REDACTED
        PID-7    first 4      # the birth year is enough for most tests
        PID-19   clear
        ",
    )?;
    assert_eq!(built.rules, read.rules);

    // Both accept by default: a position no rule names is left alone.
    assert_eq!(built.posture, Posture::Accept);
    assert_eq!(read.posture, Posture::Accept);

    // They differ on one thing, and it is worth knowing about. A payload
    // that is not ER7 at all has no positions in it, so no rule can speak
    // to it. `accept_all` passes one through, because it is a policy that
    // redacts nothing and says so. A policy *file* that mentions no
    // disposition refuses one instead: it was written by somebody who may
    // simply not have considered the case, and refusing loses no value
    // quietly.
    assert_eq!(built.unrecognised, Unrecognised::Pass);
    assert_eq!(read.unrecognised, Unrecognised::Refuse);

    // Either way, say it outright and the two agree.
    let built = built.on_unrecognised(Unrecognised::Refuse);
    assert_eq!(built, read);

    // 3. Start from a built-in and add to it. `--show-policy` on the
    //    command line writes the built-in out as a file to edit.
    let extended = Policy::patient_identifiers()
        .with("NTE-3", Action::Clear)? // free text: nothing positional finds what is in here
        .with("OBX-5", Action::Clear)?;
    assert_eq!(
        extended.rules.len(),
        Policy::patient_identifiers().rules.len() + 2
    );

    // A policy writes itself back out in the file format, so the one that
    // ran can be recorded beside the message it redacted.
    println!("{built}");
    assert_eq!(Policy::parse(&built.to_string())?, built);

    let text = "MSH|^~\\&|LAB\rPID|1||PATID1234||EVERYWOMAN^EVE||19610615|F";
    let mut message = er7::parse(text)?;
    Redactor::new(built).redact(&mut message);
    assert_eq!(message.query("PID-5.1")?.as_deref(), Some("REDACTED"));

    // A malformed policy is rejected at load time, with the line number:
    // a typo here means a value that silently was not redacted.
    let error = Policy::parse("PID-5 obfuscate").unwrap_err();
    println!("{error}");
    assert!(error.to_string().contains("policy line 1"));

    Ok(())
}

pub fn append(&mut self, other: Policy)

Append another policy’s rules, take the stricter posture, and take the appended policy’s disposition for an unrecognised payload (D20, spec §2.6).

This is how the command line concatenates several --policy files and --rule arguments; order is significant for the rules (D7).

The posture cannot be weakened by appending, and deliberately: a file of extra rules says nothing about its posture, so it accepts by default, and adopting that would switch redaction off for everything the file did not name. Silence is indistinguishable from a decision, so silence is not trusted. To relax a posture, say so with Policy::posture.

The disposition for an unrecognised payload is different, and the appended policy’s wins outright. Nothing is silent there: Policy::parse gives a file that says nothing the strictest disposition there is, Unrecognised::Refuse, so every value one carries is somebody’s decision — and a file that goes to the trouble of writing unrecognised pass should not be quietly overruled by a default it never saw.

Example:

use er7_redact::{Action, Policy, Posture};

let mut policy = Policy::all_but_the_header();
policy.append(Policy::parse("OBX-2 keep")?);

// The appended file accepts by default; the strict policy still rejects.
assert_eq!(policy.posture, Posture::Reject(Action::redacted()));

// And a stricter action in the appended policy does win.
policy.append(Policy::parse("reject clear")?);
assert_eq!(policy.posture, Posture::Reject(Action::Clear));

pub fn is_empty(&self) -> bool

True when the policy would redact nothing at all: no rules, and it accepts by default.

What it does with an unrecognised payload is not part of this: a policy that refuses one still redacts nothing.

Trait Implementations

impl Clone for Policy

fn clone(&self) -> Policy

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Policy

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Policy

fn fmt(&self, f: &mut Formatter<'_>) -> Result

The canonical policy file (spec §6.5): one rule per line, paths padded to a common width, then the two default lines — always both, whatever they say, so that a reader never has to know which default was the quiet one.

Example:

use er7_redact::{Action, Policy};

let policy = Policy::accept_all()
    .with("PID-5", Action::redacted())?
    .with("PID-7", Action::First(4))?
    .posture(er7_redact::Posture::Reject(Action::Clear));

assert_eq!(policy.to_string(), "\
PID-5  replace REDACTED
PID-7  first 4

reject        clear
unrecognised  pass
");

// And it reads back as the same policy.
assert_eq!(Policy::parse(&policy.to_string())?, policy);

impl Eq for Policy

impl PartialEq for Policy

fn eq(&self, other: &Policy) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Policy