ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
//! The PROTOCOL WRITER, at the token level — what each word turns the call into.
//!
//! These are about the CALL SHAPE and nothing else: the writer is handed values that are already
//! crossed, so nothing here has an opinion about the bridge. The manifest half — which column takes
//! which seat, and how a value crosses — is `crate::remote`'s, pinned beside its own golden; the
//! whole device compiled against real upstream types is
//! `ingraph-derive/tests/construction_protocols.rs`.

use quote::{format_ident, quote};

use super::{Construction, Filled, Injection, Seat, Supplied};

/// The host every call below is written on.
fn host() -> syn::Path {
  syn::parse_quote!(upstream::Frame)
}

/// One supplied value, ungated, under the seat a column named.
fn at(seat: &Seat, column: &str, value: &str) -> Supplied {
  let column = format_ident!("{column}");
  let value: syn::Expr = syn::parse_str(value).expect("an expression");
  Supplied {
    fill: seat.filled(&column),
    gate: proc_macro2::TokenStream::new(),
    value: quote!(#value),
  }
}

/// The call as a reader would see it, with `syn`'s spacing normalised out of the assertion.
fn written(construction: &Construction, supplied: &[Supplied]) -> String {
  construction
    .call(&host(), supplied)
    .to_string()
    .replace(' ', "")
}

/// **THE CONSTRUCTOR** — no `finish`, so the entry hands back the value and the links are on it.
#[test]
fn a_protocol_with_no_closing_call_is_a_chain_on_the_entry() {
  let call = written(
    &Construction::default(),
    &[
      at(&Seat::Arg, "id", "row.id"),
      at(&Seat::With(None), "note", "row.note"),
    ],
  );
  assert_eq!(call, "upstream::Frame::new(row.id).with_note(row.note)");
}

/// **AN ALIAS FOR THE ENTRY** — one word moves the first call and nothing else.
#[test]
fn the_entry_word_moves_the_first_call_only() {
  let construction = Construction {
    entry: format_ident!("from_ratio"),
    ..Construction::default()
  };
  let call = written(&construction, &[at(&Seat::Arg, "id", "row.id")]);
  assert_eq!(call, "upstream::Frame::from_ratio(row.id)");
}

/// **THE BUILDER** — a `finish` turns the entry into an opening and the last call into a close, and
/// `finish_arg` fills the second argument list.
#[test]
fn a_closing_call_gives_the_protocol_a_second_argument_list() {
  let construction = Construction {
    entry: format_ident!("builder"),
    finish: Some(format_ident!("build")),
    ..Construction::default()
  };
  let call = written(
    &construction,
    &[
      at(
        &Seat::With(Some(format_ident!("width"))),
        "width",
        "row.width",
      ),
      at(&Seat::FinishArg, "unit", "row.unit"),
    ],
  );
  assert_eq!(
    call,
    "upstream::Frame::builder().width(row.width).build(row.unit)"
  );
}

/// **THE TRY SHAPE.** The `?` rides the step that YIELDS THE VALUE — the finish where there is one,
/// and the entry where the entry is the whole protocol.
#[test]
fn the_fallible_word_marks_the_terminal_step_and_only_that_one() {
  let constructor = Construction {
    fallible: true,
    ..Construction::default()
  };
  assert_eq!(
    written(&constructor, &[at(&Seat::Arg, "id", "row.id")]),
    "upstream::Frame::new(row.id)?"
  );

  let builder = Construction {
    entry: format_ident!("builder"),
    finish: Some(format_ident!("build")),
    fallible: true,
    ..Construction::default()
  };
  assert_eq!(
    written(&builder, &[at(&Seat::FinishArg, "id", "row.id")]),
    "upstream::Frame::builder().build(row.id)?",
    "the opening is not the step that can fail"
  );
}

/// **THE SETTER UNROLLS THE CHAIN.** A `&mut` method is a statement whatever else the protocol
/// does, so the writer binds the value and the device raises its own `mut`.
#[test]
fn an_in_place_setter_binds_the_value_and_mutates_it() {
  let call = written(
    &Construction::default(),
    &[
      at(&Seat::Arg, "id", "row.id"),
      at(&Seat::Set(None), "tint", "row.tint"),
    ],
  );
  assert_eq!(
    call,
    "{letmut__ingraph_built=upstream::Frame::new(row.id);\
     {__ingraph_built.set_tint(row.tint);}__ingraph_built}"
  );
}

/// A CONSUMING link inside the unrolled form is an assignment rather than a statement, which is the
/// difference between the two seat words spelled out in tokens.
#[test]
fn a_gated_link_unrolls_and_keeps_its_gate_on_a_statement() {
  let call = written(
    &Construction::default(),
    &[
      at(&Seat::Arg, "id", "row.id"),
      Supplied {
        gate: quote!(#[cfg(feature = "x")]),
        ..at(&Seat::With(None), "note", "row.note")
      },
    ],
  );
  assert_eq!(
    call,
    "{letmut__ingraph_built=upstream::Frame::new(row.id);\
     #[cfg(feature=\"x\")]{__ingraph_built=__ingraph_built.with_note(row.note);}__ingraph_built}"
  );
}

/// A gated REQUIRED column stays in the argument list, an attribute being legal there — which is
/// why the writer does not unroll for one.
#[test]
fn a_gated_argument_rides_the_argument_list() {
  let call = written(
    &Construction::default(),
    &[
      at(&Seat::Arg, "id", "row.id"),
      Supplied {
        gate: quote!(#[cfg(unix)]),
        ..at(&Seat::Arg, "width", "row.width")
      },
    ],
  );
  assert_eq!(call, "upstream::Frame::new(row.id,#[cfg(unix)]row.width)");
}

/// **THE INJECTIONS** — links no column feeds, after every column's, in the order written.
#[test]
fn an_injection_lands_after_the_columns_in_the_order_it_was_written() {
  let construction = Construction {
    calls: vec![
      Injection {
        method: format_ident!("with_unit"),
        value: syn::parse_quote!(Unit::Pixels),
      },
      Injection {
        method: format_ident!("with_scale"),
        value: syn::parse_quote!(2),
      },
    ],
    ..Construction::default()
  };
  assert_eq!(
    written(&construction, &[at(&Seat::With(None), "note", "row.note")]),
    "upstream::Frame::new().with_note(row.note).with_unit(Unit::Pixels).with_scale(2)"
  );
}

/// An injection survives the unrolling, which is the case a chain-only implementation would drop.
#[test]
fn an_injection_survives_the_statement_form() {
  let construction = Construction {
    calls: vec![Injection {
      method: format_ident!("with_unit"),
      value: syn::parse_quote!(Unit::Pixels),
    }],
    ..Construction::default()
  };
  let call = written(&construction, &[at(&Seat::Set(None), "tint", "row.tint")]);
  assert_eq!(
    call,
    "{letmut__ingraph_built=upstream::Frame::new();\
     {__ingraph_built.set_tint(row.tint);}\
     __ingraph_built=__ingraph_built.with_unit(Unit::Pixels);__ingraph_built}"
  );
}

/// The two seat words rename independently, and each default is the options family's own.
#[test]
fn a_renamed_seat_spells_the_name_it_was_given() {
  let renamed = Seat::With(Some(format_ident!("maybe_note")));
  assert!(
    matches!(renamed.filled(&format_ident!("note")), Filled::Link(name) if name == "maybe_note")
  );
  assert!(
    matches!(Seat::With(None).filled(&format_ident!("note")), Filled::Link(name) if name == "with_note")
  );
  assert!(
    matches!(Seat::Set(None).filled(&format_ident!("note")), Filled::Setter(name) if name == "set_note")
  );
}

/// A blanket claims a type by its SPELLING, which is the only comparison a macro has.
#[test]
fn a_blanket_claims_the_type_it_names_and_no_other() {
  let construction = Construction {
    blanket: vec![super::Blanket {
      ty: syn::parse_quote!(Option<u8>),
    }],
    ..Construction::default()
  };
  assert!(construction.blankets(&syn::parse_quote!(Option<u8>)));
  assert!(!construction.blankets(&syn::parse_quote!(Option<u16>)));
  assert!(!construction.blankets(&syn::parse_quote!(u8)));
}