Skip to main content

tabnas_alchemy/
program.rs

1//! The public API a host embeds: [`compile`] a program (or
2//! [`compile_sources`], several files linked into one), ask it what it
3//! produces, and take a [`Sink`] to push the source's events into.
4//!
5//! A program reads JSON events unless the host declares another input:
6//! [`compile_with`] and [`compile_sources_with`] take an [`Input`], and a
7//! program compiled over [`Input::ParserEvents`] reads the parser's rule
8//! passes, which the host pushes into [`Program::parser_sink`].
9//!
10//! The host passes the [`Routers`] and the [`Renderers`] the program's
11//! stages are made with (transduce's and render's) to `compile`, and the
12//! program keeps them for every sink it makes.
13//!
14//! aless runs a pipeline on its parse thread, so everything here is
15//! `Send`: the program, the sink it builds, the values inside. The host
16//! pushes `JsonEvent`s into the sink and one `End`; the sink writes the
17//! output as it goes and flushes it at `End`. A failure comes back from
18//! the event call that found it, as a transduce `Fail` whose
19//! `committed_output` says whether bytes had already reached the writer.
20
21use std::io::Write;
22use std::sync::Arc;
23
24use crate::ast::{Expr, Sources};
25use crate::interp::{Runtime, MAX_PLAN_STEPS};
26use crate::lower::{EventSink, Lowering};
27use crate::resolve::{resolve, Resolved};
28use crate::shared::{
29    AbortFlag, Code, Duplicates, Fail, Limits, Metrics, ParserSink, Renderers, Routers, Selector,
30    Sink, TextOut,
31};
32use crate::value::{Plan, Protocol, Seq, Val};
33use crate::{desugar, parse_file, stdlib};
34
35pub use crate::lower::Renderer;
36
37/// What a program's `export` produces.
38#[derive(Clone, Copy, Debug, PartialEq, Eq)]
39pub enum Output {
40    /// The program renders its own text.
41    Text,
42    /// `TableRows/1`: the host renders it (CSV by default, or JSON records).
43    TableRows,
44    /// `JsonEvents/1`: the host renders it as JSON.
45    JsonEvents,
46}
47
48impl Output {
49    pub fn as_str(self) -> &'static str {
50        match self {
51            Output::Text => "Text",
52            Output::TableRows => "TableRows/1",
53            Output::JsonEvents => "JsonEvents/1",
54        }
55    }
56}
57
58/// What a program's `export [input]` reads: the protocol the host pushes
59/// into the program's sink, which the host declares when it compiles the
60/// program.
61#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
62pub enum Input {
63    /// `JsonEvents/1`, a document's events, into [`Program::sink`]: the
64    /// default.
65    #[default]
66    JsonEvents,
67    /// `ParserEvents/1`, the parser's rule passes, into
68    /// [`Program::parser_sink`]: what a transducer part reads, through
69    /// `parser-events`.
70    ParserEvents,
71}
72
73impl Input {
74    /// The protocol's name, as `explain` reports it.
75    pub fn protocol(self) -> &'static str {
76        match self {
77            Input::JsonEvents => "JsonEvents/1",
78            Input::ParserEvents => "ParserEvents/1",
79        }
80    }
81}
82
83/// A compiled program: parsed, desugared, resolved and checked, with its
84/// plan built. Cheap to clone; `Send + Sync`.
85#[derive(Clone)]
86pub struct Program {
87    resolved: Arc<Resolved>,
88    sources: Sources,
89    /// What the host declared `export`'s input to be.
90    input: Input,
91    /// What the checker decided from `export`'s type.
92    output: Output,
93    duplicates: Duplicates,
94    /// The host's cancellation, handed to every sink's runtime.
95    abort: AbortFlag,
96    /// `export` applied to the input plan under the flags above.
97    result: Val,
98    /// The routers and renderers every sink's stages are made with.
99    injected: Injected,
100}
101
102/// The routers and renderers the host passed to [`compile`].
103#[derive(Clone)]
104struct Injected {
105    routers: Arc<dyn Routers<Val>>,
106    renderers: Arc<dyn Renderers>,
107}
108
109impl std::fmt::Debug for Program {
110    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
111        f.debug_struct("Program")
112            .field("file", &self.resolved.file)
113            .field("input", &self.input)
114            .field("output", &self.output())
115            .finish()
116    }
117}
118
119/// Parse, desugar, resolve and check `src`, named `file` in diagnostics,
120/// and build its plan: `export` applied to the input's plan, which
121/// evaluates everything a stream does not defer, so a `fail` or a
122/// `no_match` on that path is reported here, with its own code. The work
123/// runs on a thread of [`crate::STACK_BYTES`], and building the plan is
124/// bounded by [`MAX_PLAN_STEPS`] and [`crate::MAX_EVAL_DEPTH`].
125///
126/// `routers` and `renderers` make the stages of every sink the program
127/// builds ([`Program::sink`]): transduce's (`tabnas_transduce::routers()`)
128/// and render's (`tabnas_render::renderers()`). Compiling asks nothing of
129/// them.
130pub fn compile(
131    src: &str,
132    file: &str,
133    routers: Arc<dyn Routers<Val>>,
134    renderers: Arc<dyn Renderers>,
135) -> Result<Program, Fail> {
136    compile_sources(&[Source::new(file, src)], routers, renderers)
137}
138
139/// [`compile`] over the input the host declares: `export [input]` reads
140/// JSON events ([`Input::JsonEvents`], what [`compile`] declares) or the
141/// parser's rule passes ([`Input::ParserEvents`]). The checker holds the
142/// program to it: `events input` over parser events, or `parser-events
143/// input` over JSON events, is `protocol_mismatch`.
144pub fn compile_with(
145    src: &str,
146    file: &str,
147    input: Input,
148    routers: Arc<dyn Routers<Val>>,
149    renderers: Arc<dyn Renderers>,
150) -> Result<Program, Fail> {
151    compile_sources_with(&[Source::new(file, src)], input, routers, renderers)
152}
153
154/// One of the sources a program is compiled from: the file it is named
155/// by in diagnostics, its text, and the name its own `export` is linked
156/// under when another source's `export` is the program's.
157#[derive(Clone, Copy, Debug)]
158pub struct Source<'a> {
159    pub file: &'a str,
160    pub text: &'a str,
161    /// When set, this source's `export` is defined under this name in the
162    /// linked namespace, and every mention of `export` in this source
163    /// names it, so that the program's `export`, in another source, can
164    /// call it: a host composes a program's output into a format's render
165    /// by linking the program as `program-export` and writing
166    /// `def export [input] (yaml-render (program-export input))`. The
167    /// source must define `export` (`no_export` otherwise) and must not
168    /// mention the name already (`duplicate_def`), since renaming beside
169    /// a binding of that name would change what the source means.
170    pub export_as: Option<&'a str>,
171}
172
173impl<'a> Source<'a> {
174    pub fn new(file: &'a str, text: &'a str) -> Source<'a> {
175        Source {
176            file,
177            text,
178            export_as: None,
179        }
180    }
181
182    /// The same source with its `export` linked under `name`.
183    pub fn export_as(self, name: &'a str) -> Source<'a> {
184        Source {
185            export_as: Some(name),
186            ..self
187        }
188    }
189}
190
191/// Compile a program from several sources linked into one namespace: a
192/// definition in any of them is in scope in all, `export` is defined in
193/// one, and a name defined twice, in one file or across two, is
194/// `duplicate_def`. Each source is named by its file, and the names are
195/// distinct (`duplicate_file` otherwise). A failure in a program of
196/// several sources carries the file its position is in, `Fail::file`,
197/// displayed `(file:row:col)`, beside the row and column; a program of
198/// one source is [`compile`], which positions without a file. This is
199/// how a host links a format's parts (its lift and render: libraries of
200/// definitions with no `export`) with the program that calls them.
201///
202/// A source whose `export` is not the program's is linked with
203/// [`Source::export_as`]: its `export` is defined under that name
204/// instead, so that the program's `export` can call it. This is how a
205/// host composes a whole program's output into a format's render
206/// (`def export [input] (yaml-render (program-export input))`, with the
207/// user's program linked as `program-export`), in one plan under one
208/// set of limits. The renamed source positions its failures in its own
209/// file as any source does. `routers` and `renderers` are as for
210/// [`compile`].
211pub fn compile_sources(
212    sources: &[Source<'_>],
213    routers: Arc<dyn Routers<Val>>,
214    renderers: Arc<dyn Renderers>,
215) -> Result<Program, Fail> {
216    compile_sources_with(sources, Input::JsonEvents, routers, renderers)
217}
218
219/// [`compile_sources`] over the input the host declares, as for
220/// [`compile_with`].
221pub fn compile_sources_with(
222    sources: &[Source<'_>],
223    input: Input,
224    routers: Arc<dyn Routers<Val>>,
225    renderers: Arc<dyn Renderers>,
226) -> Result<Program, Fail> {
227    let injected = Injected { routers, renderers };
228    on_stack(|| {
229        let mut named: Vec<(Arc<str>, Arc<str>)> = Vec::with_capacity(sources.len());
230        for source in sources {
231            if named.iter().any(|(file, _)| &**file == source.file) {
232                return Err(Fail::new(
233                    Code::DslTypeError,
234                    format!(
235                        "duplicate_file: {} is given twice; each source has its own name",
236                        source.file
237                    ),
238                ));
239            }
240            named.push((Arc::from(source.file), Arc::from(source.text)));
241        }
242        if named.is_empty() {
243            return Err(crate::check::no_export());
244        }
245        let linked = Sources::several(named);
246        let mut forms = Vec::new();
247        for source in sources {
248            // The reader and the desugarer see one file at a time, so the
249            // file is added here; the stages after them position through
250            // `linked`.
251            let in_file = |fail: Fail| {
252                if linked.names_files() {
253                    fail.in_file(source.file)
254                } else {
255                    fail
256                }
257            };
258            let parsed = parse_file(source.text, source.file).map_err(in_file)?;
259            let mut own = desugar::program(parsed, source.text).map_err(in_file)?;
260            if let Some(name) = source.export_as {
261                if !own.iter().any(|form| defines(form, "export")) {
262                    return Err(in_file(Fail::new(
263                        Code::DslTypeError,
264                        format!(
265                            "no_export: {} defines no export to link as {name}",
266                            source.file
267                        ),
268                    )));
269                }
270                // Renaming every `export` is a consistent renaming only
271                // while nothing in the source is already called `name`: a
272                // parameter or a `let` of that name would capture a renamed
273                // mention. The host chooses the name, so one in use is its
274                // mistake, said at the first mention.
275                if let Some(taken) = own.iter().find_map(|form| mentions(form, name)) {
276                    return Err(in_file(
277                        Fail::new(
278                            Code::DslTypeError,
279                            format!(
280                                "duplicate_def: {} already names {name}, so its export cannot \
281                                 be linked under it; link it under another name",
282                                source.file
283                            ),
284                        )
285                        .at(
286                            linked.position(taken).0 as u64,
287                            linked.position(taken).1 as u64,
288                        ),
289                    ));
290                }
291                for form in &mut own {
292                    rename_symbol(form, "export", name);
293                }
294            }
295            forms.extend(own);
296        }
297        let resolved = Arc::new(resolve(forms, &linked, &stdlib::outer)?);
298        let checked = crate::check::program_with(&resolved, &linked, input)?;
299        Program::build_here(
300            resolved,
301            linked,
302            input,
303            checked.output,
304            Duplicates::Reject,
305            AbortFlag::new(),
306            injected.clone(),
307        )
308    })
309}
310
311/// Whether `form` is a top-level `def` of `name`, as the desugarer leaves
312/// one: `(def name value)`.
313fn defines(form: &Expr, name: &str) -> bool {
314    match form {
315        Expr::List { items, .. } => {
316            items.len() == 3 && items[0].symbol() == Some("def") && items[1].symbol() == Some(name)
317        }
318        _ => false,
319    }
320}
321
322/// The span of the first symbol `name` in `form`, when it mentions one.
323/// Recursive per level, which [`crate::MAX_NESTING`] bounds.
324fn mentions<'f>(form: &'f Expr, name: &str) -> Option<&'f crate::ast::SourceSpan> {
325    match form {
326        Expr::Symbol { name: n, span } if &**n == name => Some(span),
327        Expr::List { items, .. } | Expr::Vector { items, .. } => {
328            items.iter().find_map(|item| mentions(item, name))
329        }
330        _ => None,
331    }
332}
333
334/// Every symbol `from` in `form` becomes `to`: the name a `def` binds and
335/// every mention of it alike, so the source means what it meant under
336/// the new name, which [`compile_sources`] has checked is not in use.
337/// Recursive per level, which [`crate::MAX_NESTING`] bounds.
338fn rename_symbol(form: &mut Expr, from: &str, to: &str) {
339    match form {
340        Expr::Symbol { name, .. } if &**name == from => *name = Arc::from(to),
341        Expr::List { items, .. } | Expr::Vector { items, .. } => {
342            for item in items {
343                rename_symbol(item, from, to);
344            }
345        }
346        _ => {}
347    }
348}
349
350/// Run `work` on a thread of [`crate::STACK_BYTES`], so the checker's and
351/// the evaluator's recursion has the room their bounds promise whatever
352/// thread the caller is on.
353fn on_stack<T: Send>(work: impl FnOnce() -> Result<T, Fail> + Send) -> Result<T, Fail> {
354    std::thread::scope(|scope| {
355        let thread = std::thread::Builder::new()
356            .name("alchemy-compile".into())
357            .stack_size(crate::STACK_BYTES)
358            .spawn_scoped(scope, work)
359            .map_err(|error| {
360                Fail::new(
361                    Code::ResourceLimitExceeded,
362                    format!("no thread could be started to compile the program: {error}"),
363                )
364            })?;
365        thread
366            .join()
367            .unwrap_or_else(|panic| std::panic::resume_unwind(panic))
368    })
369}
370
371impl Program {
372    fn build(
373        resolved: Arc<Resolved>,
374        sources: Sources,
375        input: Input,
376        output: Output,
377        duplicates: Duplicates,
378        abort: AbortFlag,
379        injected: Injected,
380    ) -> Result<Program, Fail> {
381        on_stack(|| {
382            Program::build_here(
383                resolved, sources, input, output, duplicates, abort, injected,
384            )
385        })
386    }
387
388    fn build_here(
389        resolved: Arc<Resolved>,
390        sources: Sources,
391        input: Input,
392        output: Output,
393        duplicates: Duplicates,
394        abort: AbortFlag,
395        injected: Injected,
396    ) -> Result<Program, Fail> {
397        let result = Runtime::new(resolved.clone(), sources.clone())
398            .with_duplicates(duplicates)
399            .with_fuel(Some(MAX_PLAN_STEPS))
400            .with_abort(abort.clone())
401            .export_with(input)?;
402        Ok(Program {
403            resolved,
404            sources,
405            input,
406            output,
407            duplicates,
408            abort,
409            result,
410            injected,
411        })
412    }
413
414    /// The same program with another policy for repeated member names in
415    /// captured values; the default rejects them.
416    pub fn with_duplicates(&self, duplicates: Duplicates) -> Result<Program, Fail> {
417        Program::build(
418            self.resolved.clone(),
419            self.sources.clone(),
420            self.input,
421            self.output,
422            duplicates,
423            self.abort.clone(),
424            self.injected.clone(),
425        )
426    }
427
428    /// The same program with the host's cancellation: every sink it makes
429    /// reads the flag as the program's functions run, so a timeout stops
430    /// a long computation on one item with `ABORTED` rather than waiting
431    /// for the item to finish. The source takes the same flag
432    /// (`ParserSource::abort`) to stop between events.
433    pub fn with_abort(&self, abort: AbortFlag) -> Program {
434        Program {
435            abort,
436            ..self.clone()
437        }
438    }
439
440    /// The policy for a member name repeated in a captured scope.
441    pub fn duplicates(&self) -> Duplicates {
442        self.duplicates
443    }
444
445    /// What the host declared `export`'s input to be, and so which sink
446    /// it pushes the source into: [`Program::sink`] for JSON events,
447    /// [`Program::parser_sink`] for parser events.
448    pub fn input(&self) -> Input {
449        self.input
450    }
451
452    /// The file name the program was compiled under: the first, of
453    /// several.
454    pub fn file(&self) -> &str {
455        &self.resolved.file
456    }
457
458    pub fn resolved(&self) -> &Arc<Resolved> {
459        &self.resolved
460    }
461
462    /// The plan `export` answered: a text or a stream.
463    pub fn result(&self) -> &Val {
464        &self.result
465    }
466
467    /// What the program produces, and so what the host renders: decided
468    /// by the checker from `export`'s type.
469    pub fn output(&self) -> Output {
470        self.output
471    }
472
473    /// The protocol the built plan produces; the checker's `output` agrees
474    /// with it, and a test holds the two together. A stream of items is
475    /// the checker's to name (every item an event, or a table event),
476    /// since the runtime learns an item's shape only as it arrives.
477    pub fn plan_output(&self) -> Output {
478        match &self.result {
479            Val::Stream(plan) => match plan.protocol() {
480                Protocol::JsonEvents => Output::JsonEvents,
481                // The parser's input is never a result: the checker
482                // refuses an export that answers it (`bad_output`).
483                Protocol::Items | Protocol::Text | Protocol::ParserEvents => self.output,
484            },
485            _ => Output::Text,
486        }
487    }
488
489    /// The selector under which the source is read one row at a time,
490    /// when the plan makes one known: the table binding's `:rows`, a
491    /// `select`'s selector, or the one multi-location capture of a
492    /// `route`. A host that streams a verified grammar prunes the parse
493    /// under it.
494    pub fn row_selector(&self) -> Option<&Selector> {
495        match root_stage(self.plan()?) {
496            Plan::Select { selector, .. } => Some(selector),
497            Plan::Route { specs, .. } => {
498                let multi: Vec<&Selector> = specs
499                    .iter()
500                    .map(|s| &s.selector)
501                    .filter(|s| s.is_multi())
502                    .collect();
503                match (multi.as_slice(), specs.len()) {
504                    ([one], _) => Some(one),
505                    ([], 1) => Some(&specs[0].selector),
506                    _ => None,
507                }
508            }
509            _ => None,
510        }
511    }
512
513    /// The plan report of spec section 15.5: the chain of calls, the
514    /// protocols, what is retained and under which limits, the ordering
515    /// contract, the renderer, the guarantee and its qualification.
516    pub fn explain(&self) -> String {
517        crate::effects::explain(self)
518    }
519
520    /// The same report as one JSON object, for a host's `--explain`.
521    pub fn explain_json(&self) -> serde_json::Value {
522        crate::effects::explain_json(self)
523    }
524
525    fn plan(&self) -> Option<&Arc<Plan>> {
526        match &self.result {
527            Val::Stream(p) | Val::Text(p) => Some(p),
528            _ => None,
529        }
530    }
531
532    /// The sink for one run: the host pushes the source's events into it
533    /// and one `End`, and the output reaches `out` through a coalescing
534    /// writer ([`Renderers::write_out`]) with `limits.max_output_bytes`
535    /// enforced and `output_bytes` counted in `metrics`. `render` chooses
536    /// how a table or JSON-events result is rendered (CSV or JSON; `None`
537    /// for the default); a program that renders its own text takes none
538    /// (`render_of_text`). A program compiled over parser events takes
539    /// them through [`Program::parser_sink`] instead.
540    pub fn sink(
541        &self,
542        out: Box<dyn Write + Send>,
543        render: Option<Renderer>,
544        limits: &Limits,
545        metrics: Arc<Metrics>,
546    ) -> Result<Box<dyn Sink + Send>, Fail> {
547        self.declared(Input::JsonEvents)?;
548        let out = self
549            .injected
550            .renderers
551            .write_out(out, limits, metrics.clone());
552        self.sink_out(out, render, limits, metrics)
553    }
554
555    /// [`Program::sink`] over any text output: for a host that has its own
556    /// writer stage, and for tests that read the text back.
557    pub fn sink_out(
558        &self,
559        out: Box<dyn TextOut + Send>,
560        render: Option<Renderer>,
561        limits: &Limits,
562        metrics: Arc<Metrics>,
563    ) -> Result<EventSink, Fail> {
564        self.declared(Input::JsonEvents)?;
565        self.lowering(limits, metrics)
566            .sink_as(&self.result, out, render, self.output)
567    }
568
569    /// The sink for one run over parser events, for a program compiled
570    /// over [`Input::ParserEvents`]: the host pushes each rule pass into
571    /// it and one `End`, once the parse has returned its value. The output
572    /// is written as for [`Program::sink`].
573    pub fn parser_sink(
574        &self,
575        out: Box<dyn Write + Send>,
576        render: Option<Renderer>,
577        limits: &Limits,
578        metrics: Arc<Metrics>,
579    ) -> Result<Box<dyn ParserSink + Send>, Fail> {
580        self.declared(Input::ParserEvents)?;
581        let out = self
582            .injected
583            .renderers
584            .write_out(out, limits, metrics.clone());
585        self.parser_sink_out(out, render, limits, metrics)
586    }
587
588    /// [`Program::parser_sink`] over any text output, as
589    /// [`Program::sink_out`] is [`Program::sink`]'s.
590    pub fn parser_sink_out(
591        &self,
592        out: Box<dyn TextOut + Send>,
593        render: Option<Renderer>,
594        limits: &Limits,
595        metrics: Arc<Metrics>,
596    ) -> Result<Box<dyn ParserSink + Send>, Fail> {
597        self.declared(Input::ParserEvents)?;
598        let lowering = self.lowering(limits, metrics);
599        let events = lowering.sink_as(&self.result, out, render, self.output)?;
600        Ok(lowering.parser_head(events))
601    }
602
603    /// The sink for one run over parser events whose JSON events go into
604    /// the host's own `down` rather than to a renderer, for a program
605    /// compiled over [`Input::ParserEvents`] that answers JSON events: a
606    /// format's transducer part, run in front of the host's own stages (a
607    /// renderer of its own, a scope over a path, another program's sink).
608    /// The host pushes each rule pass into the `ParserSink + Send` it
609    /// returns, then one `ParserEvent::End` once the parse has returned its
610    /// value, and `down` takes the events as the program makes them, then
611    /// one `End`. The source's limits hold on them as on a source's own. A
612    /// program that answers a text or a table is refused
613    /// (`protocol_mismatch`) before anything runs, as is one compiled over
614    /// JSON events.
615    pub fn parser_sink_into(
616        &self,
617        down: Box<dyn Sink + Send>,
618        limits: &Limits,
619        metrics: Arc<Metrics>,
620    ) -> Result<Box<dyn ParserSink + Send>, Fail> {
621        self.declared(Input::ParserEvents)?;
622        let lowering = self.lowering(limits, metrics);
623        let events = lowering.events_into(&self.result, self.output, down)?;
624        Ok(lowering.parser_head(events))
625    }
626
627    /// Whether the host drives the sink the program's input was declared
628    /// for: a host's mistake, not a program's, refused before anything
629    /// runs.
630    fn declared(&self, input: Input) -> Result<(), Fail> {
631        if self.input == input {
632            return Ok(());
633        }
634        let (declared, sink) = match self.input {
635            Input::JsonEvents => ("JSON events", "Program::sink"),
636            Input::ParserEvents => ("parser events", "Program::parser_sink"),
637        };
638        Err(Fail::new(
639            Code::DslTypeError,
640            format!(
641                "protocol_mismatch: the program was compiled over {declared}; push them into {sink}"
642            ),
643        ))
644    }
645
646    fn lowering<'l>(&self, limits: &'l Limits, metrics: Arc<Metrics>) -> Lowering<'l> {
647        let rt = Arc::new(
648            Runtime::new(self.resolved.clone(), self.sources.clone())
649                .with_duplicates(self.duplicates)
650                .with_limits(limits)
651                .with_abort(self.abort.clone()),
652        );
653        Lowering::new(
654            rt,
655            limits,
656            metrics,
657            self.injected.routers.clone(),
658            self.injected.renderers.clone(),
659        )
660    }
661}
662
663/// The stage that reads the input directly: the plan whose source is
664/// `Input` (or `ParserInput`), or the input itself.
665fn root_stage(plan: &Plan) -> &Plan {
666    let mut here = plan;
667    loop {
668        let next: &Plan = match here {
669            Plan::Input | Plan::ParserInput => return here,
670            Plan::Route { source, .. }
671            | Plan::Select { source, .. }
672            | Plan::Events { source }
673            | Plan::ParserEvents { source, .. }
674            | Plan::ScanEmit { source, .. }
675            | Plan::Map { source, .. }
676            | Plan::Filter { source, .. }
677            | Plan::Records { source }
678            | Plan::TreeContract { source }
679            | Plan::AsEvents { source }
680            | Plan::CsvTable { source, .. }
681            | Plan::Json { source, .. } => {
682                if matches!(**source, Plan::Input | Plan::ParserInput) {
683                    return here;
684                }
685                source
686            }
687            Plan::ConcatMap {
688                items: Seq::Stream(source),
689                ..
690            }
691            | Plan::Join {
692                items: Seq::Stream(source),
693                ..
694            } => source,
695            Plan::Concat { items, live } => match live.and_then(|i| items.get(i)) {
696                Some(Val::Text(inner)) | Some(Val::Stream(inner)) => inner,
697                _ => return here,
698            },
699            Plan::Replace {
700                source: Val::Text(inner),
701                ..
702            } => inner,
703            _ => return here,
704        };
705        here = next;
706    }
707}
708
709#[cfg(test)]
710mod tests {
711    use super::*;
712    use crate::lower::tests::{compile, PROGRAM};
713
714    #[test]
715    fn a_program_knows_its_output_and_row_selector() {
716        let p = compile(PROGRAM, "t.alc").unwrap();
717        assert_eq!(p.output(), Output::Text);
718        assert_eq!(
719            p.row_selector().unwrap().to_string(),
720            ".response.payload.deep.records[*]"
721        );
722        let table = compile(&PROGRAM.replace("    csv csv-options\n", ""), "t.alc").unwrap();
723        assert_eq!(table.output(), Output::TableRows);
724        let echo = compile("def export [input] input", "t.alc").unwrap();
725        assert_eq!(echo.output(), Output::JsonEvents);
726        assert_eq!(echo.row_selector(), None);
727        let select = compile(
728            "def export [input] (join \",\" (select (path \"a\" each-index) input))",
729            "t.alc",
730        )
731        .unwrap();
732        assert_eq!(select.output(), Output::Text);
733        assert_eq!(select.row_selector().unwrap().to_string(), ".a[*]");
734        // A rewritten tree the program says is events: the rows are still
735        // the select's, behind as-events.
736        let rewritten = compile(
737            "def export [input] (as-events (map (fn [x] (scalar x)) (select (path \"a\" each-index) input)))",
738            "t.alc",
739        )
740        .unwrap();
741        assert_eq!(rewritten.output(), Output::JsonEvents);
742        assert_eq!(rewritten.row_selector().unwrap().to_string(), ".a[*]");
743    }
744
745    #[test]
746    fn compile_reports_reader_resolver_and_export_failures() {
747        assert_eq!(
748            compile("(a b", "t.alc").unwrap_err().code,
749            crate::shared::Code::DslParseError
750        );
751        let f = compile("def export [input] (nope input)", "t.alc").unwrap_err();
752        assert!(f.message.starts_with("unknown_name: "), "{f}");
753        let f = compile("def x 1", "t.alc").unwrap_err();
754        assert!(f.message.starts_with("no_export: "), "{f}");
755    }
756}