molframe_query/api/
builder.rs

1//! Compile-time checked Rust builder surface.
2
3use crate::ast::{Column, Expr, GeometricExpr, Macro, Operator};
4use std::ops::{BitAnd, BitOr, Not};
5
6/// A typed selection expression under construction.
7#[derive(Clone, PartialEq, Debug)]
8pub struct Builder {
9    expr: Expr,
10    source: Box<str>,
11}
12
13impl Builder {
14    /// Consumes the builder into the shared selection IR.
15    #[must_use]
16    pub(crate) fn into_parts(self) -> (Expr, Box<str>) {
17        (self.expr, self.source)
18    }
19
20    /// Canonical textual form accepted by the query parser.
21    #[must_use]
22    pub fn source(&self) -> &str {
23        &self.source
24    }
25
26    fn new(expr: Expr, source: impl Into<Box<str>>) -> Self {
27        Self {
28            expr,
29            source: source.into(),
30        }
31    }
32}
33
34impl BitAnd for Builder {
35    type Output = Self;
36
37    fn bitand(self, right: Self) -> Self::Output {
38        let source = format!("({}) and ({})", self.source, right.source);
39        Self::new(Expr::And(Box::new(self.expr), Box::new(right.expr)), source)
40    }
41}
42
43impl BitOr for Builder {
44    type Output = Self;
45
46    fn bitor(self, right: Self) -> Self::Output {
47        let source = format!("({}) or ({})", self.source, right.source);
48        Self::new(Expr::Or(Box::new(self.expr), Box::new(right.expr)), source)
49    }
50}
51
52impl Not for Builder {
53    type Output = Self;
54
55    fn not(self) -> Self::Output {
56        let source = format!("not ({})", self.source);
57        Self::new(Expr::Not(Box::new(self.expr)), source)
58    }
59}
60
61/// A typed column awaiting a predicate.
62#[derive(Clone, Copy, PartialEq, Eq, Debug)]
63pub struct ColumnBuilder(Column, &'static str);
64
65impl ColumnBuilder {
66    /// String or integer membership equality.
67    #[must_use]
68    pub fn eq(self, value: impl Into<Box<str>>) -> Builder {
69        let value = value.into();
70        Builder::new(
71            Expr::Membership {
72                column: self.0,
73                values: vec![value.clone()],
74            },
75            format!("{} {:?}", self.1, value),
76        )
77    }
78
79    /// Numeric less-than comparison.
80    #[must_use]
81    pub fn lt(self, value: f64) -> Builder {
82        self.compare(Operator::Less, value)
83    }
84
85    /// Numeric less-than-or-equal comparison.
86    #[must_use]
87    pub fn le(self, value: f64) -> Builder {
88        self.compare(Operator::LessEqual, value)
89    }
90
91    /// Numeric greater-than comparison.
92    #[must_use]
93    pub fn gt(self, value: f64) -> Builder {
94        self.compare(Operator::Greater, value)
95    }
96
97    /// Numeric greater-than-or-equal comparison.
98    #[must_use]
99    pub fn ge(self, value: f64) -> Builder {
100        self.compare(Operator::GreaterEqual, value)
101    }
102
103    fn compare(self, operator: Operator, value: f64) -> Builder {
104        let symbol = match operator {
105            Operator::Less => "<",
106            Operator::LessEqual => "<=",
107            Operator::Greater => ">",
108            Operator::GreaterEqual => ">=",
109            Operator::Equal => "=",
110            Operator::NotEqual => "!=",
111        };
112        Builder::new(
113            Expr::Comparison {
114                column: self.0,
115                operator,
116                value,
117                absolute: false,
118            },
119            format!("{} {symbol} {value}", self.1),
120        )
121    }
122}
123
124/// Builder functions sharing the textual parser's typed IR.
125pub mod col {
126    use super::{Builder, Column, ColumnBuilder, Expr, GeometricExpr, Macro};
127
128    /// Every atom.
129    #[must_use]
130    pub fn all() -> Builder {
131        Builder::new(Expr::All, "all")
132    }
133
134    /// No atoms.
135    #[must_use]
136    pub fn none() -> Builder {
137        Builder::new(Expr::None, "none")
138    }
139
140    /// Protein atoms.
141    #[must_use]
142    pub fn is_protein() -> Builder {
143        Builder::new(Expr::Macro(Macro::Protein), "protein")
144    }
145
146    macro_rules! molecular_selector {
147        ($name:ident, $variant:ident, $source:literal, $doc:literal) => {
148            #[doc = $doc]
149            #[must_use]
150            pub fn $name() -> Builder {
151                Builder::new(Expr::Macro(Macro::$variant), $source)
152            }
153        };
154    }
155
156    molecular_selector!(backbone, Backbone, "backbone", "Protein backbone atoms.");
157    molecular_selector!(
158        sidechain,
159        Sidechain,
160        "sidechain",
161        "Protein side-chain atoms."
162    );
163    molecular_selector!(nucleic, Nucleic, "nucleic", "Nucleic-acid atoms.");
164    molecular_selector!(
165        nucleic_backbone,
166        NucleicBackbone,
167        "nucleicbackbone",
168        "Nucleic-acid backbone atoms."
169    );
170    molecular_selector!(
171        nucleic_base,
172        NucleicBase,
173        "nucleicbase",
174        "Nucleic-acid base atoms."
175    );
176    molecular_selector!(
177        nucleic_sugar,
178        NucleicSugar,
179        "nucleicsugar",
180        "Nucleic-acid sugar atoms."
181    );
182    molecular_selector!(water, Water, "water", "Water atoms.");
183    molecular_selector!(ions, Ion, "ion", "Ion atoms.");
184    molecular_selector!(lipids, Lipid, "lipid", "Lipid atoms.");
185    molecular_selector!(glycans, Saccharide, "saccharide", "Saccharide atoms.");
186    molecular_selector!(hetero, Hetero, "hetero", "Heterogeneous atoms.");
187    molecular_selector!(hydrogen, Hydrogen, "hydrogen", "Hydrogen atoms.");
188    molecular_selector!(heavy, Heavy, "heavy", "Non-hydrogen atoms.");
189    molecular_selector!(polymer, Polymer, "polymer", "Polymer atoms.");
190    molecular_selector!(ligands, Ligand, "ligand", "Non-polymer ligand atoms.");
191    molecular_selector!(aromatic, Aromatic, "aromatic", "Aromatic atoms.");
192
193    /// Atom name column.
194    #[must_use]
195    pub const fn name() -> ColumnBuilder {
196        ColumnBuilder(Column::AtomName, "name")
197    }
198
199    /// Residue name column.
200    #[must_use]
201    pub const fn resname() -> ColumnBuilder {
202        ColumnBuilder(Column::ResidueName, "resname")
203    }
204
205    /// Chain identifier column.
206    #[must_use]
207    pub const fn chain() -> ColumnBuilder {
208        ColumnBuilder(Column::Chain, "chain")
209    }
210
211    /// Temperature-factor column.
212    #[must_use]
213    pub const fn bfactor() -> ColumnBuilder {
214        ColumnBuilder(Column::BFactor, "bfactor")
215    }
216
217    /// Occupancy column.
218    #[must_use]
219    pub const fn occupancy() -> ColumnBuilder {
220        ColumnBuilder(Column::Occupancy, "occupancy")
221    }
222
223    /// X coordinate.
224    #[must_use]
225    pub const fn x() -> ColumnBuilder {
226        ColumnBuilder(Column::X, "x")
227    }
228
229    /// Atoms within `radius` of `target`.
230    #[must_use]
231    pub fn within(radius: f32, target: Builder) -> Builder {
232        let source = format!("within {radius} of ({})", target.source);
233        Builder::new(
234            Expr::Geometric(GeometricExpr::Within {
235                radius,
236                target: Box::new(target.expr),
237            }),
238            source,
239        )
240    }
241
242    /// Whole residues containing `target` atoms.
243    #[must_use]
244    pub fn by_residue(target: Builder) -> Builder {
245        let source = format!("byres ({})", target.source);
246        Builder::new(Expr::ByResidue(Box::new(target.expr)), source)
247    }
248
249    /// Whole residues within `radius` of `target`.
250    #[must_use]
251    pub fn residues_within(radius: f32, target: Builder) -> Builder {
252        by_residue(within(radius, target))
253    }
254}
255
256#[cfg(test)]
257#[path = "builder_tests.rs"]
258mod tests;
molframe_query/api/builder.rs

molframe_query/api/
builder.rs
