Struct Redactor 

pub struct Redactor { /* private fields */ }

A policy, plus the key its pseudonyms are derived from.

Example:

use er7_redact::{Policy, Redactor};

let text = "MSH|^~\\&|LAB\rPID|1||PATID1234||EVERYWOMAN^EVE||19610615|F";
let mut message = er7::parse(text)?;

let redactor = Redactor::new(Policy::patient_identifiers()).with_key(42);
let report = redactor.redact(&mut message);

assert_eq!(message.query("PID-5")?.as_deref(), Some("REDACTED^REDACTED"));
assert_eq!(message.query("PID-7")?.as_deref(), Some("1961"));
assert_eq!(report.len(), 4);

// The same key maps the same identifier the same way, in every message.
let mut other = er7::parse("MSH|^~\\&|LAB\rPID|1||PATID1234")?;
redactor.redact(&mut other);
assert_eq!(other.query("PID-3")?, message.query("PID-3")?);

Implementations

impl Redactor

pub fn new(policy: Policy) -> Redactor

A redactor for this policy, with the default pseudonym key 0.

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/redact_absent_empty_null.rs (line 23)

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 28)

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 67)

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 with_key(self, key: u64) -> Redactor

Set the pseudonym key (spec §7.2).

Two data sets redacted under different keys share no pseudonyms and so cannot be joined; two under the same key can. The key is a number in a configuration file, not a managed secret — read spec §7.3 before treating it as one.

Examples found in repository

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

pub fn policy(&self) -> &Policy

The policy this redactor applies.

pub fn key(&self) -> u64

The pseudonym key.

pub fn unrecognised(&self, payload: &str) -> Option<String>

What to write in place of payload, which did not parse as ER7 (D21, spec §2.8).

None means the policy refuses it: nothing should be written, and the caller reports that the payload did not parse. That is not an error this crate raises — Redactor::redact cannot fail — so the caller decides what a refusal costs. The CLI makes it a diagnostic and exit 1 (spec §10.4).

Some(text) is the payload itself where the policy passes it through, or the policy’s action applied to the whole payload as if it were one value.

Example:

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

let junk = "not a message";

// The curated policies refuse a payload they cannot read.
assert_eq!(Redactor::default().unrecognised(junk), None);

// The bare postures each do what their name says.
assert_eq!(
    Redactor::new(Policy::accept_all()).unrecognised(junk).as_deref(),
    Some("not a message"),
);
assert_eq!(
    Redactor::new(Policy::reject_all()).unrecognised(junk).as_deref(),
    Some("*************"),
);

// And any of it is overridable.
let policy = Policy::accept_all().on_unrecognised(Unrecognised::Apply(Action::redacted()));
assert_eq!(
    Redactor::new(policy).unrecognised(junk).as_deref(),
    Some("REDACTED"),
);

Examples found in repository

examples/reject_by_default.rs (line 56)

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 redact(&self, message: &mut Message) -> Report

Redact message in place, and report what changed.

This cannot fail (spec §9.2): a rule that matches nothing does nothing, a position that is not there is not created, and an empty or null leaf is left alone.

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 25)

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 23)

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 28)

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 67)

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

Trait Implementations

impl Clone for Redactor

fn clone(&self) -> Redactor

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Redactor

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

Formats the value using the given formatter.

impl Default for Redactor

fn default() -> Redactor

The curated policy (Policy::patient_identifiers) with key 0 — the same thing the command line does when no policy is given.

impl Eq for Redactor

impl PartialEq for Redactor

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for Redactor