Enum Action 

pub enum Action {
    Keep,
    Clear,
    Null,
    Replace(String),
    Mask(char),
    First(usize),
    Last(usize),
    Pseudonym,
}

What to do to a value the policy selected.

Every variant except Action::Null rewrites leaf text and leaves the shape of the message alone (D1); Null collapses the position it names to the explicit HL7 null, because that is what a null means (D6, spec §3.4).

Example:

use er7_redact::Action;

// Applied to a decoded value, with the pseudonym key.
assert_eq!(Action::redacted().apply("EVERYWOMAN", 0).as_deref(), Some("REDACTED"));
assert_eq!(Action::Mask('*').apply("EVERYWOMAN", 0).as_deref(), Some("**********"));
assert_eq!(Action::First(4).apply("19610615", 0).as_deref(), Some("1961"));
assert_eq!(Action::Last(4).apply("444333222", 0).as_deref(), Some("3222"));
assert_eq!(Action::Clear.apply("EVERYWOMAN", 0).as_deref(), Some(""));

// `Keep` changes nothing, and so returns nothing to write.
assert_eq!(Action::Keep.apply("EVERYWOMAN", 0), None);

Variants

Keep

Leave the value exactly as it is.

This is the action that accepts a position: its use is to exempt one from a policy that rejects by default (spec §2.6).

It does not undo an earlier rule: rules apply in order to the message as it stands, so once a value has been replaced there is nothing left to restore it from (D7, spec §2.4). That is also why a rejecting rule beats a Keep for the same leaf whichever order the two are in (D19).

Clear

Empty the value, leaving the position in place.

This is what redaction usually means. A receiver reads an empty field as “the sender said nothing about this”, which leaves its stored value alone — see Action::Null for the other reading.

Null

Replace the named position with the explicit HL7 null "".

A receiver reads this as “clear your stored value”, which is a different instruction from Action::Clear and a much stronger one. It is also the only action that changes the shape of a message: everything beneath the named position is replaced by one subcomponent holding "" (D6, spec §3.4).

Replace(String)

Replace the value with fixed text, e.g. REDACTED.

Delimiters in the text are encoded on the way in, so a replacement can never break the message (D11).

Mask(char)

Replace each character of the value with this one, preserving the length.

The length is exactly what this leaks; use Action::Clear or Action::Replace where that matters (spec §5.5).

First(usize)

Keep the first n characters and drop the rest — a birth date reduced to its year, say. First(0) is legal and equivalent to Action::Clear (spec §3.7).

Last(usize)

Keep the last n characters and drop the rest — an account number reduced to the digits a human matches on.

Pseudonym

Replace the value with a stable pseudonym, so that equal values stay equal across every message redacted with the same key.

Read crate::pseudonym() before using this: a pseudonym preserves linkage on purpose, and it is not a cryptographic guarantee (D12, spec §7.3).

Implementations

impl Action

pub fn redacted() -> Action

Action::Replace with the placeholder the built-in policies use.

Example:

use er7_redact::Action;

assert_eq!(Action::redacted(), Action::Replace("REDACTED".to_string()));
assert_eq!(Action::redacted().to_string(), "replace REDACTED");

Examples found in repository

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/write_a_policy.rs (line 16)

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<Action, Error>

Read an action as a policy file spells it (spec §6.2).

The action name is matched case-insensitively; an argument, where one is allowed, is the rest of the text as written.

Example:

use er7_redact::Action;

assert_eq!(Action::parse("clear")?, Action::Clear);
assert_eq!(Action::parse("first 4")?, Action::First(4));
assert_eq!(Action::parse("replace NOT ON FILE")?,
           Action::Replace("NOT ON FILE".to_string()));

// The two arguments that may be left out have a default.
assert_eq!(Action::parse("replace")?, Action::redacted());
assert_eq!(Action::parse("mask")?, Action::Mask('*'));

assert!(Action::parse("obfuscate").is_err());
assert!(Action::parse("first three").is_err());

Errors

Error::BadPolicy naming the problem: an unknown action name, an argument where none belongs, a mask argument that is not one character, or a first/last count that is not a number (spec §6.4).

pub fn apply(&self, value: &str, key: u64) -> Option<String>

The text this action writes in place of value, or None to leave the value alone.

value is the leaf’s decoded text, and key is the redactor’s pseudonym key, used only by Action::Pseudonym.

Action::Keep returns None because it writes nothing, and so does Action::Null, which the redactor applies structurally rather than as text (spec §3.4).

Example:

use er7_redact::Action;

// Counting is by character, so an escape that stands for one
// character counts as one.
assert_eq!(Action::First(3).apply("O'BRIEN", 0).as_deref(), Some("O'B"));

// Asking for more characters than there are is not an error.
assert_eq!(Action::First(99).apply("MR", 0).as_deref(), Some("MR"));
assert_eq!(Action::Last(99).apply("MR", 0).as_deref(), Some("MR"));

Trait Implementations

impl Clone for Action

fn clone(&self) -> Action

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Action

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

Formats the value using the given formatter.

impl Display for Action

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

The spelling a policy file uses, so that a policy written out re-reads as the same policy (D18, spec §6.5).

The one value that does not survive the trip is Replace with empty text, written as clear, because nothing downstream can tell the two apart.

Example:

use er7_redact::Action;

assert_eq!(Action::Pseudonym.to_string(), "pseudonym");
assert_eq!(Action::First(4).to_string(), "first 4");
assert_eq!(Action::Mask('#').to_string(), "mask #");
assert_eq!(Action::Replace(String::new()).to_string(), "clear");

impl Eq for Action

impl PartialEq for Action

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for Action