rumtk_core/pipelines.rs
1/*
2 * rumtk attempts to implement HL7 and medical protocols for interoperability in medicine.
3 * This toolkit aims to be reliable, simple, performant, and standards compliant.
4 * Copyright (C) 2025 Luis M. Santos, M.D. <lsantos@medicalmasses.com>
5 * Copyright (C) 2025 MedicalMasses L.L.C. <contact@medicalmasses.com>
6 *
7 * This program is free software: you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation, either version 3 of the License, or
10 * (at your option) any later version.
11 *
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
16 *
17 * You should have received a copy of the GNU General Public License
18 * along with this program. If not, see <https://www.gnu.org/licenses/>.
19 */
20
21pub mod pipeline_types {
22 use crate::core::{RUMResult, RUMVec};
23 use crate::strings::{RUMString, RUMStringConversions};
24 use crate::types::{RUMBuffer, RUMDeserialize, RUMHashMap, RUMSerialize};
25 use std::process::{Child, Command};
26
27 pub static EMPTY_COMMAND_LINE: RUMCommandLine = RUMCommandLine::new();
28
29 pub type RUMCommandArgs = Vec<RUMString>;
30 pub type RUMCommandEnv = RUMHashMap<RUMString, RUMString>;
31 #[derive(RUMSerialize, RUMDeserialize, PartialEq, Default, Debug, Clone)]
32 pub struct RUMCommand {
33 pub path: RUMString,
34 #[serde(skip)]
35 pub data: Option<RUMBuffer>,
36 pub args: RUMCommandArgs,
37 pub env: RUMCommandEnv,
38 }
39
40 impl RUMCommand {
41 pub fn new(
42 prog: &str,
43 data: &Option<RUMBuffer>,
44 args: &RUMCommandArgs,
45 env: &RUMCommandEnv,
46 ) -> Self {
47 RUMCommand {
48 path: prog.to_rumstring(),
49 args: args.clone(),
50 env: env.clone(),
51 data: data.clone(),
52 }
53 }
54 }
55
56 pub type RUMCommandLine = RUMVec<RUMCommand>;
57 pub type RUMPipelineCommand = Command;
58 pub type RUMPipelineProcess = Child;
59 pub type RUMPipeline = RUMVec<RUMPipelineProcess>;
60 pub type RUMPipelineResult = RUMResult<RUMBuffer>;
61}
62
63pub mod pipeline_functions {
64 use super::pipeline_types::*;
65 use crate::core::RUMResult;
66 use crate::strings::{rumtk_format, string_format, CompactStringExt, RUMArrayConversions, RUMString, StringReplacementPair};
67 use std::io::{Read, Write};
68 use std::os::unix::ffi::OsStrExt;
69
70 use crate::rumtk_resolve_sync_task;
71 use crate::types::RUMBuffer;
72 use std::process::{Command, Stdio};
73
74 const DEFAULT_PROCESS_ASYNC_WAIT: f32 = 0.001;
75 const DEFAULT_STDOUT_CHUNK_SIZE: usize = 1024;
76
77 ///
78 /// Given a command of type [RUMCommand](RUMCommand), generate a command instance the Rust
79 /// runtime can use to spawn a process.
80 ///
81 /// ## Example
82 ///
83 /// ```
84 /// use std::any::{Any, TypeId};
85 ///
86 /// use rumtk_core::strings::RUMString;
87 /// use rumtk_core::pipelines::pipeline_types::{RUMCommand, RUMPipelineCommand};
88 /// use rumtk_core::pipelines::pipeline_functions::pipeline_create_command;
89 ///
90 /// let command_name = "ls";
91 /// let mut command = RUMCommand::default();
92 /// command.path = RUMString::from(command_name);
93 ///
94 /// let sys_command = pipeline_create_command(&command);
95 ///
96 /// assert_eq!(sys_command.get_program().to_str().unwrap(), command_name, "");
97 ///
98 /// ```
99 ///
100 pub fn pipeline_create_command(command: &RUMCommand) -> RUMPipelineCommand {
101 let mut cmd = Command::new(command.path.as_str());
102
103 for arg in command.args.iter() {
104 cmd.arg(arg);
105 }
106
107 cmd.envs(command.env.iter());
108
109 cmd.stdin(Stdio::piped())
110 .stdout(Stdio::piped())
111 .stderr(Stdio::piped());
112
113 cmd
114 }
115
116 ///
117 /// Spawns a process out of the [RUMPipelineCommand](RUMPipelineCommand).
118 ///
119 /// ## Example
120 ///
121 /// ```
122 /// use std::any::{Any, TypeId};
123 ///
124 /// use rumtk_core::strings::RUMString;
125 /// use rumtk_core::pipelines::pipeline_types::{RUMCommand, RUMPipelineCommand};
126 /// use rumtk_core::pipelines::pipeline_functions::{pipeline_create_command, pipeline_spawn_process};
127 ///
128 /// let command_name = "ls";
129 /// let mut command = RUMCommand::default();
130 /// command.path = RUMString::from(command_name);
131 ///
132 /// let mut sys_command = pipeline_create_command(&command);
133 ///
134 /// let mut process = pipeline_spawn_process(&mut sys_command).unwrap();
135 ///
136 /// process.wait();
137 /// ```
138 ///
139 pub fn pipeline_spawn_process(cmd: &mut RUMPipelineCommand) -> RUMResult<RUMPipelineProcess> {
140 match cmd.spawn() {
141 Ok(process) => {
142 println!("Spawned process {} => {} with args {:?}", process.id(), cmd.get_program().as_bytes().to_rumstring(), cmd.get_args());
143 Ok(process)
144 },
145 Err(e) => Err(rumtk_format!(
146 "Failed to spawn process {:?} because => {}",
147 cmd.get_program(),
148 e
149 )),
150 }
151 }
152
153 ///
154 /// Given a process of type [RUMPipelineProcess](RUMPipelineProcess) and a rhs of type [RUMPipelineCommand](RUMPipelineCommand),
155 /// create a pipe of the lhs's `stdout` into the next command descriptor which is the rhs.
156 ///
157 /// ## Example
158 ///
159 /// ```
160 /// use std::any::{Any, TypeId};
161 /// use std::process::Stdio;
162 ///
163 /// use rumtk_core::strings::RUMString;
164 /// use rumtk_core::pipelines::pipeline_types::{RUMCommand, RUMPipelineCommand};
165 /// use rumtk_core::pipelines::pipeline_functions::{pipeline_create_command, pipeline_pipe_processes, pipeline_spawn_process};
166 ///
167 /// let ls_name = "ls";
168 /// let mut ls_command = RUMCommand::default();
169 /// ls_command.path = RUMString::from(ls_name);
170 /// let mut sys_ls_command = pipeline_create_command(&ls_command);
171 ///
172 /// let wc_name = "wc";
173 /// let mut wc_command = RUMCommand::default();
174 /// wc_command.path = RUMString::from(wc_name);
175 /// let mut sys_wc_command = pipeline_create_command(&wc_command);
176 ///
177 /// let mut sys_ls_process = pipeline_spawn_process(&mut sys_ls_command).unwrap();
178 /// pipeline_pipe_processes(&mut sys_ls_process, &mut sys_wc_command).unwrap();
179 /// let mut sys_wc_process = pipeline_spawn_process(&mut sys_wc_command).unwrap();
180 ///
181 /// sys_ls_process.wait();
182 /// sys_wc_process.wait();
183 /// ```
184 ///
185 pub fn pipeline_pipe_processes(
186 process: &mut RUMPipelineProcess,
187 piped: &mut RUMPipelineCommand,
188 ) -> RUMResult<()> {
189 let process_stdout = Stdio::from(match process.stdout.take() {
190 Some(stdout) => stdout,
191 None => {
192 return Err(rumtk_format!(
193 "No stdout handle found for process {}.",
194 process.id()
195 ));
196 }
197 });
198 let _ = piped.stdin(process_stdout);
199 Ok(())
200 }
201
202 ///
203 /// Retrieves the standard output generated by the completed process.
204 ///
205 /// ## Example
206 ///
207 /// ```
208 /// use std::any::{Any, TypeId};
209 /// use std::process::Stdio;
210 ///
211 /// use rumtk_core::strings::RUMString;
212 /// use rumtk_core::pipelines::pipeline_types::{RUMCommand, RUMPipelineCommand};
213 /// use rumtk_core::pipelines::pipeline_functions::{pipeline_create_command, pipeline_spawn_process, pipeline_get_stdout, pipeline_pipe_processes};
214 ///
215 /// let ls_name = "ls";
216 /// let mut ls_command = RUMCommand::default();
217 /// ls_command.path = RUMString::from(ls_name);
218 /// let mut sys_ls_command = pipeline_create_command(&ls_command);
219 ///
220 /// let wc_name = "wc";
221 /// let mut wc_command = RUMCommand::default();
222 /// wc_command.path = RUMString::from(wc_name);
223 /// let mut sys_wc_command = pipeline_create_command(&wc_command);
224 ///
225 /// let mut sys_ls_process = pipeline_spawn_process(&mut sys_ls_command).unwrap();
226 /// pipeline_pipe_processes(&mut sys_ls_process, &mut sys_wc_command).unwrap();
227 /// let mut sys_wc_process = pipeline_spawn_process(&mut sys_wc_command).unwrap();
228 ///
229 /// sys_ls_process.wait();
230 /// sys_wc_process.wait();
231 ///
232 /// let out_data = pipeline_get_stdout(sys_wc_process).unwrap();
233 ///
234 /// assert_eq!(out_data.is_empty(), false, "No output detected... {:?}", &out_data);
235 /// ```
236 ///
237 pub fn pipeline_get_stdout(mut process: RUMPipelineProcess) -> RUMResult<RUMBuffer> {
238 match process.wait_with_output() {
239 Ok(stdout) => Ok(RUMBuffer::from(stdout.stdout.clone())),
240 Err(e) => Err(rumtk_format!(
241 "Issue reading last process output because => {}",
242 e
243 )),
244 }
245 }
246
247 ///
248 /// Closes the `stdin` standard in file for process. Useful to trigger a resolution of the pipeline.
249 ///
250 /// ## Example
251 ///
252 /// ```
253 /// use rumtk_core::pipelines::pipeline_functions::pipeline_close_process_stdin;
254 /// use rumtk_core::strings::RUMString;
255 /// use rumtk_core::pipelines::pipeline_types::{RUMCommand, RUMPipelineCommand};
256 /// use rumtk_core::pipelines::pipeline_functions::{pipeline_create_command, pipeline_pipe_into_process, pipeline_spawn_process};
257 /// use rumtk_core::types::RUMBuffer;
258 ///
259 /// let ls_name = "ls";
260 /// let mut ls_command = RUMCommand::default();
261 /// ls_command.path = RUMString::from(ls_name);
262 /// let mut sys_ls_command = pipeline_create_command(&ls_command);
263 /// let mut sys_ls_process = pipeline_spawn_process(&mut sys_ls_command).unwrap();
264 ///
265 /// pipeline_close_process_stdin(&mut sys_ls_process);
266 ///
267 ///
268 /// ```
269 ///
270 pub fn pipeline_close_process_stdin(process: &mut RUMPipelineProcess) {
271 // Do not change into an expect() or such unwrap. We just want to ignore and assume stdin is closed.
272 match process.stdin.take() {
273 Some(stdin) => {
274 drop(stdin);
275 }
276 None => {}
277 };
278 }
279
280 ///
281 /// Pipe data into a process.
282 ///
283 /// ## Example
284 ///
285 /// ```
286 /// use rumtk_core::strings::RUMString;
287 /// use rumtk_core::pipelines::pipeline_types::{RUMCommand, RUMPipelineCommand};
288 /// use rumtk_core::pipelines::pipeline_functions::{pipeline_create_command, pipeline_pipe_into_process, pipeline_spawn_process};
289 /// use rumtk_core::types::RUMBuffer;
290 ///
291 /// let ls_name = "ls";
292 /// let mut ls_command = RUMCommand::default();
293 /// ls_command.path = RUMString::from(ls_name);
294 /// let mut sys_ls_command = pipeline_create_command(&ls_command);
295 /// let mut sys_ls_process = pipeline_spawn_process(&mut sys_ls_command).unwrap();
296 /// pipeline_pipe_into_process(&mut sys_ls_process, &RUMBuffer::default()).unwrap();
297 ///
298 /// let out = sys_ls_process.wait_with_output().unwrap();
299 ///
300 /// assert_eq!(out.stdout.is_empty(), false, "Piped command returned an empty buffer? => {:?}", String::from_utf8_lossy(out.stdout.as_slice()))
301 /// ```
302 ///
303 pub fn pipeline_pipe_into_process(
304 process: &mut RUMPipelineProcess,
305 data: &RUMBuffer,
306 ) -> RUMResult<()> {
307 match process.stdin.take() {
308 Some(ref mut stdin) => match stdin.write_all(data.as_slice()) {
309 Ok(_) => {}
310 Err(e) => {
311 return Err(rumtk_format!(
312 "Failed to pipe data to stdin of process {} because => {}",
313 process.id(),
314 e
315 ))
316 }
317 },
318 None => {}
319 }
320 Ok(())
321 }
322
323 ///
324 /// Builds an executable pipeline out of a list of [RUMCommand](RUMCommand).
325 ///
326 /// ## Example
327 ///
328 /// ```
329 /// use rumtk_core::strings::{RUMStringConversions, RUMString};
330 /// use rumtk_core::pipelines::pipeline_types::{RUMCommand};
331 /// use rumtk_core::pipelines::pipeline_functions::{pipeline_generate_command, pipeline_get_stdout, pipeline_wait_pipeline};
332 /// use rumtk_core::types::RUMBuffer;
333 ///
334 /// let ls_name = "ls";
335 /// let mut ls_command = RUMCommand::default();
336 /// ls_command.path = RUMString::from(ls_name);
337 /// ls_command.args = vec!["-la".to_rumstring()];
338 ///
339 /// let mut process = pipeline_generate_command(&ls_command, &RUMBuffer::default()).unwrap();
340 /// let result = pipeline_get_stdout(process).unwrap();
341 ///
342 /// assert!(result.len() > 0, "Command generation failed to generate a valid command!");
343 /// ```
344 ///
345 pub fn pipeline_generate_command(command: &RUMCommand, data: &RUMBuffer) -> RUMResult<RUMPipelineProcess> {
346 let mut root = pipeline_create_command(&command);
347 let mut process = pipeline_spawn_process(&mut root)?;
348 pipeline_pipe_into_process(&mut process, data)?;
349 pipeline_close_process_stdin(&mut process);
350
351 Ok(process)
352 }
353
354 ///
355 /// Add buffer at the beginning of pipeline to pipe in. This buffer serves as the initial input of
356 /// a pipe aware program.
357 ///
358 /// ## Example
359 /// ```
360 /// use rumtk_core::core::RUMResult;
361 /// use rumtk_core::pipelines::pipeline_types::{RUMCommand, RUMCommandLine};
362 /// use rumtk_core::rumtk_pipeline_run;
363 /// use rumtk_core::strings::{buffer_to_string, RUMString};
364 /// use rumtk_core::types::RUMBuffer;
365 ///
366 /// let data = RUMBuffer::from_static(b"Hello World");
367 /// let wc_name = "wc";
368 /// let mut wc_command = RUMCommand::default();
369 /// wc_command.path = RUMString::from(wc_name);
370 /// let mut pipeline = vec![
371 /// wc_command
372 /// ];
373 ///
374 /// let processor = || -> RUMResult<RUMBuffer> {rumtk_pipeline_run!(&pipeline, &data)};
375 /// let result_string = buffer_to_string(&processor().unwrap()).unwrap();
376 /// let binding = result_string.as_str().replace('\n', "");
377 /// let result_items: Vec<&str> = binding.split(" ").collect();
378 /// let result = result_items.get(2).unwrap().trim().parse::<i32>().unwrap();
379 ///
380 /// assert_eq!(result, 2, "Data was not piped properly!");
381 /// ```
382 ///
383 pub fn pipeline_add_stdin_data_to_pipeline<'a>(pipeline: &'a mut RUMCommandLine, data: &RUMBuffer) -> &'a RUMCommandLine {
384 match pipeline.get_mut(0) {
385 Some(command) => command.data = Some(data.clone()),
386 None => {
387 return pipeline;
388 }
389 };
390
391 pipeline
392 }
393
394 ///
395 /// Flatten the [RUMCommandLine] structure into a single string representing the pipeline and
396 /// print it or log it.
397 ///
398 fn print_pipeline(pipeline: &RUMCommandLine) {
399 let mut pipeline_components = Vec::<RUMString>::with_capacity(pipeline.len());
400
401 for pipe in pipeline.iter() {
402 pipeline_components.push(rumtk_format!("{} {}", pipe.path, pipe.args.clone().join_compact(" ")));
403 }
404
405 println!("Executing {}", pipeline_components.join_compact(" | "));
406 }
407
408 pub fn pipeline_patch_command_args<'a>(cmd: &'a mut RUMCommand, replacements: &StringReplacementPair) -> RUMResult<&'a RUMCommand> {
409 let mut new_args = RUMCommandArgs::with_capacity(cmd.args.len());
410
411 for arg in cmd.args.iter() {
412 new_args.push(string_format(arg, replacements));
413 }
414
415 cmd.args = new_args;
416
417 Ok(cmd)
418 }
419
420 ///
421 /// Patches the arguments of the first command with the pattern=replacement pairs!
422 ///
423 /// ## Example
424 /// ```
425 /// use rumtk_core::core::RUMResult;
426 /// use rumtk_core::pipelines::pipeline_functions::pipeline_patch_args;
427 /// use rumtk_core::pipelines::pipeline_types::{RUMCommand, RUMCommandLine};
428 /// use rumtk_core::rumtk_pipeline_run;
429 /// use rumtk_core::strings::{buffer_to_string, RUMString};
430 /// use rumtk_core::types::RUMBuffer;
431 ///
432 /// let ls_name = "ls";
433 /// let mut ls_command = RUMCommand::default();
434 /// ls_command.path = RUMString::from(ls_name);
435 /// ls_command.args.push(RUMString::from("{options}"));
436 /// let mut pipeline = vec![
437 /// ls_command
438 /// ];
439 /// pipeline_patch_args(&mut pipeline, &[("{options}", "-la")]);
440 ///
441 /// let processor = || -> RUMResult<RUMBuffer> {rumtk_pipeline_run!(&pipeline)};
442 /// let result_string = buffer_to_string(&processor().unwrap()).unwrap();
443 /// let results: Vec<&str> = result_string.as_str().split("\n").collect();
444 /// let dot_dir = results.get(1).unwrap().chars().last().unwrap();
445 ///
446 /// assert_eq!(dot_dir, '.', "Incorrect options passed!");
447 /// ```
448 ///
449 pub fn pipeline_patch_args<'a>(pipeline: &'a mut RUMCommandLine, replacements: &StringReplacementPair) -> RUMResult<&'a RUMCommandLine> {
450 for mut cmd in pipeline.iter_mut() {
451 pipeline_patch_command_args(&mut cmd, replacements)?;
452 }
453 Ok(pipeline)
454 }
455
456 ///
457 /// Await for pipeline to execute in a async friendly manner. Once the pipeline execution ends,
458 /// consume the pipeline and return the output.
459 ///
460 /// ## Example
461 ///
462 /// ```
463 /// use rumtk_core::strings::RUMString;
464 /// use rumtk_core::types::RUMBuffer;
465 /// use rumtk_core::pipelines::pipeline_types::{RUMCommand};
466 /// use rumtk_core::pipelines::pipeline_functions::{pipeline_await_pipeline};
467 /// use rumtk_core::{rumtk_resolve_task};
468 ///
469 /// let ls_name = "ls";
470 /// let mut ls_command = RUMCommand::default();
471 /// ls_command.path = RUMString::from(ls_name);
472 ///
473 /// let wc_name = "wc";
474 /// let mut wc_command = RUMCommand::default();
475 /// wc_command.path = RUMString::from(wc_name);
476 ///
477 /// let pipeline = vec![
478 /// ls_command,
479 /// wc_command
480 /// ];
481 ///
482 /// let result = rumtk_resolve_task!(pipeline_await_pipeline(&pipeline, &RUMBuffer::default())).unwrap();
483 ///
484 /// assert_eq!(result.is_empty(), false, "Pipeline returned no buffer from command wc! => {:?}", &result);
485 /// ```
486 ///
487 pub async fn pipeline_await_pipeline(pipeline: &RUMCommandLine, initial_data: &RUMBuffer) -> RUMPipelineResult {
488 let pipeline_copy = pipeline.clone();
489 let data_copy = initial_data.clone();
490 rumtk_resolve_sync_task!(move || {
491 pipeline_wait_pipeline(&pipeline_copy, &data_copy)
492 })
493 }
494
495 ///
496 /// Await for pipeline to complete execution. Once the pipeline execution ends,
497 /// consume the pipeline and return the output.
498 ///
499 /// ## Example
500 ///
501 /// ```
502 /// use rumtk_core::strings::RUMString;
503 /// use rumtk_core::pipelines::pipeline_types::{RUMCommand};
504 /// use rumtk_core::pipelines::pipeline_functions::{pipeline_wait_pipeline};
505 /// use rumtk_core::types::RUMBuffer;
506 ///
507 /// let ls_name = "ls";
508 /// let mut ls_command = RUMCommand::default();
509 /// ls_command.path = RUMString::from(ls_name);
510 ///
511 /// let wc_name = "wc";
512 /// let mut wc_command = RUMCommand::default();
513 /// wc_command.path = RUMString::from(wc_name);
514 ///
515 /// let pipeline = vec![
516 /// ls_command,
517 /// wc_command
518 /// ];
519 ///
520 /// let result = pipeline_wait_pipeline(&pipeline, &RUMBuffer::default()).unwrap();
521 ///
522 /// assert_eq!(result.is_empty(), false, "Pipeline returned no buffer from command wc! => {:?}", &result);
523 /// ```
524 ///
525 pub fn pipeline_wait_pipeline(pipeline: &RUMCommandLine, initial_data: &RUMBuffer) -> RUMPipelineResult {
526 let mut last_data = initial_data.clone();
527
528 // Print pipeline
529 print_pipeline(&pipeline);
530
531 // Now let's visit each process and await their completion!
532 for c in pipeline.iter() {
533 let mut p = pipeline_generate_command(&c, &last_data)?;
534 pipeline_close_process_stdin(&mut p);
535 println!("Waiting on {}", p.id());
536 last_data = pipeline_get_stdout(p)?;
537 }
538
539 Ok(last_data)
540 }
541}
542
543pub mod pipeline_macros {
544 ///
545 /// Creates a pipeline command out of the provided parameters. Parameters include `path`, `args`,
546 /// and `env`. The command has [RUMCommand](super::pipeline_types::RUMCommand).
547 ///
548 /// `env` is a map of type [RUMCommandEnv](super::pipeline_types::RUMCommandEnv) containing a set of
549 /// key value pair strings that we can use to update the process environment.
550 ///
551 /// ## Example
552 ///
553 /// ### Program Only
554 ///
555 /// ```
556 /// use rumtk_core::rumtk_pipeline_command;
557 ///
558 /// let command = rumtk_pipeline_command!("ls");
559 /// ```
560 ///
561 /// ### Program with Piped Data
562 ///
563 /// ```
564 /// use rumtk_core::rumtk_pipeline_command;
565 /// use rumtk_core::types::RUMBuffer;
566 /// use rumtk_core::strings::RUMStringConversions;
567 ///
568 /// let command = rumtk_pipeline_command!("ls", RUMBuffer::default());
569 /// ```
570 ///
571 /// ### Program with Args
572 ///
573 /// ```
574 /// use rumtk_core::rumtk_pipeline_command;
575 /// use rumtk_core::types::RUMBuffer;
576 /// use rumtk_core::strings::RUMStringConversions;
577 ///
578 /// let command = rumtk_pipeline_command!("ls", RUMBuffer::default(), &vec![
579 /// "-l".to_rumstring()
580 /// ]);
581 /// ```
582 ///
583 #[macro_export]
584 macro_rules! rumtk_pipeline_command {
585 ( $path:expr, $data:expr, $args:expr, $env:expr ) => {{
586 use $crate::pipelines::pipeline_types::RUMCommand;
587
588 RUMCommand::new($path, &Some($data), $args, $env)
589 }};
590 ( $path:expr, $data:expr, $args:expr ) => {{
591 use $crate::pipelines::pipeline_types::{RUMCommand, RUMCommandEnv};
592
593 RUMCommand::new($path, &Some($data), $args, &RUMCommandEnv::default())
594 }};
595 ( $path:expr, $data:expr ) => {{
596 use $crate::pipelines::pipeline_types::{RUMCommand, RUMCommandArgs, RUMCommandEnv};
597
598 RUMCommand::new(
599 $path,
600 &Some($data),
601 &RUMCommandArgs::default(),
602 &RUMCommandEnv::default(),
603 )
604 }};
605 ( $path:expr ) => {{
606 use $crate::pipelines::pipeline_types::{RUMCommand, RUMCommandArgs, RUMCommandEnv};
607 use $crate::types::RUMBuffer;
608
609 RUMCommand::new(
610 $path,
611 &None,
612 &RUMCommandArgs::default(),
613 &RUMCommandEnv::default(),
614 )
615 }};
616 }
617
618 ///
619 /// Given a series of [RUMCommand](super::pipeline_types::RUMCommand) passed to this macro, prepare
620 /// and execute the commands in a pipeline. A pipeline here refers to the Unix style pipeline which is the
621 /// terminal form of a pipeline. The pipeline behaves like it would in the terminal => `ls | wc`.
622 ///
623 /// See [this article](https://cscie26.dce.harvard.edu/~dce-lib113/reference/unix/unix2.html)
624 /// and the [Unix Philosophy](https://cscie2x.dce.harvard.edu/hw/ch01s06.html) to learn more!
625 ///
626 /// ## Example
627 ///
628 /// ### Simple
629 ///
630 /// ```
631 /// use rumtk_core::{rumtk_pipeline_command, rumtk_pipeline_quick_run, rumtk_resolve_task, rumtk_init_threads};
632 /// use rumtk_core::core::{RUMResult};
633 /// use rumtk_core::strings::RUMStringConversions;
634 /// use rumtk_core::types::RUMBuffer;
635 ///
636 /// let f = async || -> RUMResult<()> {
637 /// let result = rumtk_pipeline_quick_run!(
638 /// rumtk_pipeline_command!("ls"),
639 /// rumtk_pipeline_command!("wc")
640 /// ).unwrap();
641 ///
642 /// assert_eq!(result.is_empty(), false, "Pipeline returned no buffer from command wc! => {:?}", &result);
643 /// Ok(())
644 /// };
645 ///
646 /// rumtk_resolve_task!(f()).unwrap();
647 /// ```
648 ///
649 #[macro_export]
650 macro_rules! rumtk_pipeline_quick_run {
651 ( $($command:expr),+ ) => {{
652 use $crate::types::RUMBuffer;
653 use $crate::pipelines::pipeline_functions::{pipeline_wait_pipeline};
654
655 let pipeline = vec![$($command),+];
656
657 pipeline_wait_pipeline(&pipeline, &RUMBuffer::default())
658 }};
659 }
660
661 ///
662 /// Given a series of [RUMCommand](super::pipeline_types::RUMCommand) passed to this macro, prepare
663 /// and execute the commands in a pipeline. A pipeline here refers to the Unix style pipeline which is the
664 /// terminal form of a pipeline. The pipeline behaves like it would in the terminal => `ls | wc`.
665 ///
666 /// See [this article](https://cscie26.dce.harvard.edu/~dce-lib113/reference/unix/unix2.html)
667 /// and the [Unix Philosophy](https://cscie2x.dce.harvard.edu/hw/ch01s06.html) to learn more!
668 ///
669 /// This is the `async` flavor.
670 ///
671 /// ## Example
672 ///
673 /// ### Simple
674 ///
675 /// ```
676 /// use rumtk_core::{rumtk_pipeline_command, rumtk_pipeline_quick_run_async, rumtk_resolve_task, rumtk_init_threads};
677 /// use rumtk_core::core::{RUMResult};
678 /// use rumtk_core::strings::RUMStringConversions;
679 /// use rumtk_core::types::RUMBuffer;
680 ///
681 /// let f = async || -> RUMResult<()> {
682 /// let result = rumtk_pipeline_quick_run_async!(
683 /// rumtk_pipeline_command!("ls"),
684 /// rumtk_pipeline_command!("wc")
685 /// ).await?;
686 ///
687 /// assert_eq!(result.is_empty(), false, "Pipeline returned no buffer from command wc! => {:?}", &result);
688 /// Ok(())
689 /// };
690 ///
691 /// rumtk_resolve_task!(f()).unwrap();
692 /// ```
693 ///
694 #[macro_export]
695 macro_rules! rumtk_pipeline_quick_run_async {
696 ( $($command:expr),+ ) => {{
697 use $crate::types::RUMBuffer;
698 use $crate::pipelines::pipeline_functions::{pipeline_await_pipeline};
699
700 let pipeline = vec![$($command),+];
701
702 pipeline_await_pipeline(&pipeline.clone(), &RUMBuffer::default().clone())
703 }};
704 }
705
706 ///
707 /// This macro is similar to [rumtk_pipeline_quick_run](crate::rumtk_pipeline_quick_run). The difference here
708 /// is that the function takes a pipeline structure ([RUMCommandLine](crate::pipelines::pipeline_types::RUMCommandLine))
709 /// In other words, this macro simply runs an already defined pipeline.
710 ///
711 /// ## Example
712 ///
713 /// ### Run the pipeline
714 /// ```
715 /// use rumtk_core::{rumtk_pipeline_command, rumtk_pipeline_run, rumtk_resolve_task, rumtk_init_threads};
716 /// use rumtk_core::core::{RUMResult};
717 /// use rumtk_core::strings::RUMStringConversions;
718 /// use rumtk_core::types::RUMBuffer;
719 ///
720 /// let f = || -> RUMResult<RUMBuffer> {
721 /// let pipeline = vec![
722 /// rumtk_pipeline_command!("ls"),
723 /// rumtk_pipeline_command!("wc")
724 /// ];
725 ///
726 /// rumtk_pipeline_run!(&pipeline)
727 /// };
728 ///
729 /// f().unwrap();
730 /// ```
731 ///
732 /// ### Pipe Buffer to Pipeline
733 ///
734 /// ```
735 /// use rumtk_core::{rumtk_pipeline_command, rumtk_pipeline_run};
736 /// use rumtk_core::core::RUMResult;
737 /// use rumtk_core::types::RUMBuffer;
738 /// use rumtk_core::strings::{buffer_to_string, string_to_buffer};
739 ///
740 /// const data: &str = "Hello World!";
741 /// const expected: &str = " 0 2 12\n";
742 ///
743 ///
744 /// let f = |input: &RUMBuffer| -> RUMResult<RUMBuffer> {
745 /// let mut pipeline = vec![
746 /// rumtk_pipeline_command!("wc")
747 /// ];
748 ///
749 /// rumtk_pipeline_run!(&pipeline, &input)
750 /// };
751 /// let result = buffer_to_string(&f(&string_to_buffer(data)).unwrap()).unwrap();
752 ///
753 /// assert_eq!(result, expected, "Buffer correctly piped into pipeline!");
754 /// ```
755 ///
756 /// ### Pipe String to Pipeline
757 ///
758 /// ```
759 /// use rumtk_core::{rumtk_pipeline_command, rumtk_pipeline_run};
760 /// use rumtk_core::core::RUMResult;
761 /// use rumtk_core::strings::{string_to_buffer, buffer_to_string};
762 /// use rumtk_core::types::RUMBuffer;
763 ///
764 /// const data: &str = "Hello World!";
765 /// const expected: &str = " 0 2 12\n";
766 ///
767 ///
768 /// let f = |input: &str| -> RUMResult<RUMBuffer> {
769 /// let mut pipeline = vec![
770 /// rumtk_pipeline_command!("wc")
771 /// ];
772 ///
773 /// rumtk_pipeline_run!(&pipeline, &string_to_buffer(input))
774 /// };
775 /// let result = buffer_to_string(&f(data).unwrap()).unwrap();
776 ///
777 /// assert_eq!(result, expected, "String correctly piped into pipeline!");
778 /// ```
779 ///
780 #[macro_export]
781 macro_rules! rumtk_pipeline_run {
782 ( $pipeline:expr ) => {{
783 use $crate::types::RUMBuffer;
784
785 rumtk_pipeline_run!($pipeline, &RUMBuffer::default())
786 }};
787 ( $pipeline:expr, $data:expr ) => {{
788 use $crate::pipelines::pipeline_functions::{pipeline_wait_pipeline};
789
790 pipeline_wait_pipeline($pipeline, $data)
791 }};
792 }
793
794
795 ///
796 /// This macro is similar to [rumtk_pipeline_quick_run_async](crate::rumtk_pipeline_quick_run_async). The difference here
797 /// is that the function takes a pipeline structure ([RUMCommandLine](crate::pipelines::pipeline_types::RUMCommandLine))
798 /// In other words, this macro simply runs an already defined pipeline.
799 ///
800 /// ## Example
801 /// ```
802 /// use rumtk_core::{rumtk_pipeline_command, rumtk_pipeline_run_async, rumtk_resolve_task, rumtk_init_threads};
803 /// use rumtk_core::core::{RUMResult};
804 /// use rumtk_core::strings::RUMStringConversions;
805 /// use rumtk_core::types::RUMBuffer;
806 ///
807 /// let f = async || -> RUMResult<RUMBuffer> {
808 /// let pipeline = vec![
809 /// rumtk_pipeline_command!("ls"),
810 /// rumtk_pipeline_command!("wc")
811 /// ];
812 ///
813 /// rumtk_pipeline_run_async!(&pipeline).await
814 /// };
815 ///
816 /// rumtk_resolve_task!(f()).unwrap();
817 /// ```
818 ///
819 /// ### Pipe Buffer to Pipeline
820 ///
821 /// ```
822 /// use rumtk_core::{rumtk_pipeline_command, rumtk_pipeline_run_async, rumtk_resolve_task, rumtk_spawn_task};
823 /// use rumtk_core::core::RUMResult;
824 /// use rumtk_core::types::RUMBuffer;
825 /// use rumtk_core::strings::{buffer_to_string, string_to_buffer};
826 ///
827 /// const data: &str = "Hello World!";
828 /// const expected: &str = " 0 2 12\n";
829 ///
830 ///
831 /// let task = rumtk_spawn_task!(async {
832 /// let input = RUMBuffer::from("Hello World!");
833 /// let mut pipeline = vec![
834 /// rumtk_pipeline_command!("wc")
835 /// ];
836 ///
837 /// rumtk_pipeline_run_async!(&pipeline, &input).await
838 /// });
839 ///
840 /// let result = buffer_to_string(&rumtk_resolve_task!(task).unwrap().unwrap()).unwrap();
841 ///
842 /// assert_eq!(result, expected, "Buffer correctly piped into pipeline!");
843 /// ```
844 ///
845 /// ### Pipe String to Pipeline
846 ///
847 /// ```
848 /// use rumtk_core::{rumtk_pipeline_command, rumtk_pipeline_run_async, rumtk_resolve_task, rumtk_spawn_task};
849 /// use rumtk_core::core::RUMResult;
850 /// use rumtk_core::strings::{string_to_buffer, buffer_to_string};
851 /// use rumtk_core::types::RUMBuffer;
852 ///
853 /// const data: &str = "Hello World!";
854 /// const expected: &str = " 0 2 12\n";
855 ///
856 ///
857 /// let task = rumtk_spawn_task!(async {
858 /// let input = string_to_buffer(data);
859 /// let mut pipeline = vec![
860 /// rumtk_pipeline_command!("wc")
861 /// ];
862 ///
863 /// rumtk_pipeline_run_async!(&pipeline, &input).await
864 /// });
865 ///
866 /// let result = buffer_to_string(&rumtk_resolve_task!(task).unwrap().unwrap()).unwrap();
867 ///
868 /// assert_eq!(result, expected, "String correctly piped into pipeline!");
869 /// ```
870 ///
871 #[macro_export]
872 macro_rules! rumtk_pipeline_run_async {
873 ( $pipeline:expr ) => {{
874 use $crate::types::RUMBuffer;
875
876 rumtk_pipeline_run_async!($pipeline, &RUMBuffer::default())
877 }};
878 ( $pipeline:expr, $data:expr ) => {{
879 use $crate::pipelines::pipeline_functions::{pipeline_await_pipeline};
880
881 pipeline_await_pipeline($pipeline, $data)
882 }};
883 }
884
885 ///
886 /// Patch the pipeline's arguments with desired dynamic options.
887 ///
888 /// ## Example
889 /// ```
890 /// use rumtk_core::{rumtk_pipeline_patch_args, rumtk_pipeline_command, rumtk_pipeline_run};
891 /// use rumtk_core::core::RUMResult;
892 /// use rumtk_core::strings::buffer_to_string;
893 /// use rumtk_core::types::RUMBuffer;
894 /// use rumtk_core::strings::string_to_buffer;
895 ///
896 ///
897 /// let f = || -> RUMResult<RUMBuffer> {
898 /// let mut pipeline = vec![
899 /// rumtk_pipeline_command!("ls", RUMBuffer::default(), &vec![
900 /// "{options}".into()
901 /// ])
902 /// ];
903 ///
904 /// rumtk_pipeline_patch_args!(&mut pipeline, &[("{options}", "-la")]);
905 ///
906 /// rumtk_pipeline_run!(&pipeline)
907 /// };
908 ///
909 /// let result_string = buffer_to_string(&f().unwrap()).unwrap();
910 /// let results: Vec<&str> = result_string.as_str().split("\n").collect();
911 /// let dot_dir = results.get(1).unwrap().chars().last().unwrap();
912 ///
913 /// assert_eq!(dot_dir, '.', "Incorrect options passed!");
914 /// ```
915 ///
916 #[macro_export]
917 macro_rules! rumtk_pipeline_patch_args {
918 ( $pipeline:expr, $replacements:expr ) => {{
919 use $crate::pipelines::pipeline_functions::{pipeline_patch_args};
920
921 pipeline_patch_args($pipeline, $replacements)
922 }};
923 }
924}