├── samples ├── example.env ├── example.yml ├── gen-env.sh ├── gen-yml.sh ├── gen-md.sh ├── code.rb └── example.md ├── .gitignore ├── shell.nix ├── renovate.json ├── .pre-commit-hooks.yaml ├── .github └── workflows │ └── ci.yaml ├── ci.sh ├── .pre-commit-config.yaml ├── _config.yml ├── Cargo.toml ├── src ├── nom_ext.rs ├── cli.rs ├── main.rs ├── lib.rs ├── gen_test_md.rs ├── executor.rs └── parser.rs ├── LICENSE ├── flake.lock ├── flake.nix ├── CHANGELOG.md ├── default.nix ├── Cargo.lock ├── README.md ├── spec.clear.md └── spec.processed.md /samples/example.env: -------------------------------------------------------------------------------- 1 | foo=bar 2 | -------------------------------------------------------------------------------- /samples/example.yml: -------------------------------------------------------------------------------- 1 | foo: bar 2 | -------------------------------------------------------------------------------- /samples/gen-env.sh: -------------------------------------------------------------------------------- 1 | echo "foo=bar" 2 | -------------------------------------------------------------------------------- /samples/gen-yml.sh: -------------------------------------------------------------------------------- 1 | echo "foo: bar" 2 | -------------------------------------------------------------------------------- /samples/gen-md.sh: -------------------------------------------------------------------------------- 1 | echo "I'm gen-md.sh" 2 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Rust 2 | /target 3 | /src/tests.rs 4 | -------------------------------------------------------------------------------- /samples/code.rb: -------------------------------------------------------------------------------- 1 | require "pp" 2 | 3 | pp ({ foo: 3 }) 4 | -------------------------------------------------------------------------------- /samples/example.md: -------------------------------------------------------------------------------- 1 | *this is part of the example.md file* 2 | -------------------------------------------------------------------------------- /shell.nix: -------------------------------------------------------------------------------- 1 | { system ? builtins.currentSystem }: 2 | (import ./. { src = ./.; inherit system; }).shellNix.default 3 | -------------------------------------------------------------------------------- /renovate.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "https://docs.renovatebot.com/renovate-schema.json", 3 | "extends": [ 4 | "config:base" 5 | ] 6 | } 7 | -------------------------------------------------------------------------------- /.pre-commit-hooks.yaml: -------------------------------------------------------------------------------- 1 | - id: mdsh 2 | name: mdsh 3 | description: README.md shell pre-processor. 4 | entry: mdsh --inputs 5 | language: rust 6 | files: README.md 7 | minimum_pre_commit_version: 1.18.1 8 | -------------------------------------------------------------------------------- /.github/workflows/ci.yaml: -------------------------------------------------------------------------------- 1 | name: "CI" 2 | on: 3 | pull_request: 4 | push: 5 | jobs: 6 | tests: 7 | strategy: 8 | matrix: 9 | os: [ubuntu-latest, macos-latest] 10 | runs-on: ${{ matrix.os }} 11 | steps: 12 | - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4 13 | - uses: cachix/install-nix-action@91a071959513ca103b54280ac0bef5b825791d4d # v31 14 | - run: ./ci.sh 15 | -------------------------------------------------------------------------------- /ci.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env nix-shell 2 | #!nix-shell -i bash -I nixpkgs=channel:nixos-22.05 3 | # shellcheck shell=bash 4 | # 5 | # Travis CI specific build script 6 | set -euo pipefail 7 | 8 | ## Functions ## 9 | 10 | run() { 11 | echo >&2 12 | echo "$ $*" >&2 13 | "$@" 14 | } 15 | 16 | ## Main ## 17 | 18 | mkdir -p "${TMPDIR}" 19 | 20 | # build mdsh 21 | run cargo build --verbose 22 | 23 | # run after build, pre-commit needs mdsh 24 | run pre-commit run --all-files 25 | 26 | # run the tests 27 | run cargo test --verbose 28 | -------------------------------------------------------------------------------- /.pre-commit-config.yaml: -------------------------------------------------------------------------------- 1 | # See https://pre-commit.com for more information 2 | # See https://pre-commit.com/hooks.html for more hooks 3 | repos: 4 | - repo: https://github.com/doublify/pre-commit-rust 5 | rev: ebc9050d3d3434417feff68e3d847ad4123f5ba8 6 | hooks: 7 | - id: fmt 8 | - id: cargo-check 9 | 10 | - repo: local 11 | hooks: 12 | - id: mdsh 13 | name: mdsh 14 | description: README.md shell pre-processor. 15 | entry: cargo run -- --inputs 16 | language: system 17 | files: README.md 18 | always_run: true 19 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | theme: jekyll-theme-primer 2 | title: "`$ mdsh`" 3 | description: "a markdown shell pre-processor" 4 | url: "https://zimbatm.github.io/mdsh" 5 | author: 6 | twitter: zimbatm 7 | github: zimbatm 8 | 9 | # see https://github.com/github/pages-gem/blob/754a725e4766d4329bb1dd0e07c638a045ad2c04/lib/github-pages/plugins.rb#L6-L42 10 | plugins: 11 | - jemoji 12 | - jekyll-avatar 13 | - jekyll-default-layout 14 | - jekyll-feed 15 | - jekyll-mentions 16 | - jekyll-readme-index 17 | - jekyll-sitemap 18 | 19 | markdown: CommonMarkGhPages 20 | # see https://github.com/gjtorikian/commonmarker#parse-options 21 | commonmark: 22 | options: 23 | - FOOTNOTES 24 | - SMART 25 | extensions: 26 | - autolink 27 | - strikethrough 28 | - table 29 | -------------------------------------------------------------------------------- /Cargo.toml: -------------------------------------------------------------------------------- 1 | [package] 2 | name = "mdsh" 3 | version = "0.9.2" 4 | authors = ["zimbatm "] 5 | edition = "2021" 6 | description = "Markdown shell pre-processor" 7 | homepage = "https://github.com/zimbatm/mdsh" 8 | repository = "https://github.com/zimbatm/mdsh" 9 | keywords = [ 10 | "markdown", 11 | "shell", 12 | ] 13 | readme = "README.md" 14 | license = "MIT" 15 | default-run = "mdsh" 16 | 17 | [[bin]] 18 | name = "gen-test-md" 19 | path = "src/gen_test_md.rs" 20 | 21 | [badges.travis-ci] 22 | repository = "zimbatm/mdsh" 23 | 24 | [dependencies] 25 | anyhow = "1.0.98" 26 | clap = { version = "4", features = ["derive"] } 27 | nom = { version = "8.0.0", default-features = false } 28 | nom-language = "0.1.0" 29 | shellexpand = { version = "3", default-features = false, features = ["base-0"] } 30 | 31 | [dev-dependencies] 32 | dedent = "0.1.1" 33 | -------------------------------------------------------------------------------- /src/nom_ext.rs: -------------------------------------------------------------------------------- 1 | /// A hacky wrapper to allow to "`Clone`" `Parser`s 2 | pub struct FnParser

(fn() -> P, Option

); 3 | 4 | impl

Clone for FnParser

{ 5 | fn clone(&self) -> Self { 6 | FnParser(self.0, None) 7 | } 8 | } 9 | 10 | impl

FnParser

{ 11 | pub fn new(init: fn() -> P) -> Self { 12 | Self(init, None) 13 | } 14 | } 15 | 16 | impl<'a, P: nom::Parser<&'a str>> nom::Parser<&'a str> for FnParser

{ 17 | type Output = P::Output; 18 | type Error = P::Error; 19 | fn process( 20 | &mut self, 21 | input: &'a str, 22 | ) -> nom::PResult { 23 | if let Some(parser) = self.1.as_mut() { 24 | parser.process::(input) 25 | } else { 26 | let mut parser = self.0(); 27 | let res = parser.process::(input); 28 | self.1 = Some(parser); 29 | res 30 | } 31 | } 32 | } 33 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2019 zimbatm and contributors 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /flake.lock: -------------------------------------------------------------------------------- 1 | { 2 | "nodes": { 3 | "nixpkgs": { 4 | "locked": { 5 | "lastModified": 1718396522, 6 | "narHash": "sha256-C0re6ZtCqC1ndL7ib7vOqmgwvZDhOhJ1W0wQgX1tTIo=", 7 | "owner": "nixos", 8 | "repo": "nixpkgs", 9 | "rev": "3e6b9369165397184774a4b7c5e8e5e46531b53f", 10 | "type": "github" 11 | }, 12 | "original": { 13 | "owner": "nixos", 14 | "ref": "nixpkgs-unstable", 15 | "repo": "nixpkgs", 16 | "type": "github" 17 | } 18 | }, 19 | "root": { 20 | "inputs": { 21 | "nixpkgs": "nixpkgs", 22 | "systems": "systems" 23 | } 24 | }, 25 | "systems": { 26 | "locked": { 27 | "lastModified": 1681028828, 28 | "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=", 29 | "owner": "nix-systems", 30 | "repo": "default", 31 | "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e", 32 | "type": "github" 33 | }, 34 | "original": { 35 | "owner": "nix-systems", 36 | "repo": "default", 37 | "type": "github" 38 | } 39 | } 40 | }, 41 | "root": "root", 42 | "version": 7 43 | } 44 | -------------------------------------------------------------------------------- /flake.nix: -------------------------------------------------------------------------------- 1 | { 2 | description = "mdsh - a markdown shell pre-processor"; 3 | inputs = { 4 | nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable"; 5 | systems.url = "github:nix-systems/default"; 6 | }; 7 | outputs = 8 | { 9 | self, 10 | nixpkgs, 11 | systems, 12 | }: 13 | let 14 | version = (lib.importTOML "${self}/Cargo.toml").package.version; 15 | 16 | inherit (nixpkgs) lib; 17 | fs = lib.fileset; 18 | eachSystem = f: lib.genAttrs (import systems) (system: f nixpkgs.legacyPackages.${system}); 19 | in 20 | { 21 | devShells = eachSystem (pkgs: { 22 | default = pkgs.mkShell { 23 | buildInputs = [ 24 | pkgs.cargo 25 | pkgs.gitAndTools.git-extras 26 | pkgs.gitAndTools.pre-commit 27 | pkgs.libiconv 28 | pkgs.rust-analyzer 29 | pkgs.rustc 30 | pkgs.rustfmt 31 | ]; 32 | 33 | shellHook = '' 34 | export PATH=$PWD/target/debug:$PATH 35 | export RUST_SRC_PATH="${pkgs.rust.packages.stable.rustPlatform.rustLibSrc}"; 36 | ''; 37 | }; 38 | }); 39 | 40 | packages = eachSystem (pkgs: { 41 | default = pkgs.rustPlatform.buildRustPackage { 42 | pname = "mdsh"; 43 | inherit version; 44 | 45 | src = fs.toSource { 46 | root = ./.; 47 | fileset = fs.unions [ 48 | ./Cargo.toml 49 | ./Cargo.lock 50 | ./src 51 | ./spec.clear.md 52 | ./spec.processed.md 53 | ./samples 54 | ]; 55 | }; 56 | 57 | cargoLock.lockFile = ./Cargo.lock; 58 | 59 | meta = with lib; { 60 | description = "Markdown shell pre-processor"; 61 | homepage = "https://github.com/zimbatm/mdsh"; 62 | license = with licenses; [ mit ]; 63 | maintainers = with maintainers; [ zimbatm ]; 64 | mainProgram = "mdsh"; 65 | }; 66 | }; 67 | }); 68 | }; 69 | } 70 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | 2 | 0.9.2 / 2025-03-17 3 | ================== 4 | 5 | * chore: update `--help` output to fix test (#81) 6 | * fix: add `--version` back (#80) 7 | * chore: fmt 8 | 9 | 0.9.1 / 2025-03-14 10 | ================== 11 | 12 | * fix(README): update mdsh output 13 | * fix(deps): update rust crate clap to v4.5.32 (#79) 14 | * fix(deps): update rust crate lazy_static to v1.5.0 (#68) 15 | * fix(deps): update rust crate regex to v1.11.1 (#71) 16 | * chore(deps): update actions/checkout digest to 11bd719 (#73) 17 | * chore(deps): update cachix/install-nix-action action to v31 (#77) 18 | * cli: port from structopt to clap/derive (#75) 19 | * chore(deps): update cachix/install-nix-action action to v30 (#72) 20 | * chore(deps): update cachix/install-nix-action action to v29 (#70) 21 | * fix(deps): update rust crate regex to v1.10.6 (#69) 22 | * chore(nix): read deps from Cargo.lock directly 23 | 24 | 0.9.0 / 2024-06-17 25 | ================== 26 | 27 | * chore(deps): update actions/checkout digest to 692973e (#64) 28 | * chore(nix): fix shell invocation 29 | * chore(deps): cargo update 30 | * chore(deps): flake update 31 | * chore(flake): replace flake-utils with systems 32 | * chore(deps): update cachix/install-nix-action action to v27 (#66) 33 | * Merge pull request #63 from deemp/main 34 | * fix: mdsh derivation - don't depend on readme - update hash - bump patch version 35 | * chore: bump version 36 | * fix: improve messages about failing commands 37 | * fix: set RUST_SRC_PATH 38 | * chore(deps): update cachix/install-nix-action action to v26 (#60) 39 | 40 | 0.8.0 / 2024-02-27 41 | ================== 42 | 43 | * FEAT: support multiline commands (#59) 44 | * FEAT: add Nix package and describe usage with flakes (#59) 45 | * FIX: print newline after command 46 | * CHORE: update readme 47 | * CHORE: switch default branch to main 48 | * CHORE: update deps 49 | 50 | 0.7.0 / 2023-02-03 51 | ================== 52 | 53 | * FEAT: add support for multiple inputs (#33) 54 | * FIX: add libiconv as a dev dependency 55 | * FIX: avoid writing if no change 56 | * README: make the run reproducible 57 | * CHORE: fix CI on macOS 58 | * CHORE: fix warning 59 | * CHORE: Bump regex from 1.4.3 to 1.5.5 (#31) 60 | 61 | 0.6.0 / 2021-02-26 62 | ================== 63 | 64 | * CHANGE: handle empty lines between command and result 65 | * bump dependencies 66 | 67 | 0.5.0 / 2020-05-08 68 | ================== 69 | 70 | * NEW: add variables support (#27) 71 | 72 | 0.4.0 / 2020-01-12 73 | ================== 74 | 75 | * NEW: Codefence type (#26) 76 | 77 | 0.3.0 / 2019-10-19 78 | ================== 79 | 80 | * CHANGE: use the RHS of the link as a source. 81 | Eg: `$ [before.rb](after.rb)` now loads `after.rb` instead of `before.rb` 82 | 83 | 0.2.0 / 2019-10-08 84 | ================== 85 | 86 | * FEAT: add support for commented-out commands 87 | * FIX: fix line collapsing 88 | 89 | 0.1.5 / 2019-08-24 90 | ================== 91 | 92 | * FEAT: add pre-commit hooks 93 | * improve diff output for --frozen 94 | 95 | 0.1.4 / 2019-08-01 96 | ================== 97 | 98 | * FEAT: implement --frozen option (#13) 99 | * FEAT: filter out ANSI escape characters (#22) 100 | * FEAT: better error messages on read/write errors (#18) 101 | * DOC: improved documentation overall 102 | 103 | 0.1.3 / 2019-02-18 104 | ================== 105 | 106 | * FEAT: allow switching between outputs 107 | * FEAT: add support for work_dir. Fixes #5 108 | * README: add installation instructions 109 | * README: clarify the syntax 110 | * README: Fix typos (#3) 111 | 112 | 0.1.2 / 2019-02-17 113 | ================== 114 | 115 | * pin nixpkgs 116 | * README: improve the docs 117 | 118 | 0.1.1 / 2019-02-16 119 | ================== 120 | 121 | * README: add badges 122 | * cargo fmt 123 | * Cargo.toml: add metadata 124 | 125 | 0.1.0 / 2019-02-16 126 | ================== 127 | 128 | * add linking support 129 | * support stdin and stdout 130 | * basic implementation 131 | -------------------------------------------------------------------------------- /src/cli.rs: -------------------------------------------------------------------------------- 1 | //! Command line interface 2 | use std::{ 3 | path::{Path, PathBuf}, 4 | str::FromStr, 5 | }; 6 | 7 | use clap::Parser; 8 | 9 | /// Markdown shell pre-processor. 10 | /// Never let your READMEs and tutorials get out of sync again. 11 | /// 12 | /// Exits non-zero if a sub-command failed. 13 | #[derive(Debug, Parser)] 14 | #[clap(name = "mdsh", version = env!("CARGO_PKG_VERSION"))] 15 | pub struct Opt { 16 | /// Path to the markdown files. `-` for stdin. 17 | #[clap( 18 | short = 'i', 19 | long = "inputs", 20 | alias = "input", 21 | default_value = "./README.md", 22 | num_args = 1.., 23 | )] 24 | pub inputs: Vec, 25 | 26 | /// Path to the output file, `-` for stdout [defaults to updating the input file in-place]. 27 | #[clap(short = 'o', long = "output")] 28 | pub output: Option, 29 | 30 | /// Directory to execute the scripts under [defaults to the input file’s directory]. 31 | #[clap(short = 'w', long = "work-dir")] 32 | pub work_dir: Option, 33 | 34 | /// Fail if the output is different from the input. Useful for CI. 35 | /// 36 | /// Using `--frozen`, you can guarantee that developers update 37 | /// documentation when they make a change. Just add `mdsh --frozen` 38 | /// as a check to your continuous integration setup. 39 | #[clap(long = "frozen", conflicts_with = "clean")] 40 | pub frozen: bool, 41 | 42 | /// Remove all generated blocks. 43 | #[clap(long = "clean")] 44 | pub clean: bool, 45 | } 46 | 47 | /// Possible file input (either a file name or `-`) 48 | #[derive(Clone)] 49 | pub enum FileArg { 50 | /// equal to - (so stdin or stdout) 51 | StdHandle, 52 | File(PathBuf), 53 | } 54 | 55 | impl std::fmt::Debug for FileArg { 56 | fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> Result<(), std::fmt::Error> { 57 | match self { 58 | Self::StdHandle => write!(f, "-"), 59 | Self::File(buf) => buf.fmt(f), 60 | } 61 | } 62 | } 63 | 64 | impl FileArg { 65 | /// Return the parent, if it is a `StdHandle` use the current directory. 66 | /// Returns `None` if there is no parent (that is we are `/`). 67 | pub fn parent(&self) -> Option { 68 | match self { 69 | FileArg::StdHandle => Some(Parent::current_dir()), 70 | FileArg::File(buf) => Parent::of(buf), 71 | } 72 | } 73 | 74 | /// return a `FileArg::File`, don’t parse 75 | pub fn from_str_unsafe(s: &str) -> Self { 76 | FileArg::File(PathBuf::from(s)) 77 | } 78 | } 79 | 80 | impl FromStr for FileArg { 81 | type Err = std::string::ParseError; 82 | fn from_str(s: &str) -> Result { 83 | match s { 84 | "-" => Ok(FileArg::StdHandle), 85 | p => Ok(FileArg::File(PathBuf::from(p))), 86 | } 87 | } 88 | } 89 | 90 | /// Parent path, gracefully handling relative path inputs 91 | #[derive(Debug, Clone)] 92 | pub struct Parent(PathBuf); 93 | 94 | impl Parent { 95 | /// Create from a `Path`, falling back to the 96 | /// `current_dir()` if necessary. 97 | /// Returns `None` if there is no parent (that is we are `/`). 98 | pub fn of(p: &Path) -> Option { 99 | let prnt = p.parent()?; 100 | if prnt.as_os_str().is_empty() { 101 | Some(Self::current_dir()) 102 | } else { 103 | Some(Parent(prnt.to_path_buf())) 104 | } 105 | } 106 | 107 | /// Creates a `Parent` that is the current directory. 108 | /// Asks the operating system for the path. 109 | pub fn current_dir() -> Self { 110 | Parent( 111 | std::env::current_dir().expect( 112 | "fatal: current working directory not accessible and `--work-dir` not given", 113 | ), 114 | ) 115 | } 116 | 117 | /// Convert from a `PathBuf` that is already a parent. 118 | pub fn from_parent_path_buf(buf: PathBuf) -> Self { 119 | Parent(buf) 120 | } 121 | 122 | pub fn as_path_buf(&self) -> &PathBuf { 123 | &self.0 124 | } 125 | } 126 | -------------------------------------------------------------------------------- /src/main.rs: -------------------------------------------------------------------------------- 1 | use std::{ 2 | fs::File, 3 | io::{self, prelude::*}, 4 | }; 5 | 6 | use anyhow::Context; 7 | 8 | /// Trims trailing ASCII whitespace from a byte slice. 9 | /// Stable alternative to the unstable `trim_ascii_end()` method. 10 | fn trim_ascii_end(bytes: &[u8]) -> &[u8] { 11 | let mut end = bytes.len(); 12 | while end > 0 && bytes[end - 1].is_ascii_whitespace() { 13 | end -= 1; 14 | } 15 | &bytes[..end] 16 | } 17 | use clap::Parser; 18 | use mdsh::{ 19 | cli::{FileArg, Opt, Parent}, 20 | executor::TheProcessor, 21 | Cleaner, Processor, 22 | }; 23 | 24 | fn main() -> anyhow::Result<()> { 25 | let opt = Opt::parse(); 26 | let clean = opt.clean; 27 | let frozen = opt.frozen; 28 | let inputs = opt.inputs; 29 | 30 | if let [_, _, ..] = &inputs[..] { 31 | opt.output 32 | .is_none() 33 | .then_some(()) 34 | .context("--output is not compatible with multiple inputs")?; 35 | opt.work_dir 36 | .is_none() 37 | .then_some(()) 38 | .context("--work-dir is not compatible with multiple inputs")?; 39 | for input in inputs { 40 | let work_dir = input 41 | .clone() 42 | .parent() 43 | .context("an input file has no parent directory")?; 44 | let output = input.clone(); 45 | process_file(&input, &output, &work_dir, clean, frozen)?; 46 | } 47 | } else if let [input, ..] = &inputs[..] { 48 | let output = opt.output.unwrap_or_else(|| input.clone()); 49 | let work_dir: Parent = opt.work_dir.map_or_else( 50 | || { 51 | input 52 | .clone() 53 | .parent() 54 | .context("the input file has no parent directory.") 55 | }, 56 | |buf| Ok(Parent::from_parent_path_buf(buf)), 57 | )?; 58 | process_file(input, &output, &work_dir, clean, frozen)?; 59 | } 60 | 61 | Ok(()) 62 | } 63 | 64 | fn process_file( 65 | input: &FileArg, 66 | output: &FileArg, 67 | work_dir: &Parent, 68 | clean: bool, 69 | frozen: bool, 70 | ) -> anyhow::Result<()> { 71 | let input_content = read_file(input)?; 72 | 73 | let work_dir = work_dir.as_path_buf().as_os_str(); 74 | match (input, output) { 75 | (FileArg::File(inf), FileArg::File(outf)) if inf == outf => { 76 | let mut buffer = Vec::with_capacity(8192); 77 | if clean { 78 | Cleaner::new(&mut buffer).process(&input_content, input)?; 79 | } else { 80 | TheProcessor::new(work_dir, &mut buffer).process(&input_content, input)?; 81 | } 82 | let file_unmodified_check = !frozen || input_content.as_bytes() == buffer; 83 | 84 | std::fs::write(outf, trim_ascii_end(&buffer)) 85 | .with_context(|| format!("failed to write file {outf:?}"))?; 86 | 87 | file_unmodified_check 88 | .then_some(()) 89 | .context("File modified")?; 90 | } 91 | (_, FileArg::File(outf)) => { 92 | let mut outf_handle = File::create(outf) 93 | .with_context(|| format!("failed to open file {outf:?} for writing"))?; 94 | if clean { 95 | Cleaner::new(&mut outf_handle).process(&input_content, input)?; 96 | } else { 97 | TheProcessor::new(work_dir, &mut outf_handle).process(&input_content, input)?; 98 | } 99 | } 100 | (_, FileArg::StdHandle) => { 101 | if clean { 102 | Cleaner::new(&mut io::stdout()).process(&input_content, input)?; 103 | } else { 104 | TheProcessor::new(work_dir, &mut io::stdout()).process(&input_content, input)?; 105 | } 106 | } 107 | } 108 | Ok(()) 109 | } 110 | 111 | fn read_file(f: &FileArg) -> anyhow::Result { 112 | let mut buffer = String::with_capacity(8192); 113 | 114 | match f { 115 | FileArg::StdHandle => { 116 | let stdin = io::stdin(); 117 | let mut handle = stdin.lock(); 118 | handle 119 | .read_to_string(&mut buffer) 120 | .context("failed to read from stdin")?; 121 | } 122 | FileArg::File(path_buf) => { 123 | File::open(path_buf) 124 | .with_context(|| format!("failed to open file {:?}", path_buf.display()))? 125 | .read_to_string(&mut buffer) 126 | .with_context(|| format!("failed to read file {:?}", path_buf.display()))?; 127 | } 128 | } 129 | 130 | Ok(buffer) 131 | } 132 | 133 | /* 134 | fn trail_nl>(s: T) -> String { 135 | let r = s.as_ref(); 136 | if r.ends_with('\n') { 137 | r.to_string() 138 | } else { 139 | format!("{}\n", r) 140 | } 141 | } 142 | 143 | // make sure that the string starts and ends with new lines 144 | fn wrap_nl(s: String) -> String { 145 | if s.starts_with('\n') { 146 | trail_nl(s) 147 | } else if s.ends_with('\n') { 148 | format!("\n{}", s) 149 | } else { 150 | format!("\n{}\n", s) 151 | } 152 | } 153 | 154 | // remove all ANSI escape characters 155 | fn filter_ansi(s: String) -> String { 156 | RE_ANSI_FILTER.replace_all(&s, "").to_string() 157 | } 158 | */ 159 | -------------------------------------------------------------------------------- /src/lib.rs: -------------------------------------------------------------------------------- 1 | pub mod cli; 2 | pub mod executor; 3 | mod nom_ext; 4 | pub mod parser; 5 | 6 | use std::io::Write; 7 | 8 | use anyhow::{Context, Result}; 9 | use nom::Finish; 10 | 11 | use crate::parser::fmt_nom_error; 12 | 13 | const BEGIN_MDSH: &str = ""; 14 | const END_MDSH: &str = ""; 15 | 16 | pub trait Processor<'a> { 17 | fn process_piece(&mut self, piece: MdPiece<'a>) -> Result<()>; 18 | 19 | fn process(&'a mut self, input: &'a str, input_pipe: &cli::FileArg) -> Result<()> { 20 | // TODO: consider streaming directly from BufReader or smth, 21 | // see https://github.com/rust-bakery/nom/issues/1145 22 | let mut iter = nom::combinator::iterator(input, parser::markdown_piece()); 23 | 24 | for piece in iter.by_ref() { 25 | self.process_piece(piece) 26 | .context("processing markdown piece")?; 27 | } 28 | 29 | let (_input, _) = iter 30 | .finish() 31 | .finish() 32 | .map_err(fmt_nom_error(input, &format!("{input_pipe:?}"))) 33 | .context("parsing markdown")?; 34 | 35 | Ok(()) 36 | } 37 | } 38 | 39 | pub struct Cleaner { 40 | pub out: W, 41 | } 42 | 43 | impl Cleaner { 44 | pub fn new(out: W) -> Self { 45 | Self { out } 46 | } 47 | } 48 | 49 | impl<'a, W: Write> Processor<'a> for Cleaner { 50 | fn process_piece(&mut self, piece: MdPiece<'a>) -> Result<()> { 51 | match piece { 52 | MdPiece::FencedBlock => (), 53 | MdPiece::Action((source, _action)) => { 54 | self.out.write_all(source.as_bytes())?; 55 | } 56 | MdPiece::RawLine(raw_line) => { 57 | self.out.write_all(raw_line.as_bytes())?; 58 | } 59 | } 60 | Ok(()) 61 | } 62 | } 63 | 64 | #[derive(Debug)] 65 | pub enum MdPiece<'a> { 66 | FencedBlock, 67 | Action(parser::ActionWithSource<'a>), 68 | RawLine(&'a str), 69 | } 70 | 71 | #[cfg(test)] 72 | pub(crate) mod test { 73 | use crate::{cli::FileArg, executor::TheProcessor, Cleaner, Processor}; 74 | 75 | pub(crate) fn process(input: &str) -> anyhow::Result { 76 | let mut buf = Vec::new(); 77 | TheProcessor::new(std::ffi::OsStr::new("."), &mut buf) 78 | .process(input, &FileArg::StdHandle)?; 79 | Ok(String::from_utf8(buf)?) 80 | } 81 | 82 | fn process_clean(input: &str) -> anyhow::Result { 83 | let mut buf = Vec::new(); 84 | Cleaner::new(&mut buf).process(input, &FileArg::StdHandle)?; 85 | Ok(String::from_utf8(buf)?) 86 | } 87 | 88 | macro_rules! assert_process_eq { 89 | ($i:tt, $o:tt) => { 90 | const ANSI_R: &str = "\x1b[1;31m"; 91 | const ANSI_G: &str = "\x1b[1;32m"; 92 | const ANSI_B: &str = "\x1b[1;34m"; 93 | const ANSI_0: &str = "\x1b[0m"; 94 | const EOF_M: &str = "\x1b[1;33mEOF\x1b[0m"; 95 | 96 | let input = $i; 97 | println!("{ANSI_B}INPUT ============={ANSI_0}\n{}{EOF_M}", input); 98 | let result = process(&input) 99 | .inspect_err(|e| println!("{e}")) 100 | .expect("processing"); 101 | let expected = $o; 102 | 103 | if result != expected { 104 | println!("{ANSI_R}RESULT ============{ANSI_0}\n{}{EOF_M}", result); 105 | println!("{ANSI_G}EXPECTED =========={ANSI_0}\n{}{EOF_M}", expected); 106 | } 107 | assert_eq!(result, expected, "unexpected processing result"); 108 | 109 | let result2 = process(&result) 110 | .inspect_err(|e| println!("{e}")) 111 | .expect("second processing"); 112 | if result != result2 { 113 | println!("{ANSI_R}RESULT 2 =========={ANSI_0}\n{}{EOF_M}", result2); 114 | println!("{ANSI_G}EXPECTED =========={ANSI_0}\n{}{EOF_M}", expected); 115 | } 116 | 117 | assert_eq!(result, result2, "processing is not idempotent"); 118 | }; 119 | } 120 | pub(crate) use assert_process_eq; 121 | 122 | #[test] 123 | fn test_whole_file() { 124 | let file_in = String::from_utf8(std::fs::read("spec.clear.md").unwrap()).unwrap(); 125 | let file_out = String::from_utf8(std::fs::read("spec.processed.md").unwrap()).unwrap(); 126 | let result = process(&file_in) 127 | .inspect_err(|e| println!("{e}")) 128 | .expect("processing"); 129 | if result != file_out { 130 | std::fs::write("/tmp/tmp.md", &result).unwrap(); 131 | } 132 | 133 | assert_eq!( 134 | result, file_out, 135 | "unexpected result, see `diff /tmp/tmp.md spec.clear.md`" 136 | ); 137 | } 138 | 139 | #[test] 140 | fn test_whole_file_idempotency() { 141 | let file_in = String::from_utf8(std::fs::read("spec.processed.md").unwrap()).unwrap(); 142 | let result = process(&file_in) 143 | .inspect_err(|e| println!("{e}")) 144 | .expect("processing"); 145 | if result != file_in { 146 | std::fs::write("/tmp/tmp2.md", &result).unwrap(); 147 | } 148 | 149 | assert_eq!( 150 | result, file_in, 151 | "unexpected result, see `diff /tmp/tmp2.md spec.processed.md`" 152 | ); 153 | } 154 | 155 | #[test] 156 | fn test_whole_file_cleaner() { 157 | let file_in = String::from_utf8(std::fs::read("spec.processed.md").unwrap()).unwrap(); 158 | let file_out = String::from_utf8(std::fs::read("spec.clear.md").unwrap()).unwrap(); 159 | let result = process_clean(&file_in) 160 | .inspect_err(|e| println!("{e}")) 161 | .expect("processing"); 162 | 163 | if result != file_out { 164 | std::fs::write("/tmp/tmp3.md", &result).unwrap(); 165 | } 166 | 167 | assert_eq!( 168 | result, file_out, 169 | "unexpected result, see `diff /tmp/tmp3.md spec.clear.md`" 170 | ); 171 | } 172 | } 173 | -------------------------------------------------------------------------------- /default.nix: -------------------------------------------------------------------------------- 1 | # Compatibility function to allow flakes to be used by 2 | # non-flake-enabled Nix versions. Given a source tree containing a 3 | # 'flake.nix' and 'flake.lock' file, it fetches the flake inputs and 4 | # calls the flake's 'outputs' function. It then returns an attrset 5 | # containing 'defaultNix' (to be used in 'default.nix'), 'shellNix' 6 | # (to be used in 'shell.nix'). 7 | 8 | { src, system ? builtins.currentSystem or "unknown-system" }: 9 | 10 | let 11 | 12 | lockFilePath = src + "/flake.lock"; 13 | 14 | lockFile = builtins.fromJSON (builtins.readFile lockFilePath); 15 | 16 | fetchTree = 17 | info: 18 | if info.type == "github" then 19 | { 20 | outPath = 21 | fetchTarball 22 | ({ url = "https://api.${info.host or "github.com"}/repos/${info.owner}/${info.repo}/tarball/${info.rev}"; } 23 | // (if info ? narHash then { sha256 = info.narHash; } else { }) 24 | ); 25 | rev = info.rev; 26 | shortRev = builtins.substring 0 7 info.rev; 27 | lastModified = info.lastModified; 28 | lastModifiedDate = formatSecondsSinceEpoch info.lastModified; 29 | narHash = info.narHash; 30 | } 31 | else if info.type == "git" then 32 | { 33 | outPath = 34 | builtins.fetchGit 35 | ({ url = info.url; } 36 | // (if info ? rev then { inherit (info) rev; } else { }) 37 | // (if info ? ref then { inherit (info) ref; } else { }) 38 | // (if info ? submodules then { inherit (info) submodules; } else { }) 39 | ); 40 | lastModified = info.lastModified; 41 | lastModifiedDate = formatSecondsSinceEpoch info.lastModified; 42 | narHash = info.narHash; 43 | } // (if info ? rev then { 44 | rev = info.rev; 45 | shortRev = builtins.substring 0 7 info.rev; 46 | } else { }) 47 | else if info.type == "path" then 48 | { 49 | outPath = builtins.path { 50 | path = 51 | if builtins.substring 0 1 info.path != "/" 52 | then src + ("/" + info.path) 53 | else info.path; 54 | }; 55 | narHash = info.narHash; 56 | } 57 | else if info.type == "tarball" then 58 | { 59 | outPath = 60 | fetchTarball 61 | ({ inherit (info) url; } 62 | // (if info ? narHash then { sha256 = info.narHash; } else { }) 63 | ); 64 | } 65 | else if info.type == "gitlab" then 66 | { 67 | inherit (info) rev narHash lastModified; 68 | outPath = 69 | fetchTarball 70 | ({ url = "https://${info.host or "gitlab.com"}/api/v4/projects/${info.owner}%2F${info.repo}/repository/archive.tar.gz?sha=${info.rev}"; } 71 | // (if info ? narHash then { sha256 = info.narHash; } else { }) 72 | ); 73 | shortRev = builtins.substring 0 7 info.rev; 74 | } 75 | else 76 | # FIXME: add Mercurial, tarball inputs. 77 | throw "flake input has unsupported input type '${info.type}'"; 78 | 79 | callLocklessFlake = flakeSrc: 80 | let 81 | flake = import (flakeSrc + "/flake.nix"); 82 | outputs = flakeSrc // (flake.outputs ({ self = outputs; })); 83 | in 84 | outputs; 85 | 86 | rootSrc = 87 | let 88 | # Try to clean the source tree by using fetchGit, if this source 89 | # tree is a valid git repository. 90 | tryFetchGit = src: 91 | if isGit && !isShallow 92 | then 93 | let res = builtins.fetchGit src; 94 | in if res.rev == "0000000000000000000000000000000000000000" then removeAttrs res [ "rev" "shortRev" ] else res 95 | else { outPath = src; }; 96 | # NB git worktrees have a file for .git, so we don't check the type of .git 97 | isGit = builtins.pathExists (src + "/.git"); 98 | isShallow = builtins.pathExists (src + "/.git/shallow"); 99 | 100 | in 101 | { lastModified = 0; lastModifiedDate = formatSecondsSinceEpoch 0; } 102 | // (if src ? outPath then src else tryFetchGit src); 103 | 104 | # Format number of seconds in the Unix epoch as %Y%m%d%H%M%S. 105 | formatSecondsSinceEpoch = t: 106 | let 107 | rem = x: y: x - x / y * y; 108 | days = t / 86400; 109 | secondsInDay = rem t 86400; 110 | hours = secondsInDay / 3600; 111 | minutes = (rem secondsInDay 3600) / 60; 112 | seconds = rem t 60; 113 | 114 | # Courtesy of https://stackoverflow.com/a/32158604. 115 | z = days + 719468; 116 | era = (if z >= 0 then z else z - 146096) / 146097; 117 | doe = z - era * 146097; 118 | yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365; 119 | y = yoe + era * 400; 120 | doy = doe - (365 * yoe + yoe / 4 - yoe / 100); 121 | mp = (5 * doy + 2) / 153; 122 | d = doy - (153 * mp + 2) / 5 + 1; 123 | m = mp + (if mp < 10 then 3 else -9); 124 | y' = y + (if m <= 2 then 1 else 0); 125 | 126 | pad = s: if builtins.stringLength s < 2 then "0" + s else s; 127 | in 128 | "${toString y'}${pad (toString m)}${pad (toString d)}${pad (toString hours)}${pad (toString minutes)}${pad (toString seconds)}"; 129 | 130 | allNodes = 131 | builtins.mapAttrs 132 | (key: node: 133 | let 134 | sourceInfo = 135 | if key == lockFile.root 136 | then rootSrc 137 | else fetchTree (node.info or { } // removeAttrs node.locked [ "dir" ]); 138 | 139 | subdir = if key == lockFile.root then "" else node.locked.dir or ""; 140 | 141 | flake = import (sourceInfo + (if subdir != "" then "/" else "") + subdir + "/flake.nix"); 142 | 143 | inputs = builtins.mapAttrs 144 | (_inputName: inputSpec: allNodes.${resolveInput inputSpec}) 145 | (node.inputs or { }); 146 | 147 | # Resolve a input spec into a node name. An input spec is 148 | # either a node name, or a 'follows' path from the root 149 | # node. 150 | resolveInput = inputSpec: 151 | if builtins.isList inputSpec 152 | then getInputByPath lockFile.root inputSpec 153 | else inputSpec; 154 | 155 | # Follow an input path (e.g. ["dwarffs" "nixpkgs"]) from the 156 | # root node, returning the final node. 157 | getInputByPath = nodeName: path: 158 | if path == [ ] 159 | then nodeName 160 | else 161 | getInputByPath 162 | # Since this could be a 'follows' input, call resolveInput. 163 | (resolveInput lockFile.nodes.${nodeName}.inputs.${builtins.head path}) 164 | (builtins.tail path); 165 | 166 | outputs = flake.outputs (inputs // { self = result; }); 167 | 168 | result = outputs // sourceInfo // { inherit inputs; inherit outputs; inherit sourceInfo; _type = "flake"; }; 169 | 170 | in 171 | if node.flake or true then 172 | assert builtins.isFunction flake.outputs; 173 | result 174 | else 175 | sourceInfo 176 | ) 177 | lockFile.nodes; 178 | 179 | result = 180 | if !(builtins.pathExists lockFilePath) 181 | then callLocklessFlake rootSrc 182 | else if lockFile.version >= 5 && lockFile.version <= 7 183 | then allNodes.${lockFile.root} 184 | else throw "lock file '${lockFilePath}' has unsupported version ${toString lockFile.version}"; 185 | 186 | in 187 | rec { 188 | defaultNix = 189 | (builtins.removeAttrs result [ "__functor" ]) 190 | // (if result ? defaultPackage.${system} then { default = result.defaultPackage.${system}; } else { }) 191 | // (if result ? packages.${system}.default then { default = result.packages.${system}.default; } else { }); 192 | 193 | shellNix = 194 | defaultNix 195 | // (if result ? devShell.${system} then { default = result.devShell.${system}; } else { }) 196 | // (if result ? devShells.${system}.default then { default = result.devShells.${system}.default; } else { }); 197 | } 198 | -------------------------------------------------------------------------------- /src/gen_test_md.rs: -------------------------------------------------------------------------------- 1 | //! Helper script to generate `spec.clear.md` 2 | 3 | const FILE_HEADER: &str = "# `mdsh` spec. 4 | 5 | Each H4 section is converted into a test case by `build.rs` script. Each section 6 | in `spec.clear.md` must correspond to the same section in `spec.processed.md`. 7 | `spec.processed.md` is a version of this file after one `mdsh` pass. 8 | `spec.processed.md` must be idempotent, i.e. any next passes result in the same content. 9 | `mdsh --clean` pass on `spec.processed.md` must result in `spec.clear.md`."; 10 | 11 | fn main() { 12 | println!("{FILE_HEADER}\n\n"); 13 | for (out_cmd, out_cmd_title) in [ 14 | (Markdown, "Producing raw markdown"), 15 | (CodeBlock, "Producing code blocks"), 16 | (EnvVars, "Sourcing environment variables"), 17 | ] 18 | .iter() 19 | { 20 | println!("## {out_cmd_title}\n"); 21 | for (in_cmd, in_cmd_title) in [ 22 | (Execute, "Executing shell commands"), 23 | (Read, "Reading files contents"), 24 | (Raw, "Using inlined values"), 25 | ] 26 | .iter() 27 | { 28 | println!("### {in_cmd_title}\n"); 29 | let container_types = [Oneline, Multiline(true), Multiline(false)]; 30 | for cnt in container_types 31 | .clone() 32 | .iter() 33 | .cloned() 34 | .map(Code) 35 | .chain(container_types.map(Comment)) 36 | .chain([Link]) 37 | { 38 | // Excluding few useless cases 39 | if in_cmd == &Raw && out_cmd == &Markdown 40 | || (cnt.kind() == &Multiline(true) && matches!(in_cmd, Read | Raw)) 41 | || cnt == Link && (out_cmd, in_cmd) == (&EnvVars, &Raw) 42 | { 43 | continue; 44 | } 45 | 46 | println!("#### {}\n", test_case_name(&cnt, out_cmd, in_cmd)); 47 | println!("\n", (&cnt, out_cmd, in_cmd)); 48 | println!("{}\n", test_case(&cnt, out_cmd, in_cmd)); 49 | 50 | if out_cmd == &EnvVars { 51 | println!("``> $ echo \"\\`\\$foo\\` is $foo\"``\n"); 52 | } 53 | } 54 | } 55 | } 56 | println!("The end!"); 57 | } 58 | 59 | #[derive(Debug, Eq, PartialEq)] 60 | enum Container { 61 | Code(ContainerType), 62 | Comment(ContainerType), 63 | Link, 64 | } 65 | 66 | #[derive(Clone, Debug, Eq, PartialEq)] 67 | enum ContainerType { 68 | Oneline, 69 | Multiline(bool), 70 | } 71 | 72 | #[derive(Debug, Eq, PartialEq)] 73 | enum InCmd { 74 | Execute, 75 | Read, 76 | Raw, 77 | } 78 | 79 | #[derive(Debug, Eq, PartialEq)] 80 | enum OutCmd { 81 | Markdown, 82 | CodeBlock, 83 | EnvVars, 84 | } 85 | 86 | use Container::*; 87 | use ContainerType::*; 88 | use InCmd::*; 89 | use OutCmd::*; 90 | 91 | impl Container { 92 | fn kind(&self) -> &ContainerType { 93 | match self { 94 | Code(k) => k, 95 | Comment(k) => k, 96 | Link => &Oneline, 97 | } 98 | } 99 | } 100 | 101 | fn test_case_name(cnt: &Container, out_cmd: &OutCmd, in_cmd: &InCmd) -> String { 102 | let doing = in_cmd_name(in_cmd); 103 | let resulting = out_cmd_name(out_cmd); 104 | match cnt { 105 | Code(Oneline) => format!("{doing} in inline code and {resulting}"), 106 | Code(Multiline(true)) => format!("{doing} in code blocks with data line and {resulting}"), 107 | Code(Multiline(false)) => format!("{doing} in code blocks and {resulting}"), 108 | 109 | Comment(Oneline) => format!("{doing} in one-line comments and {resulting}"), 110 | Comment(Multiline(true)) => { 111 | format!("{doing} in multiline comments with data line and {resulting}") 112 | } 113 | Comment(Multiline(false)) => format!("{doing} in multiline comments and {resulting}"), 114 | Link => format!("{doing} in markdown link and {resulting}"), 115 | } 116 | } 117 | 118 | const fn in_cmd_name(in_cmd: &InCmd) -> &'static str { 119 | match in_cmd { 120 | Execute => "Executing command", 121 | Read => "Reading file", 122 | Raw => "Using inlined data", 123 | } 124 | } 125 | 126 | const fn out_cmd_name(out_cmd: &OutCmd) -> &'static str { 127 | match out_cmd { 128 | Markdown => "producing raw markdown", 129 | CodeBlock => "producing code block", 130 | EnvVars => "sourcing env variable(s)", 131 | } 132 | } 133 | 134 | fn test_case(cnt: &Container, out_cmd: &OutCmd, in_cmd: &InCmd) -> String { 135 | let cmd = command(out_cmd, in_cmd); 136 | let data_line = mk_data_line(cnt.kind(), out_cmd, in_cmd); 137 | let data = if cnt.kind() == &Multiline(true) { 138 | data(true, in_cmd, out_cmd) 139 | } else { 140 | data(false, in_cmd, out_cmd) 141 | }; 142 | match cnt { 143 | Code(Oneline) => format!("`{cmd} {data_line}`"), 144 | Code(Multiline(true)) => format!( 145 | "```{} {cmd} {data_line}\n{data}\n```", 146 | src_lang(out_cmd, in_cmd, true), 147 | ), 148 | Code(Multiline(false)) => { 149 | format!("```{} {cmd}\n{data}\n```", src_lang(out_cmd, in_cmd, false),) 150 | } 151 | 152 | Comment(Oneline) => format!(""), 153 | Comment(Multiline(true)) => format!("",), 154 | Comment(Multiline(false)) => format!(""), 155 | 156 | Link => format!("[{cmd} description]({})", link_file(out_cmd, in_cmd)), 157 | } 158 | } 159 | 160 | const fn link_file(out_cmd: &OutCmd, in_cmd: &InCmd) -> &'static str { 161 | match (out_cmd, in_cmd) { 162 | (Markdown, Execute) => "./samples/gen-md.sh", 163 | (CodeBlock, Execute) => "./samples/gen-yml.sh", 164 | (EnvVars, Execute) => "./samples/gen-env.sh", 165 | (_, _) => read_data_line(out_cmd), 166 | } 167 | } 168 | 169 | const fn data(data_line: bool, in_cmd: &InCmd, out_cmd: &OutCmd) -> &'static str { 170 | match (data_line, in_cmd, out_cmd) { 171 | (true, Execute, Markdown) => "I am *markdown*", 172 | (true, Execute, CodeBlock) => "foo: true", 173 | (true, Execute, EnvVars) => "foo=bar", 174 | (false, Execute, _) => exec_data_line(&Oneline, out_cmd), 175 | (_, Read, _) => read_data_line(out_cmd), 176 | (_, Raw, Markdown) => "I am *markdown*", 177 | (_, Raw, CodeBlock) => "foo: true", 178 | (_, Raw, EnvVars) => "foo=bar", 179 | } 180 | } 181 | 182 | const fn exec_data_line(cnt_type: &ContainerType, out_cmd: &OutCmd) -> &'static str { 183 | match (cnt_type, out_cmd) { 184 | (Multiline(true), Markdown) => "sed 's/.*/Hi, \\0/'", 185 | (Multiline(true), CodeBlock | EnvVars) => "sed 's/.*/\\0 # hmm/'", 186 | (Oneline, CodeBlock) => "echo 'foo: true'", 187 | (Oneline, Markdown) => "echo 'I am *markdown*'", 188 | (Oneline, EnvVars) => "echo 'foo=bar'", 189 | (Multiline(false), _) => "", 190 | } 191 | } 192 | 193 | const fn read_data_line(out_cmd: &OutCmd) -> &'static str { 194 | match out_cmd { 195 | Markdown => "./samples/example.md", 196 | CodeBlock => "./samples/example.yml", 197 | EnvVars => "./samples/example.env", 198 | } 199 | } 200 | 201 | const fn src_lang(out_cmd: &OutCmd, in_cmd: &InCmd, data_line: bool) -> &'static str { 202 | match (out_cmd, data_line, in_cmd) { 203 | (Markdown, true, Execute) => "md", 204 | (CodeBlock, true, Execute) => "yml", 205 | (EnvVars, true, Execute) => "env", 206 | (_, false, Execute) => "sh", 207 | (_, _, Read) => "filelist", 208 | (Markdown, _, Raw) => "md", 209 | (CodeBlock, _, Raw) => "yml", 210 | (EnvVars, _, Raw) => "env", 211 | } 212 | } 213 | 214 | fn command(out_cmd: &OutCmd, in_cmd: &InCmd) -> String { 215 | [mk_out_cmd(out_cmd), mk_in_cmd(in_cmd)] 216 | .join(" ") 217 | .trim() 218 | .into() 219 | } 220 | 221 | const fn mk_in_cmd(in_cmd: &InCmd) -> &'static str { 222 | match in_cmd { 223 | Execute => "$", 224 | Read => "<", 225 | Raw => "", 226 | } 227 | } 228 | 229 | fn mk_data_line(cnt_type: &ContainerType, out_cmd: &OutCmd, in_cmd: &InCmd) -> &'static str { 230 | match in_cmd { 231 | Execute => exec_data_line(cnt_type, out_cmd), 232 | Read => read_data_line(out_cmd), 233 | Raw => data(false, &Raw, out_cmd), 234 | } 235 | } 236 | 237 | const fn mk_out_cmd(x: &OutCmd) -> &'static str { 238 | match x { 239 | Markdown => ">", 240 | CodeBlock => "> yaml", 241 | EnvVars => "!", 242 | } 243 | } 244 | -------------------------------------------------------------------------------- /src/executor.rs: -------------------------------------------------------------------------------- 1 | use std::{ 2 | collections::BTreeMap as Map, 3 | ffi::OsStr, 4 | fs::File, 5 | io::{Cursor, Read, Write}, 6 | process::{self, Stdio}, 7 | }; 8 | 9 | use anyhow::{Context, Error, Result}; 10 | 11 | use crate::{MdPiece, BEGIN_MDSH, END_MDSH}; 12 | 13 | #[derive(Debug)] 14 | /// Actionable container: comment/code/link. 15 | pub struct Action<'a> { 16 | pub command: Command<'a>, 17 | pub data_line: Option<&'a str>, 18 | pub data: Option<&'a str>, 19 | } 20 | 21 | /// Command to execute: get data, act on data. 22 | #[derive(Debug)] 23 | pub struct Command<'a> { 24 | pub in_type: InType, 25 | pub out_type: OutType<'a>, 26 | } 27 | 28 | /// How to get data: command output, file content, or raw. 29 | #[derive(Debug)] 30 | pub enum InType { 31 | /// `$ cmd` executes `cmd` and uses data if available as stdin. 32 | /// `$` executes data. 33 | /// Use stdout as the result. 34 | Execute, 35 | /// `< fname` reads file. 36 | /// `<` reads list of files and concats them. 37 | /// Use file contents as the result 38 | Read, 39 | /// Use data as the result, only useful for setting env vars 40 | RawData, 41 | } 42 | 43 | /// What to do with the data 44 | #[derive(Debug)] 45 | pub enum OutType<'a> { 46 | /// `>` results in fence gated inlined markdown 47 | Markdown, 48 | /// `!` results are sourced as environment variables 49 | Environment, 50 | /// `> foo.yaml`, where lang name is `yaml`, results in code block 51 | CodeBlock(&'a str), 52 | } 53 | 54 | impl<'a, W: Write> crate::Processor<'a> for TheProcessor<'a, W> { 55 | fn process_piece(&mut self, piece: MdPiece<'a>) -> Result<()> { 56 | match piece { 57 | MdPiece::FencedBlock => (), 58 | MdPiece::Action((source, action)) => { 59 | self.out.write_all(source.as_bytes())?; 60 | self.process_action(action)?; 61 | } 62 | MdPiece::RawLine(raw_line) => { 63 | self.out.write_all(raw_line.as_bytes())?; 64 | } 65 | } 66 | Ok(()) 67 | } 68 | } 69 | 70 | #[derive(Debug, Default)] 71 | pub struct TheProcessor<'a, W> { 72 | variables: Map, 73 | workdir: &'a OsStr, 74 | pub out: W, 75 | } 76 | 77 | impl<'a, W: Write> TheProcessor<'a, W> { 78 | pub fn new(workdir: &'a OsStr, out: W) -> Self { 79 | Self { 80 | variables: Default::default(), 81 | workdir, 82 | out, 83 | } 84 | } 85 | 86 | /// Process parsed [`Action`] 87 | pub fn process_action(&mut self, action: Action<'a>) -> Result<()> { 88 | let mut r = self 89 | .get_data(action.command.in_type, action.data_line, action.data) 90 | .context("getting data")?; 91 | self.act_on_data(action.command.out_type, &mut r) 92 | } 93 | 94 | /// Execute or read to get the data 95 | fn get_data( 96 | &self, 97 | in_type: InType, 98 | data_line: Option<&'a str>, 99 | data: Option<&'a str>, 100 | ) -> Result> { 101 | match in_type { 102 | InType::RawData => Ok(match (data_line, data) { 103 | (Some(data_line), None) => { 104 | Box::new(Cursor::new(format!("{data_line}\n"))) as Box 105 | } 106 | (Some(data_line), Some(data)) => { 107 | Box::new(Cursor::new(format!("{data_line}\n")).chain(data.as_bytes())) 108 | } 109 | (None, data) => Box::new(data.unwrap_or("").as_bytes()), 110 | }), 111 | InType::Read => data_line 112 | .into_iter() 113 | .chain(data.map(str::lines).into_iter().flatten()) 114 | .try_fold(Box::new(std::io::empty()) as Box, |s, x| { 115 | eprintln!("< {x}"); 116 | Ok::, Error>(Box::new(s.chain(File::open(x)?))) 117 | }), 118 | InType::Execute => { 119 | if let Some(data) = data_line.and(data) { 120 | let mut lines: usize = 0; 121 | for line in data.lines() { 122 | eprintln!("$ {line}"); 123 | lines += 1; 124 | if lines > 4 { 125 | eprintln!("$ ..."); 126 | break; 127 | } 128 | } 129 | } else if let Some(data_line) = data_line { 130 | eprintln!("$ {data_line}"); 131 | } 132 | 133 | let oneliner = data_line.map(|command| format!("set -euo pipefail && {command}")); 134 | 135 | let mut cmd = process::Command::new("bash"); 136 | 137 | if let Some(command) = oneliner { 138 | cmd.args(["-c", &command]); 139 | } 140 | 141 | let mut child = cmd 142 | .envs(&self.variables) 143 | .stdin(data.map_or_else(Stdio::null, |_| Stdio::piped())) 144 | .stdin(Stdio::piped()) 145 | .stdout(Stdio::piped()) 146 | .stderr(Stdio::inherit()) 147 | .current_dir(self.workdir) 148 | .spawn()?; 149 | 150 | if let Some(data) = data { 151 | let mut stdin = child 152 | .stdin 153 | .take() 154 | .context("child process didn't provide stdin pipe")?; 155 | stdin 156 | .write_all(data.as_bytes()) 157 | .context("writing to command's stdin")?; 158 | stdin.flush()?; 159 | } 160 | Ok(Box::new(Child(child)) as Box) 161 | } 162 | } 163 | } 164 | 165 | /// Takes data and acts on it 166 | fn act_on_data(&mut self, out_type: OutType<'a>, data: &mut R) -> Result<()> { 167 | match out_type { 168 | OutType::Markdown => produce_fenced_block(data, &mut self.out), 169 | OutType::Environment => self.env_var_list(data), 170 | OutType::CodeBlock(lang_name) => produce_code_block(lang_name, data, &mut self.out), 171 | } 172 | .context("acting on data") 173 | } 174 | 175 | pub fn env_var_list(&mut self, data: &mut R) -> Result<()> { 176 | use std::borrow::Cow; 177 | 178 | use nom::Finish; 179 | 180 | use crate::parser::{env_var_line, fmt_nom_error}; 181 | 182 | let mut input = String::with_capacity(8192); 183 | data.read_to_string(&mut input)?; 184 | let input = input.as_str(); 185 | 186 | let mut iter = nom::combinator::iterator(input, env_var_line()); 187 | for (k, v) in iter.by_ref().flatten() { 188 | let val = shellexpand::env_with_context(v, |x| { 189 | self.variables 190 | .get(x) 191 | .map_or_else(|| std::env::var(x).map(Cow::from), |x| Ok(Cow::from(x))) 192 | .map(Some) 193 | }) 194 | .context("expanding shell variables")? 195 | .into(); 196 | 197 | eprintln!("! {k}='{val}'"); 198 | self.variables.insert(k.to_owned(), val); 199 | } 200 | // TODO: error msg with absolute line numbers 201 | iter.finish() 202 | .finish() 203 | .map_err(fmt_nom_error(input, "`!` env block"))?; 204 | Ok(()) 205 | } 206 | } 207 | 208 | fn produce_fenced_block(r: &mut R, w: &mut W) -> Result<()> { 209 | writeln!(w, "\n{BEGIN_MDSH}")?; 210 | std::io::copy(r, w)?; 211 | writeln!(w, "{END_MDSH}")?; 212 | Ok(()) 213 | } 214 | 215 | fn produce_code_block(lang: &str, r: &mut R, w: &mut W) -> Result<()> { 216 | produce_fenced_block( 217 | &mut format!("```{lang}\n") 218 | .as_bytes() 219 | .chain(r) 220 | .chain("```\n".as_bytes()), 221 | w, 222 | ) 223 | } 224 | 225 | /// Helper wrapper over [`std::process::Child`] that calls 226 | /// [`std::process::Child::wait`] when [`Read::read`] returns 0. 227 | struct Child(std::process::Child); 228 | 229 | impl Read for Child { 230 | fn read(&mut self, buf: &mut [u8]) -> std::io::Result { 231 | use std::io::Error; 232 | let n = self 233 | .0 234 | .stdout 235 | .as_mut() 236 | .ok_or_else(|| Error::other("Child process didn't provide stdout pipe"))? 237 | .read(buf)?; 238 | if n == 0 { 239 | let res = self.0.wait()?; 240 | if !res.success() { 241 | return Err(Error::other(format!("Child process terminated with {res}"))); 242 | } 243 | } 244 | Ok(n) 245 | } 246 | } 247 | -------------------------------------------------------------------------------- /Cargo.lock: -------------------------------------------------------------------------------- 1 | # This file is automatically @generated by Cargo. 2 | # It is not intended for manual editing. 3 | version = 4 4 | 5 | [[package]] 6 | name = "anstream" 7 | version = "0.6.18" 8 | source = "registry+https://github.com/rust-lang/crates.io-index" 9 | checksum = "8acc5369981196006228e28809f761875c0327210a891e941f4c683b3a99529b" 10 | dependencies = [ 11 | "anstyle", 12 | "anstyle-parse", 13 | "anstyle-query", 14 | "anstyle-wincon", 15 | "colorchoice", 16 | "is_terminal_polyfill", 17 | "utf8parse", 18 | ] 19 | 20 | [[package]] 21 | name = "anstyle" 22 | version = "1.0.10" 23 | source = "registry+https://github.com/rust-lang/crates.io-index" 24 | checksum = "55cc3b69f167a1ef2e161439aa98aed94e6028e5f9a59be9a6ffb47aef1651f9" 25 | 26 | [[package]] 27 | name = "anstyle-parse" 28 | version = "0.2.6" 29 | source = "registry+https://github.com/rust-lang/crates.io-index" 30 | checksum = "3b2d16507662817a6a20a9ea92df6652ee4f94f914589377d69f3b21bc5798a9" 31 | dependencies = [ 32 | "utf8parse", 33 | ] 34 | 35 | [[package]] 36 | name = "anstyle-query" 37 | version = "1.1.2" 38 | source = "registry+https://github.com/rust-lang/crates.io-index" 39 | checksum = "79947af37f4177cfead1110013d678905c37501914fba0efea834c3fe9a8d60c" 40 | dependencies = [ 41 | "windows-sys", 42 | ] 43 | 44 | [[package]] 45 | name = "anstyle-wincon" 46 | version = "3.0.7" 47 | source = "registry+https://github.com/rust-lang/crates.io-index" 48 | checksum = "ca3534e77181a9cc07539ad51f2141fe32f6c3ffd4df76db8ad92346b003ae4e" 49 | dependencies = [ 50 | "anstyle", 51 | "once_cell", 52 | "windows-sys", 53 | ] 54 | 55 | [[package]] 56 | name = "anyhow" 57 | version = "1.0.98" 58 | source = "registry+https://github.com/rust-lang/crates.io-index" 59 | checksum = "e16d2d3311acee920a9eb8d33b8cbc1787ce4a264e85f964c2404b969bdcd487" 60 | 61 | [[package]] 62 | name = "clap" 63 | version = "4.5.32" 64 | source = "registry+https://github.com/rust-lang/crates.io-index" 65 | checksum = "6088f3ae8c3608d19260cd7445411865a485688711b78b5be70d78cd96136f83" 66 | dependencies = [ 67 | "clap_builder", 68 | "clap_derive", 69 | ] 70 | 71 | [[package]] 72 | name = "clap_builder" 73 | version = "4.5.32" 74 | source = "registry+https://github.com/rust-lang/crates.io-index" 75 | checksum = "22a7ef7f676155edfb82daa97f99441f3ebf4a58d5e32f295a56259f1b6facc8" 76 | dependencies = [ 77 | "anstream", 78 | "anstyle", 79 | "clap_lex", 80 | "strsim", 81 | ] 82 | 83 | [[package]] 84 | name = "clap_derive" 85 | version = "4.5.32" 86 | source = "registry+https://github.com/rust-lang/crates.io-index" 87 | checksum = "09176aae279615badda0765c0c0b3f6ed53f4709118af73cf4655d85d1530cd7" 88 | dependencies = [ 89 | "heck", 90 | "proc-macro2", 91 | "quote", 92 | "syn", 93 | ] 94 | 95 | [[package]] 96 | name = "clap_lex" 97 | version = "0.7.4" 98 | source = "registry+https://github.com/rust-lang/crates.io-index" 99 | checksum = "f46ad14479a25103f283c0f10005961cf086d8dc42205bb44c46ac563475dca6" 100 | 101 | [[package]] 102 | name = "colorchoice" 103 | version = "1.0.3" 104 | source = "registry+https://github.com/rust-lang/crates.io-index" 105 | checksum = "5b63caa9aa9397e2d9480a9b13673856c78d8ac123288526c37d7839f2a86990" 106 | 107 | [[package]] 108 | name = "dedent" 109 | version = "0.1.1" 110 | source = "registry+https://github.com/rust-lang/crates.io-index" 111 | checksum = "a8a3dee4e932355439992a45dc631b0979abf9c677958674bd94298bf9002870" 112 | dependencies = [ 113 | "proc-macro2", 114 | "quote", 115 | "syn", 116 | ] 117 | 118 | [[package]] 119 | name = "heck" 120 | version = "0.5.0" 121 | source = "registry+https://github.com/rust-lang/crates.io-index" 122 | checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" 123 | 124 | [[package]] 125 | name = "is_terminal_polyfill" 126 | version = "1.70.1" 127 | source = "registry+https://github.com/rust-lang/crates.io-index" 128 | checksum = "7943c866cc5cd64cbc25b2e01621d07fa8eb2a1a23160ee81ce38704e97b8ecf" 129 | 130 | [[package]] 131 | name = "mdsh" 132 | version = "0.9.2" 133 | dependencies = [ 134 | "anyhow", 135 | "clap", 136 | "dedent", 137 | "nom", 138 | "nom-language", 139 | "shellexpand", 140 | ] 141 | 142 | [[package]] 143 | name = "memchr" 144 | version = "2.7.4" 145 | source = "registry+https://github.com/rust-lang/crates.io-index" 146 | checksum = "78ca9ab1a0babb1e7d5695e3530886289c18cf2f87ec19a575a0abdce112e3a3" 147 | 148 | [[package]] 149 | name = "nom" 150 | version = "8.0.0" 151 | source = "registry+https://github.com/rust-lang/crates.io-index" 152 | checksum = "df9761775871bdef83bee530e60050f7e54b1105350d6884eb0fb4f46c2f9405" 153 | dependencies = [ 154 | "memchr", 155 | ] 156 | 157 | [[package]] 158 | name = "nom-language" 159 | version = "0.1.0" 160 | source = "registry+https://github.com/rust-lang/crates.io-index" 161 | checksum = "2de2bc5b451bfedaef92c90b8939a8fff5770bdcc1fafd6239d086aab8fa6b29" 162 | dependencies = [ 163 | "nom", 164 | ] 165 | 166 | [[package]] 167 | name = "once_cell" 168 | version = "1.20.2" 169 | source = "registry+https://github.com/rust-lang/crates.io-index" 170 | checksum = "1261fe7e33c73b354eab43b1273a57c8f967d0391e80353e51f764ac02cf6775" 171 | 172 | [[package]] 173 | name = "proc-macro2" 174 | version = "1.0.95" 175 | source = "registry+https://github.com/rust-lang/crates.io-index" 176 | checksum = "02b3e5e68a3a1a02aad3ec490a98007cbc13c37cbe84a3cd7b8e406d76e7f778" 177 | dependencies = [ 178 | "unicode-ident", 179 | ] 180 | 181 | [[package]] 182 | name = "quote" 183 | version = "1.0.40" 184 | source = "registry+https://github.com/rust-lang/crates.io-index" 185 | checksum = "1885c039570dc00dcb4ff087a89e185fd56bae234ddc7f056a945bf36467248d" 186 | dependencies = [ 187 | "proc-macro2", 188 | ] 189 | 190 | [[package]] 191 | name = "shellexpand" 192 | version = "3.1.1" 193 | source = "registry+https://github.com/rust-lang/crates.io-index" 194 | checksum = "8b1fdf65dd6331831494dd616b30351c38e96e45921a27745cf98490458b90bb" 195 | 196 | [[package]] 197 | name = "strsim" 198 | version = "0.11.1" 199 | source = "registry+https://github.com/rust-lang/crates.io-index" 200 | checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f" 201 | 202 | [[package]] 203 | name = "syn" 204 | version = "2.0.87" 205 | source = "registry+https://github.com/rust-lang/crates.io-index" 206 | checksum = "25aa4ce346d03a6dcd68dd8b4010bcb74e54e62c90c573f394c46eae99aba32d" 207 | dependencies = [ 208 | "proc-macro2", 209 | "quote", 210 | "unicode-ident", 211 | ] 212 | 213 | [[package]] 214 | name = "unicode-ident" 215 | version = "1.0.12" 216 | source = "registry+https://github.com/rust-lang/crates.io-index" 217 | checksum = "3354b9ac3fae1ff6755cb6db53683adb661634f67557942dea4facebec0fee4b" 218 | 219 | [[package]] 220 | name = "utf8parse" 221 | version = "0.2.2" 222 | source = "registry+https://github.com/rust-lang/crates.io-index" 223 | checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821" 224 | 225 | [[package]] 226 | name = "windows-sys" 227 | version = "0.59.0" 228 | source = "registry+https://github.com/rust-lang/crates.io-index" 229 | checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b" 230 | dependencies = [ 231 | "windows-targets", 232 | ] 233 | 234 | [[package]] 235 | name = "windows-targets" 236 | version = "0.52.6" 237 | source = "registry+https://github.com/rust-lang/crates.io-index" 238 | checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973" 239 | dependencies = [ 240 | "windows_aarch64_gnullvm", 241 | "windows_aarch64_msvc", 242 | "windows_i686_gnu", 243 | "windows_i686_gnullvm", 244 | "windows_i686_msvc", 245 | "windows_x86_64_gnu", 246 | "windows_x86_64_gnullvm", 247 | "windows_x86_64_msvc", 248 | ] 249 | 250 | [[package]] 251 | name = "windows_aarch64_gnullvm" 252 | version = "0.52.6" 253 | source = "registry+https://github.com/rust-lang/crates.io-index" 254 | checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3" 255 | 256 | [[package]] 257 | name = "windows_aarch64_msvc" 258 | version = "0.52.6" 259 | source = "registry+https://github.com/rust-lang/crates.io-index" 260 | checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469" 261 | 262 | [[package]] 263 | name = "windows_i686_gnu" 264 | version = "0.52.6" 265 | source = "registry+https://github.com/rust-lang/crates.io-index" 266 | checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b" 267 | 268 | [[package]] 269 | name = "windows_i686_gnullvm" 270 | version = "0.52.6" 271 | source = "registry+https://github.com/rust-lang/crates.io-index" 272 | checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66" 273 | 274 | [[package]] 275 | name = "windows_i686_msvc" 276 | version = "0.52.6" 277 | source = "registry+https://github.com/rust-lang/crates.io-index" 278 | checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66" 279 | 280 | [[package]] 281 | name = "windows_x86_64_gnu" 282 | version = "0.52.6" 283 | source = "registry+https://github.com/rust-lang/crates.io-index" 284 | checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78" 285 | 286 | [[package]] 287 | name = "windows_x86_64_gnullvm" 288 | version = "0.52.6" 289 | source = "registry+https://github.com/rust-lang/crates.io-index" 290 | checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d" 291 | 292 | [[package]] 293 | name = "windows_x86_64_msvc" 294 | version = "0.52.6" 295 | source = "registry+https://github.com/rust-lang/crates.io-index" 296 | checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec" 297 | -------------------------------------------------------------------------------- /src/parser.rs: -------------------------------------------------------------------------------- 1 | use nom::{ 2 | branch::alt, 3 | bytes::complete::{escaped, tag, take_until, take_until1, take_while, take_while_m_n}, 4 | character::complete::{ 5 | alphanumeric1, anychar, char, multispace0, multispace1, newline, none_of, one_of, space0, 6 | }, 7 | combinator::{consumed, cut, eof, fail, not, opt, peek, recognize, rest, success}, 8 | error::context, 9 | multi::{many0_count, many1_count}, 10 | sequence::{delimited, preceded, terminated}, 11 | Parser as _, 12 | }; 13 | use nom_language::error::VerboseError; 14 | 15 | use crate::{ 16 | executor::{Action, Command, InType, OutType}, 17 | nom_ext::FnParser, 18 | MdPiece, BEGIN_MDSH, END_MDSH, 19 | }; 20 | 21 | /// Trait alias, sort of like 22 | /// ```future_rust 23 | /// type Parser<'a, T> = nom::Parser< 24 | /// 'a, 25 | /// &'a str, 26 | /// Output = T, 27 | /// Error = VerboseError<&'a str> 28 | /// >; 29 | /// ``` 30 | pub trait Parser<'a, T>: nom::Parser<&'a str, Output = T, Error = VerboseError<&'a str>> {} 31 | 32 | impl<'a, T, X: nom::Parser<&'a str, Output = T, Error = VerboseError<&'a str>>> Parser<'a, T> 33 | for X 34 | { 35 | } 36 | 37 | // pub type IRes = nom::IResult>; 38 | 39 | pub fn markdown_piece<'a>() -> impl Parser<'a, MdPiece<'a>> { 40 | alt(( 41 | FencedBlockParser.map(|_| MdPiece::FencedBlock), 42 | action_with_source().map(MdPiece::Action), 43 | preceded(tag(BEGIN_MDSH), fail()), 44 | comment().map(MdPiece::RawLine), 45 | non_actionable_code_block().map(MdPiece::RawLine), 46 | recognize(context("raw line", (take_until("\n"), newline))).map(MdPiece::RawLine), 47 | )) 48 | } 49 | 50 | pub type ActionWithSource<'a> = (&'a str, Action<'a>); 51 | 52 | fn action_with_source<'a>() -> impl Parser<'a, ActionWithSource<'a>> { 53 | consumed(alt(( 54 | actionable_code_block(), 55 | inline_code(), 56 | link(), 57 | actionable_comment(), 58 | ))) 59 | } 60 | 61 | /// Need this to avoid "recursive opaque type" error. 62 | /// Recursive definition to allow included markdown code 63 | /// to be also processable by mdsh 64 | struct FencedBlockParser; 65 | 66 | impl<'a> nom::Parser<&'a str> for FencedBlockParser { 67 | type Output = (); 68 | type Error = VerboseError<&'a str>; 69 | 70 | fn process( 71 | &mut self, 72 | input: &'a str, 73 | ) -> nom::PResult { 74 | context( 75 | "fenced block", 76 | delimited( 77 | (tag(BEGIN_MDSH), newline), 78 | recognize( 79 | // markdown_piece(), // TODO 80 | many0_count(not(tag(BEGIN_MDSH).or(tag(END_MDSH))).and(anychar)) 81 | .and(alt((peek(tag(END_MDSH)), recognize(Self)))), 82 | ), 83 | cut(tag(END_MDSH) 84 | .and(space0) 85 | .and(recognize(newline).or(eof)) 86 | .and(multispace0)), 87 | ), 88 | ) 89 | .map(|_| ()) 90 | .process::(input) 91 | } 92 | } 93 | 94 | /// Link container: 95 | /// ```md 96 | /// [> yaml < yaml example](./sample.yaml)` 97 | /// ``` 98 | fn link<'a>() -> impl Parser<'a, Action<'a>> { 99 | context( 100 | "link", 101 | ( 102 | char('['), 103 | command(), 104 | not(char('[')), 105 | cut((take_until("]"), tag("]("))), 106 | cut(filepath()), 107 | cut((char(')'), newline)), 108 | ), 109 | ) 110 | .map(|(_, command, _, _, filepath, _)| Action { 111 | command, 112 | data_line: Some(filepath), 113 | data: None, 114 | }) 115 | } 116 | 117 | fn out_type<'a>() -> impl Parser<'a, OutType<'a>> { 118 | context( 119 | "output type", 120 | alt(( 121 | (char('>'), space0, filepath()).map(|x| OutType::CodeBlock(x.2)), 122 | (char('>')).map(|_| OutType::Markdown), 123 | (char('!')).map(|_| OutType::Environment), 124 | )), 125 | ) 126 | } 127 | 128 | fn filepath<'a>() -> impl Parser<'a, &'a str> { 129 | context( 130 | "filepath", 131 | recognize(many1_count(alt(( 132 | recognize(alphanumeric1), 133 | recognize(one_of("/._-")), 134 | )))), 135 | ) 136 | } 137 | 138 | fn in_type<'a>() -> impl Parser<'a, InType> { 139 | context( 140 | "input type", 141 | alt(( 142 | char('$').map(|_| InType::Execute), 143 | char('<').map(|_| InType::Read), 144 | success(()).map(|_| InType::RawData), 145 | )), 146 | ) 147 | } 148 | 149 | fn command<'a>() -> impl Parser<'a, Command<'a>> { 150 | context( 151 | "mdsh command", 152 | (out_type(), space0, in_type()).map(|(out_type, _, in_type)| Command { in_type, out_type }), 153 | ) 154 | } 155 | 156 | fn comment<'a>() -> impl Parser<'a, &'a str> { 157 | recognize(context( 158 | "comment", 159 | (tag("")), tag("-->")), 160 | )) 161 | } 162 | 163 | fn actionable_comment<'a>() -> impl Parser<'a, Action<'a>> { 164 | context( 165 | "comment", 166 | delimited( 167 | tag(""), 169 | tag("-->").and(space0).and(newline), 170 | ) 171 | .and_then( 172 | ( 173 | space0, 174 | command(), 175 | space0, 176 | opt( 177 | recognize(many1_count(not(tag("-->").or(tag("\n"))).and(anychar))) 178 | .map(|s: &str| s.trim_end()), 179 | ), 180 | opt(newline), 181 | rest, 182 | ) 183 | .map(|(_, command, _, data_line, _, data)| Action { 184 | command, 185 | data_line, 186 | data: Some(data), 187 | }), 188 | ), 189 | ) 190 | } 191 | 192 | /// Inline code container: 193 | /// ```md 194 | /// `> yml $ echo 'foo: bar'` 195 | /// ``` 196 | fn inline_code<'a>() -> impl Parser<'a, Action<'a>> { 197 | context( 198 | "inline code", 199 | recognize(take_while_m_n(1, 2, |x| x == '`').and(not(char('`')))) 200 | .flat_map(|q1| terminated(take_until1(q1), tag(q1).and(newline))) 201 | .and_then((command(), space0, rest)) 202 | .map(|(command, _, rest)| Action { 203 | command, 204 | data_line: Some(rest), 205 | data: None, 206 | }), 207 | ) 208 | } 209 | 210 | fn non_actionable_code_block<'a>() -> impl Parser<'a, &'a str> { 211 | fn meta_line<'a>() -> impl Parser<'a, ()> { 212 | take_until("\n").and(newline).map(|_| ()) 213 | } 214 | recognize(code_block(FnParser::new(meta_line))) 215 | } 216 | 217 | fn actionable_code_block<'a>() -> impl Parser<'a, Action<'a>> { 218 | fn meta_line<'a>() -> impl Parser<'a, (Command<'a>, Option<&'a str>)> { 219 | ( 220 | opt(filepath()).and(space0), 221 | command(), 222 | space0, 223 | opt(take_until1("\n")), 224 | newline, 225 | ) 226 | .map(|(_srclang, command, _, data_line, _)| (command, data_line)) 227 | } 228 | context( 229 | "code block with mdsh command", 230 | code_block(FnParser::new(meta_line)), 231 | ) 232 | .map(|((command, data_line), data)| Action { 233 | command, 234 | data_line, 235 | data: Some(data), 236 | }) 237 | } 238 | 239 | fn code_block<'a, X>( 240 | meta_line: FnParser + 'a>, 241 | ) -> impl Parser<'a, (X, &'a str)> { 242 | let fence = alt(( 243 | (tag("```"), take_while(|x| x == '`')), 244 | (tag("~~~"), take_while(|x| x == '~')), 245 | )); 246 | context( 247 | "code block", 248 | recognize((space0, fence)).flat_map(move |q| { 249 | ( 250 | meta_line.clone(), 251 | cut(alt(( 252 | peek(tag(q)).map(|_| "\n"), // covers the edge case with empty code block 253 | recognize(many0_count(not(newline.and(tag(q))).and(anychar)).and(newline)), 254 | ))), 255 | cut(tag(q).and(newline)), 256 | ) 257 | }), 258 | ) 259 | .map(|(meta_line, data, _)| (meta_line, data)) 260 | } 261 | 262 | pub fn env_var_line<'a>() -> impl Parser<'a, Option<(&'a str, &'a str)>> { 263 | let kv_definition = ( 264 | recognize(many1_count(alphanumeric1.or(recognize(char('_'))))), 265 | cut(char('=')), 266 | cut(alt(( 267 | delimited( 268 | char('"'), 269 | escaped(none_of("\n\"\\"), '\\', one_of("\n\"\\")), 270 | char('"'), 271 | ), 272 | delimited( 273 | char('\''), 274 | escaped(none_of("'\\"), '\\', one_of("'\\")), 275 | char('\''), 276 | ), 277 | take_until(" "), 278 | take_until("\n"), 279 | rest, 280 | ))), 281 | opt(newline), 282 | ) 283 | .map(|(k, _, v, _)| (k, v)); 284 | alt(( 285 | (char('#'), take_until("\n"), newline).map(|_| None), 286 | (multispace1).map(|_| None), 287 | kv_definition.map(Some), 288 | )) 289 | } 290 | 291 | pub fn fmt_nom_error<'a>( 292 | input: &'a str, 293 | src_name: &'a str, 294 | ) -> impl FnOnce(VerboseError<&'a str>) -> anyhow::Error { 295 | move |e| { 296 | anyhow::anyhow!( 297 | "Parsing error in {}:\n{}", 298 | src_name, 299 | nom_language::error::convert_error(input, e) 300 | ) 301 | } 302 | } 303 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # `$ mdsh` - a markdown shell pre-processor 2 | 3 | [![Build Status](https://github.com/zimbatm/mdsh/actions/workflows/ci.yaml/badge.svg)](https://github.com/zimbatm/mdsh/actions/workflows/ci.yaml?branch=master) [![crates.io](https://img.shields.io/crates/v/mdsh.svg)](https://crates.io/crates/mdsh) 4 | 5 | The mdsh project describes a Markdown language extension that can be used to 6 | automate some common tasks in README.md files. Quite often I find myself 7 | needing to embed a snippet of code or markdown from a different file. Or I 8 | want to show the output of a command. In both cases this can be done manually, 9 | but what all you had to do was run `mdsh` and have the file updated 10 | automatically? 11 | 12 | So the goal of this tool is first to extend the syntax of Markdown in a 13 | natural way. Something that you might type. And if the `mdsh` tool is run, the 14 | related blocks get updated in place. Most other tools would produce a new file 15 | but we really want a sort of idempotent operation here. 16 | 17 | In the end this gives a tool that is a bit akin to literate programming or 18 | jupyer notebooks but for shell commands. It adds a bit of verbosity to the 19 | file and in exchange it allows to automate the refresh of those outputs. 20 | 21 | See the source code of [./spec.clear.md](./spec.clear.md) and 22 | [./spec.processed.md](./spec.processed.md) for **everything** that `mdsh` can. 23 | 24 | ## Usage 25 | 26 | Run `mdsh --help` 27 | 28 | 29 | 30 | ``` 31 | Markdown shell pre-processor. Never let your READMEs and tutorials get out of sync again. 32 | 33 | Exits non-zero if a sub-command failed. 34 | 35 | Usage: mdsh [OPTIONS] 36 | 37 | Options: 38 | -i, --inputs 39 | Path to the markdown files. `-` for stdin 40 | 41 | [default: ./README.md] 42 | 43 | -o, --output 44 | Path to the output file, `-` for stdout [defaults to updating the input file in-place] 45 | 46 | -w, --work-dir 47 | Directory to execute the scripts under [defaults to the input file’s directory] 48 | 49 | --frozen 50 | Fail if the output is different from the input. Useful for CI. 51 | 52 | Using `--frozen`, you can guarantee that developers update documentation when they make a change. Just add `mdsh --frozen` as a check to your continuous integration setup. 53 | 54 | --clean 55 | Remove all generated blocks 56 | 57 | -h, --help 58 | Print help (see a summary with '-h') 59 | 60 | -V, --version 61 | Print version 62 | ``` 63 | 64 | ## `mdsh` command 65 | 66 | The mdsh "Command" consists of these parts: 67 | 68 | ``` 69 | [langname] [data_line] 70 | [data] 71 | ``` 72 | 73 | `in_cmd` defines how and where to source data, it can be one of three: 74 | - `<` — read file as is. The filepath is sourced from `data_line`, if `data` is available, it is read per line for filenames and each file is concatenated to previos one. 75 | - `$` — command execution. If the `data_line` is available, then it is executed as shell command. If the `data` is available it is passed to the command as via stdin (Closes https://github.com/zimbatm/mdsh/issues/57). If only `data` is available but not `data_line`, then the `data` is executed as shell script. 76 | - "empty command" aka "use data as is", concatenating `data_line` and `data`. In practice this is useful only for env variables setting 77 | 78 | `out_cmd` defines what to do with the data from `in_cmd`, it can be one of three: 79 | - `> lang` — produce code block with `lang` (similarly to current `as lang` statements). 80 | - `>` — produce raw markdown output fenced by comment-tags 81 | - `!` — expand data to shell variables 82 | 83 | with these 3 * 3 commands you get 9 combinations, for example: 84 | 85 | - `> < include.md` — read file and produce raw markdown 86 | - `> py < script.py` — read script.py and produce code block with language `py` 87 | - `> yml $ ./script.py foo $bar` — execute `script.py foo $bar` in shell and produce `yml` code block 88 | - `>$ ./gen-md.py` — execute `gen-md.py` and produce raw markdown 89 | - `! foo=$bar` — use `foo=$bar` as "raw data" and expand env variables that can be used in the next shell executions 90 | - `!< .env` — read `.env` and eval shell vars 91 | - `!$ ./gen-vars.py` — execute gen-vars and treat output as the list of shell variable assignments 92 | 93 | So it can do quite a lot of things and the underlying model is pretty simple, and even allows to do some useless things, like `> hello` — would produce an empty code block with `hello` language. 94 | 95 | ## Containers 96 | 97 | Commands can be put into containers, here's all of them: 98 | 99 | ### Inline code blocks 100 | 101 | Must start from new line and end with newline. `langname` is skipped, parsing starts right from `out_cmd`, `data` is absent. 102 | 103 | ```md 104 | `>$ echo hi` 105 | ``` 106 | 107 | ### Code blocks 108 | ```` 109 | ```[langname] [data_line] 110 | [data] 111 | ``` 112 | ```` 113 | 114 | Source environment variables: 115 | ````md 116 | ```env ! 117 | foo=$bar 118 | ``` 119 | ```` 120 | 121 | Execute script and produce yaml block (you can even put shebang at the top and use other than bash scripting languages. 122 | ````md 123 | ```sh > yaml $ 124 | echo 'foo: true' 125 | ``` 126 | ```` 127 | 128 | Run `data_line` as oneline command and pass code block to it via stdin, producing raw markdown. 129 | ````md 130 | ```> $ sed 's/.*/Hi, \0/' 131 | Bobby 132 | ``` 133 | ```` 134 | 135 | ### Oneline comments 136 | 137 | Similar to inline code blocks but hidden: 138 | 139 | ```md 140 | `` — includes LICENSE.md 141 | ``` 142 | 143 | ### Multiline comment blocks 144 | 145 | Behaves similarly to code blocks, but `langname` is not needed 146 | 147 | ````md 148 | 151 | ```` 152 | 153 | ### Links 154 | 155 | These slightly deviate from the rest of containers: 156 | 157 | ```md 158 | [ whatever here is ignored]() 159 | ``` 160 | 161 | ## Installation 162 | 163 | The best way to install `mdsh` is with the rust tool cargo. 164 | 165 | ```bash 166 | cargo install mdsh 167 | ``` 168 | 169 | If you are lucky enough to be a nix user: 170 | 171 | ```bash 172 | nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -iA mdsh 173 | ``` 174 | 175 | If you are a nix + flakes user: 176 | 177 | ```bash 178 | nix profile install github:zimbatm/mdsh 179 | ``` 180 | 181 | ## Running without installation 182 | 183 | If you are a nix + flakes user: 184 | 185 | ```bash 186 | nix run github:zimbatm/mdsh -- --help 187 | ``` 188 | 189 | ### Pre-commit hook 190 | 191 | This project can also be installed as a [pre-commit](https://pre-commit.com/) 192 | hook. 193 | 194 | Add to your project's `.pre-commit-config.yaml`: 195 | 196 | ```yaml 197 | - repo: https://github.com/zimbatm/mdsh.git 198 | rev: main 199 | hooks: 200 | - id: mdsh 201 | ``` 202 | 203 | Make sure to have rust available in your environment. 204 | 205 | Then run `pre-commit install-hooks` 206 | 207 | ## Known issues 208 | 209 | The tool currently lacks in precision as it doesn't parse the Markdown file, 210 | it just looks for the desired blocks by regexp. It means that in some cases it 211 | might misintepret some of the commands. Most existing Markdown parsers are 212 | used to generate HTML in the end and are thus not position-preserving. Eg: 213 | pulldown-cmark 214 | 215 | The block removal algorithm doesn't support output that contains triple 216 | backtick or ``. 217 | 218 | ## Related projects 219 | 220 | * is the closest to this project. It 221 | has some interesting Pandoc filters that capture code blocks into outputs. 222 | The transformation is not in-place like `mdsh`. 223 | * [Enola.dev's ExecMD](https://docs.enola.dev/use/execmd) is another similar tool. 224 | * [Literate Programming](https://en.wikipedia.org/wiki/Literate_programming) 225 | is the practice of interspesing executable code into documents. There are 226 | many language-specific implementations out there. `mdsh` is a bit like a 227 | bash literate programming language. 228 | * [Jupyter Notebooks](https://jupyter.org/) is a whole other universe of 229 | documentation and code. It's great but stores the notebooks as JSON files. A 230 | special viewer program is required to render them to HTML or text. 231 | 232 | ## User Feedback 233 | 234 | ### Issues 235 | 236 | If you have any problems with or questions about this project, please contact 237 | us through a [GitHub issue](https://github.com/zimbatm/mdsh/issues). 238 | 239 | ### Contributing 240 | 241 | You are invited to contribute new features, fixes or updates, large or small; 242 | we are always thrilled to receive pull requests, and do our best to process 243 | them as fast as we can. 244 | 245 | ## License 246 | 247 | [>< LICENSE](LICENSE) 248 | 249 | 250 | MIT License 251 | 252 | Copyright (c) 2019 zimbatm and contributors 253 | 254 | Permission is hereby granted, free of charge, to any person obtaining a copy 255 | of this software and associated documentation files (the "Software"), to deal 256 | in the Software without restriction, including without limitation the rights 257 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 258 | copies of the Software, and to permit persons to whom the Software is 259 | furnished to do so, subject to the following conditions: 260 | 261 | The above copyright notice and this permission notice shall be included in all 262 | copies or substantial portions of the Software. 263 | 264 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 265 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 266 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 267 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 268 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 269 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 270 | SOFTWARE. 271 | -------------------------------------------------------------------------------- /spec.clear.md: -------------------------------------------------------------------------------- 1 | # `mdsh` spec. 2 | 3 | Each H4 section is converted into a test case by `build.rs` script. Each section 4 | in `spec.clear.md` must correspond to the same section in `spec.processed.md`. 5 | `spec.processed.md` is a version of this file after one `mdsh` pass. 6 | `spec.processed.md` must be idempotent, i.e. any next passes result in the same content. 7 | `mdsh --clean` pass on `spec.processed.md` must result in `spec.clear.md`. 8 | 9 | 10 | 11 | 12 | - [Producing raw markdown](#producing-raw-markdown) 13 | - [Executing shell commands](#executing-shell-commands) 14 | - [Executing command in inline code and producing raw markdown](#executing-command-in-inline-code-and-producing-raw-markdown) 15 | - [Executing command in code blocks with data line and producing raw markdown](#executing-command-in-code-blocks-with-data-line-and-producing-raw-markdown) 16 | - [Executing command in code blocks and producing raw markdown](#executing-command-in-code-blocks-and-producing-raw-markdown) 17 | - [Executing command in one-line comments and producing raw markdown](#executing-command-in-one-line-comments-and-producing-raw-markdown) 18 | - [Executing command in multiline comments with data line and producing raw markdown](#executing-command-in-multiline-comments-with-data-line-and-producing-raw-markdown) 19 | - [Executing command in multiline comments and producing raw markdown](#executing-command-in-multiline-comments-and-producing-raw-markdown) 20 | - [Executing command in markdown link and producing raw markdown](#executing-command-in-markdown-link-and-producing-raw-markdown) 21 | - [Reading files contents](#reading-files-contents) 22 | - [Reading file in inline code and producing raw markdown](#reading-file-in-inline-code-and-producing-raw-markdown) 23 | - [Reading file in code blocks and producing raw markdown](#reading-file-in-code-blocks-and-producing-raw-markdown) 24 | - [Reading file in one-line comments and producing raw markdown](#reading-file-in-one-line-comments-and-producing-raw-markdown) 25 | - [Reading file in multiline comments and producing raw markdown](#reading-file-in-multiline-comments-and-producing-raw-markdown) 26 | - [Reading file in markdown link and producing raw markdown](#reading-file-in-markdown-link-and-producing-raw-markdown) 27 | - [Using inlined values](#using-inlined-values) 28 | - [Producing code blocks](#producing-code-blocks) 29 | - [Executing shell commands](#executing-shell-commands-1) 30 | - [Executing command in inline code and producing code block](#executing-command-in-inline-code-and-producing-code-block) 31 | - [Executing command in code blocks with data line and producing code block](#executing-command-in-code-blocks-with-data-line-and-producing-code-block) 32 | - [Executing command in code blocks and producing code block](#executing-command-in-code-blocks-and-producing-code-block) 33 | - [Executing command in one-line comments and producing code block](#executing-command-in-one-line-comments-and-producing-code-block) 34 | - [Executing command in multiline comments with data line and producing code block](#executing-command-in-multiline-comments-with-data-line-and-producing-code-block) 35 | - [Executing command in multiline comments and producing code block](#executing-command-in-multiline-comments-and-producing-code-block) 36 | - [Executing command in markdown link and producing code block](#executing-command-in-markdown-link-and-producing-code-block) 37 | - [Reading files contents](#reading-files-contents-1) 38 | - [Reading file in inline code and producing code block](#reading-file-in-inline-code-and-producing-code-block) 39 | - [Reading file in code blocks and producing code block](#reading-file-in-code-blocks-and-producing-code-block) 40 | - [Reading file in one-line comments and producing code block](#reading-file-in-one-line-comments-and-producing-code-block) 41 | - [Reading file in multiline comments and producing code block](#reading-file-in-multiline-comments-and-producing-code-block) 42 | - [Reading file in markdown link and producing code block](#reading-file-in-markdown-link-and-producing-code-block) 43 | - [Using inlined values](#using-inlined-values-1) 44 | - [Using inlined data in inline code and producing code block](#using-inlined-data-in-inline-code-and-producing-code-block) 45 | - [Using inlined data in code blocks and producing code block](#using-inlined-data-in-code-blocks-and-producing-code-block) 46 | - [Using inlined data in one-line comments and producing code block](#using-inlined-data-in-one-line-comments-and-producing-code-block) 47 | - [Using inlined data in multiline comments and producing code block](#using-inlined-data-in-multiline-comments-and-producing-code-block) 48 | - [Using inlined data in markdown link and producing code block](#using-inlined-data-in-markdown-link-and-producing-code-block) 49 | - [Sourcing environment variables](#sourcing-environment-variables) 50 | - [Executing shell commands](#executing-shell-commands-2) 51 | - [Executing command in inline code and sourcing env variable(s)](#executing-command-in-inline-code-and-sourcing-env-variables) 52 | - [Executing command in code blocks with data line and sourcing env variable(s)](#executing-command-in-code-blocks-with-data-line-and-sourcing-env-variables) 53 | - [Executing command in code blocks and sourcing env variable(s)](#executing-command-in-code-blocks-and-sourcing-env-variables) 54 | - [Executing command in one-line comments and sourcing env variable(s)](#executing-command-in-one-line-comments-and-sourcing-env-variables) 55 | - [Executing command in multiline comments with data line and sourcing env variable(s)](#executing-command-in-multiline-comments-with-data-line-and-sourcing-env-variables) 56 | - [Executing command in multiline comments and sourcing env variable(s)](#executing-command-in-multiline-comments-and-sourcing-env-variables) 57 | - [Executing command in markdown link and sourcing env variable(s)](#executing-command-in-markdown-link-and-sourcing-env-variables) 58 | - [Reading files contents](#reading-files-contents-2) 59 | - [Reading file in inline code and sourcing env variable(s)](#reading-file-in-inline-code-and-sourcing-env-variables) 60 | - [Reading file in code blocks and sourcing env variable(s)](#reading-file-in-code-blocks-and-sourcing-env-variables) 61 | - [Reading file in one-line comments and sourcing env variable(s)](#reading-file-in-one-line-comments-and-sourcing-env-variables) 62 | - [Reading file in multiline comments and sourcing env variable(s)](#reading-file-in-multiline-comments-and-sourcing-env-variables) 63 | - [Reading file in markdown link and sourcing env variable(s)](#reading-file-in-markdown-link-and-sourcing-env-variables) 64 | - [Using inlined values](#using-inlined-values-2) 65 | - [Using inlined data in inline code and sourcing env variable(s)](#using-inlined-data-in-inline-code-and-sourcing-env-variables) 66 | - [Using inlined data in code blocks and sourcing env variable(s)](#using-inlined-data-in-code-blocks-and-sourcing-env-variables) 67 | - [Using inlined data in one-line comments and sourcing env variable(s)](#using-inlined-data-in-one-line-comments-and-sourcing-env-variables) 68 | - [Using inlined data in multiline comments and sourcing env variable(s)](#using-inlined-data-in-multiline-comments-and-sourcing-env-variables) 69 | 70 | 71 | 72 | ## Producing raw markdown 73 | 74 | ### Executing shell commands 75 | 76 | #### Executing command in inline code and producing raw markdown 77 | 78 | 79 | 80 | `> $ echo 'I am *markdown*'` 81 | 82 | #### Executing command in code blocks with data line and producing raw markdown 83 | 84 | 85 | 86 | ```md > $ sed 's/.*/Hi, \0/' 87 | I am *markdown* 88 | ``` 89 | 90 | #### Executing command in code blocks and producing raw markdown 91 | 92 | 93 | 94 | ```sh > $ 95 | echo 'I am *markdown*' 96 | ``` 97 | 98 | #### Executing command in one-line comments and producing raw markdown 99 | 100 | 101 | 102 | 103 | 104 | #### Executing command in multiline comments with data line and producing raw markdown 105 | 106 | 107 | 108 | 111 | 112 | #### Executing command in multiline comments and producing raw markdown 113 | 114 | 115 | 116 | 119 | 120 | #### Executing command in markdown link and producing raw markdown 121 | 122 | 123 | 124 | [> $ description](./samples/gen-md.sh) 125 | 126 | ### Reading files contents 127 | 128 | #### Reading file in inline code and producing raw markdown 129 | 130 | 131 | 132 | `> < ./samples/example.md` 133 | 134 | #### Reading file in code blocks and producing raw markdown 135 | 136 | 137 | 138 | ```filelist > < 139 | ./samples/example.md 140 | ``` 141 | 142 | #### Reading file in one-line comments and producing raw markdown 143 | 144 | 145 | 146 | 147 | 148 | #### Reading file in multiline comments and producing raw markdown 149 | 150 | 151 | 152 | 155 | 156 | #### Reading file in markdown link and producing raw markdown 157 | 158 | 159 | 160 | [> < description](./samples/example.md) 161 | 162 | ### Using inlined values 163 | 164 | ## Producing code blocks 165 | 166 | ### Executing shell commands 167 | 168 | #### Executing command in inline code and producing code block 169 | 170 | 171 | 172 | `> yaml $ echo 'foo: true'` 173 | 174 | #### Executing command in code blocks with data line and producing code block 175 | 176 | 177 | 178 | ```yml > yaml $ sed 's/.*/\0 # hmm/' 179 | foo: true 180 | ``` 181 | 182 | #### Executing command in code blocks and producing code block 183 | 184 | 185 | 186 | ```sh > yaml $ 187 | echo 'foo: true' 188 | ``` 189 | 190 | #### Executing command in one-line comments and producing code block 191 | 192 | 193 | 194 | 195 | 196 | #### Executing command in multiline comments with data line and producing code block 197 | 198 | 199 | 200 | 203 | 204 | #### Executing command in multiline comments and producing code block 205 | 206 | 207 | 208 | 211 | 212 | #### Executing command in markdown link and producing code block 213 | 214 | 215 | 216 | [> yaml $ description](./samples/gen-yml.sh) 217 | 218 | ### Reading files contents 219 | 220 | #### Reading file in inline code and producing code block 221 | 222 | 223 | 224 | `> yaml < ./samples/example.yml` 225 | 226 | #### Reading file in code blocks and producing code block 227 | 228 | 229 | 230 | ```filelist > yaml < 231 | ./samples/example.yml 232 | ``` 233 | 234 | #### Reading file in one-line comments and producing code block 235 | 236 | 237 | 238 | 239 | 240 | #### Reading file in multiline comments and producing code block 241 | 242 | 243 | 244 | 247 | 248 | #### Reading file in markdown link and producing code block 249 | 250 | 251 | 252 | [> yaml < description](./samples/example.yml) 253 | 254 | ### Using inlined values 255 | 256 | #### Using inlined data in inline code and producing code block 257 | 258 | 259 | 260 | `> yaml foo: true` 261 | 262 | #### Using inlined data in code blocks and producing code block 263 | 264 | 265 | 266 | ```yml > yaml 267 | foo: true 268 | ``` 269 | 270 | #### Using inlined data in one-line comments and producing code block 271 | 272 | 273 | 274 | 275 | 276 | #### Using inlined data in multiline comments and producing code block 277 | 278 | 279 | 280 | 283 | 284 | #### Using inlined data in markdown link and producing code block 285 | 286 | 287 | 288 | [> yaml description](./samples/example.yml) 289 | 290 | ## Sourcing environment variables 291 | 292 | ### Executing shell commands 293 | 294 | #### Executing command in inline code and sourcing env variable(s) 295 | 296 | 297 | 298 | `! $ echo 'foo=bar'` 299 | 300 | ``> $ echo "\`\$foo\` is $foo"`` 301 | 302 | #### Executing command in code blocks with data line and sourcing env variable(s) 303 | 304 | 305 | 306 | ```env ! $ sed 's/.*/\0 # hmm/' 307 | foo=bar 308 | ``` 309 | 310 | ``> $ echo "\`\$foo\` is $foo"`` 311 | 312 | #### Executing command in code blocks and sourcing env variable(s) 313 | 314 | 315 | 316 | ```sh ! $ 317 | echo 'foo=bar' 318 | ``` 319 | 320 | ``> $ echo "\`\$foo\` is $foo"`` 321 | 322 | #### Executing command in one-line comments and sourcing env variable(s) 323 | 324 | 325 | 326 | 327 | 328 | ``> $ echo "\`\$foo\` is $foo"`` 329 | 330 | #### Executing command in multiline comments with data line and sourcing env variable(s) 331 | 332 | 333 | 334 | 337 | 338 | ``> $ echo "\`\$foo\` is $foo"`` 339 | 340 | #### Executing command in multiline comments and sourcing env variable(s) 341 | 342 | 343 | 344 | 347 | 348 | ``> $ echo "\`\$foo\` is $foo"`` 349 | 350 | #### Executing command in markdown link and sourcing env variable(s) 351 | 352 | 353 | 354 | [! $ description](./samples/gen-env.sh) 355 | 356 | ``> $ echo "\`\$foo\` is $foo"`` 357 | 358 | ### Reading files contents 359 | 360 | #### Reading file in inline code and sourcing env variable(s) 361 | 362 | 363 | 364 | `! < ./samples/example.env` 365 | 366 | ``> $ echo "\`\$foo\` is $foo"`` 367 | 368 | #### Reading file in code blocks and sourcing env variable(s) 369 | 370 | 371 | 372 | ```filelist ! < 373 | ./samples/example.env 374 | ``` 375 | 376 | ``> $ echo "\`\$foo\` is $foo"`` 377 | 378 | #### Reading file in one-line comments and sourcing env variable(s) 379 | 380 | 381 | 382 | 383 | 384 | ``> $ echo "\`\$foo\` is $foo"`` 385 | 386 | #### Reading file in multiline comments and sourcing env variable(s) 387 | 388 | 389 | 390 | 393 | 394 | ``> $ echo "\`\$foo\` is $foo"`` 395 | 396 | #### Reading file in markdown link and sourcing env variable(s) 397 | 398 | 399 | 400 | [! < description](./samples/example.env) 401 | 402 | ``> $ echo "\`\$foo\` is $foo"`` 403 | 404 | ### Using inlined values 405 | 406 | #### Using inlined data in inline code and sourcing env variable(s) 407 | 408 | 409 | 410 | `! foo=bar` 411 | 412 | ``> $ echo "\`\$foo\` is $foo"`` 413 | 414 | #### Using inlined data in code blocks and sourcing env variable(s) 415 | 416 | 417 | 418 | ```env ! 419 | foo=bar 420 | ``` 421 | 422 | ``> $ echo "\`\$foo\` is $foo"`` 423 | 424 | #### Using inlined data in one-line comments and sourcing env variable(s) 425 | 426 | 427 | 428 | 429 | 430 | ``> $ echo "\`\$foo\` is $foo"`` 431 | 432 | #### Using inlined data in multiline comments and sourcing env variable(s) 433 | 434 | 435 | 436 | 439 | 440 | ``> $ echo "\`\$foo\` is $foo"`` 441 | 442 | The end! 443 | -------------------------------------------------------------------------------- /spec.processed.md: -------------------------------------------------------------------------------- 1 | # `mdsh` spec. 2 | 3 | Each H4 section is converted into a test case by `build.rs` script. Each section 4 | in `spec.clear.md` must correspond to the same section in `spec.processed.md`. 5 | `spec.processed.md` is a version of this file after one `mdsh` pass. 6 | `spec.processed.md` must be idempotent, i.e. any next passes result in the same content. 7 | `mdsh --clean` pass on `spec.processed.md` must result in `spec.clear.md`. 8 | 9 | 10 | 11 | 12 | - [Producing raw markdown](#producing-raw-markdown) 13 | - [Executing shell commands](#executing-shell-commands) 14 | - [Executing command in inline code and producing raw markdown](#executing-command-in-inline-code-and-producing-raw-markdown) 15 | - [Executing command in code blocks with data line and producing raw markdown](#executing-command-in-code-blocks-with-data-line-and-producing-raw-markdown) 16 | - [Executing command in code blocks and producing raw markdown](#executing-command-in-code-blocks-and-producing-raw-markdown) 17 | - [Executing command in one-line comments and producing raw markdown](#executing-command-in-one-line-comments-and-producing-raw-markdown) 18 | - [Executing command in multiline comments with data line and producing raw markdown](#executing-command-in-multiline-comments-with-data-line-and-producing-raw-markdown) 19 | - [Executing command in multiline comments and producing raw markdown](#executing-command-in-multiline-comments-and-producing-raw-markdown) 20 | - [Executing command in markdown link and producing raw markdown](#executing-command-in-markdown-link-and-producing-raw-markdown) 21 | - [Reading files contents](#reading-files-contents) 22 | - [Reading file in inline code and producing raw markdown](#reading-file-in-inline-code-and-producing-raw-markdown) 23 | - [Reading file in code blocks and producing raw markdown](#reading-file-in-code-blocks-and-producing-raw-markdown) 24 | - [Reading file in one-line comments and producing raw markdown](#reading-file-in-one-line-comments-and-producing-raw-markdown) 25 | - [Reading file in multiline comments and producing raw markdown](#reading-file-in-multiline-comments-and-producing-raw-markdown) 26 | - [Reading file in markdown link and producing raw markdown](#reading-file-in-markdown-link-and-producing-raw-markdown) 27 | - [Using inlined values](#using-inlined-values) 28 | - [Producing code blocks](#producing-code-blocks) 29 | - [Executing shell commands](#executing-shell-commands-1) 30 | - [Executing command in inline code and producing code block](#executing-command-in-inline-code-and-producing-code-block) 31 | - [Executing command in code blocks with data line and producing code block](#executing-command-in-code-blocks-with-data-line-and-producing-code-block) 32 | - [Executing command in code blocks and producing code block](#executing-command-in-code-blocks-and-producing-code-block) 33 | - [Executing command in one-line comments and producing code block](#executing-command-in-one-line-comments-and-producing-code-block) 34 | - [Executing command in multiline comments with data line and producing code block](#executing-command-in-multiline-comments-with-data-line-and-producing-code-block) 35 | - [Executing command in multiline comments and producing code block](#executing-command-in-multiline-comments-and-producing-code-block) 36 | - [Executing command in markdown link and producing code block](#executing-command-in-markdown-link-and-producing-code-block) 37 | - [Reading files contents](#reading-files-contents-1) 38 | - [Reading file in inline code and producing code block](#reading-file-in-inline-code-and-producing-code-block) 39 | - [Reading file in code blocks and producing code block](#reading-file-in-code-blocks-and-producing-code-block) 40 | - [Reading file in one-line comments and producing code block](#reading-file-in-one-line-comments-and-producing-code-block) 41 | - [Reading file in multiline comments and producing code block](#reading-file-in-multiline-comments-and-producing-code-block) 42 | - [Reading file in markdown link and producing code block](#reading-file-in-markdown-link-and-producing-code-block) 43 | - [Using inlined values](#using-inlined-values-1) 44 | - [Using inlined data in inline code and producing code block](#using-inlined-data-in-inline-code-and-producing-code-block) 45 | - [Using inlined data in code blocks and producing code block](#using-inlined-data-in-code-blocks-and-producing-code-block) 46 | - [Using inlined data in one-line comments and producing code block](#using-inlined-data-in-one-line-comments-and-producing-code-block) 47 | - [Using inlined data in multiline comments and producing code block](#using-inlined-data-in-multiline-comments-and-producing-code-block) 48 | - [Using inlined data in markdown link and producing code block](#using-inlined-data-in-markdown-link-and-producing-code-block) 49 | - [Sourcing environment variables](#sourcing-environment-variables) 50 | - [Executing shell commands](#executing-shell-commands-2) 51 | - [Executing command in inline code and sourcing env variable(s)](#executing-command-in-inline-code-and-sourcing-env-variables) 52 | - [Executing command in code blocks with data line and sourcing env variable(s)](#executing-command-in-code-blocks-with-data-line-and-sourcing-env-variables) 53 | - [Executing command in code blocks and sourcing env variable(s)](#executing-command-in-code-blocks-and-sourcing-env-variables) 54 | - [Executing command in one-line comments and sourcing env variable(s)](#executing-command-in-one-line-comments-and-sourcing-env-variables) 55 | - [Executing command in multiline comments with data line and sourcing env variable(s)](#executing-command-in-multiline-comments-with-data-line-and-sourcing-env-variables) 56 | - [Executing command in multiline comments and sourcing env variable(s)](#executing-command-in-multiline-comments-and-sourcing-env-variables) 57 | - [Executing command in markdown link and sourcing env variable(s)](#executing-command-in-markdown-link-and-sourcing-env-variables) 58 | - [Reading files contents](#reading-files-contents-2) 59 | - [Reading file in inline code and sourcing env variable(s)](#reading-file-in-inline-code-and-sourcing-env-variables) 60 | - [Reading file in code blocks and sourcing env variable(s)](#reading-file-in-code-blocks-and-sourcing-env-variables) 61 | - [Reading file in one-line comments and sourcing env variable(s)](#reading-file-in-one-line-comments-and-sourcing-env-variables) 62 | - [Reading file in multiline comments and sourcing env variable(s)](#reading-file-in-multiline-comments-and-sourcing-env-variables) 63 | - [Reading file in markdown link and sourcing env variable(s)](#reading-file-in-markdown-link-and-sourcing-env-variables) 64 | - [Using inlined values](#using-inlined-values-2) 65 | - [Using inlined data in inline code and sourcing env variable(s)](#using-inlined-data-in-inline-code-and-sourcing-env-variables) 66 | - [Using inlined data in code blocks and sourcing env variable(s)](#using-inlined-data-in-code-blocks-and-sourcing-env-variables) 67 | - [Using inlined data in one-line comments and sourcing env variable(s)](#using-inlined-data-in-one-line-comments-and-sourcing-env-variables) 68 | - [Using inlined data in multiline comments and sourcing env variable(s)](#using-inlined-data-in-multiline-comments-and-sourcing-env-variables) 69 | 70 | 71 | 72 | ## Producing raw markdown 73 | 74 | ### Executing shell commands 75 | 76 | #### Executing command in inline code and producing raw markdown 77 | 78 | 79 | 80 | `> $ echo 'I am *markdown*'` 81 | 82 | 83 | I am *markdown* 84 | 85 | 86 | #### Executing command in code blocks with data line and producing raw markdown 87 | 88 | 89 | 90 | ```md > $ sed 's/.*/Hi, \0/' 91 | I am *markdown* 92 | ``` 93 | 94 | 95 | Hi, I am *markdown* 96 | 97 | 98 | #### Executing command in code blocks and producing raw markdown 99 | 100 | 101 | 102 | ```sh > $ 103 | echo 'I am *markdown*' 104 | ``` 105 | 106 | 107 | I am *markdown* 108 | 109 | 110 | #### Executing command in one-line comments and producing raw markdown 111 | 112 | 113 | 114 | 115 | 116 | 117 | I am *markdown* 118 | 119 | 120 | #### Executing command in multiline comments with data line and producing raw markdown 121 | 122 | 123 | 124 | 127 | 128 | 129 | Hi, I am *markdown* 130 | 131 | 132 | #### Executing command in multiline comments and producing raw markdown 133 | 134 | 135 | 136 | 139 | 140 | 141 | I am *markdown* 142 | 143 | 144 | #### Executing command in markdown link and producing raw markdown 145 | 146 | 147 | 148 | [> $ description](./samples/gen-md.sh) 149 | 150 | 151 | I'm gen-md.sh 152 | 153 | 154 | ### Reading files contents 155 | 156 | #### Reading file in inline code and producing raw markdown 157 | 158 | 159 | 160 | `> < ./samples/example.md` 161 | 162 | 163 | *this is part of the example.md file* 164 | 165 | 166 | #### Reading file in code blocks and producing raw markdown 167 | 168 | 169 | 170 | ```filelist > < 171 | ./samples/example.md 172 | ``` 173 | 174 | 175 | *this is part of the example.md file* 176 | 177 | 178 | #### Reading file in one-line comments and producing raw markdown 179 | 180 | 181 | 182 | 183 | 184 | 185 | *this is part of the example.md file* 186 | 187 | 188 | #### Reading file in multiline comments and producing raw markdown 189 | 190 | 191 | 192 | 195 | 196 | 197 | *this is part of the example.md file* 198 | 199 | 200 | #### Reading file in markdown link and producing raw markdown 201 | 202 | 203 | 204 | [> < description](./samples/example.md) 205 | 206 | 207 | *this is part of the example.md file* 208 | 209 | 210 | ### Using inlined values 211 | 212 | ## Producing code blocks 213 | 214 | ### Executing shell commands 215 | 216 | #### Executing command in inline code and producing code block 217 | 218 | 219 | 220 | `> yaml $ echo 'foo: true'` 221 | 222 | 223 | ```yaml 224 | foo: true 225 | ``` 226 | 227 | 228 | #### Executing command in code blocks with data line and producing code block 229 | 230 | 231 | 232 | ```yml > yaml $ sed 's/.*/\0 # hmm/' 233 | foo: true 234 | ``` 235 | 236 | 237 | ```yaml 238 | foo: true # hmm 239 | ``` 240 | 241 | 242 | #### Executing command in code blocks and producing code block 243 | 244 | 245 | 246 | ```sh > yaml $ 247 | echo 'foo: true' 248 | ``` 249 | 250 | 251 | ```yaml 252 | foo: true 253 | ``` 254 | 255 | 256 | #### Executing command in one-line comments and producing code block 257 | 258 | 259 | 260 | 261 | 262 | 263 | ```yaml 264 | foo: true 265 | ``` 266 | 267 | 268 | #### Executing command in multiline comments with data line and producing code block 269 | 270 | 271 | 272 | 275 | 276 | 277 | ```yaml 278 | foo: true # hmm 279 | ``` 280 | 281 | 282 | #### Executing command in multiline comments and producing code block 283 | 284 | 285 | 286 | 289 | 290 | 291 | ```yaml 292 | foo: true 293 | ``` 294 | 295 | 296 | #### Executing command in markdown link and producing code block 297 | 298 | 299 | 300 | [> yaml $ description](./samples/gen-yml.sh) 301 | 302 | 303 | ```yaml 304 | foo: bar 305 | ``` 306 | 307 | 308 | ### Reading files contents 309 | 310 | #### Reading file in inline code and producing code block 311 | 312 | 313 | 314 | `> yaml < ./samples/example.yml` 315 | 316 | 317 | ```yaml 318 | foo: bar 319 | ``` 320 | 321 | 322 | #### Reading file in code blocks and producing code block 323 | 324 | 325 | 326 | ```filelist > yaml < 327 | ./samples/example.yml 328 | ``` 329 | 330 | 331 | ```yaml 332 | foo: bar 333 | ``` 334 | 335 | 336 | #### Reading file in one-line comments and producing code block 337 | 338 | 339 | 340 | 341 | 342 | 343 | ```yaml 344 | foo: bar 345 | ``` 346 | 347 | 348 | #### Reading file in multiline comments and producing code block 349 | 350 | 351 | 352 | 355 | 356 | 357 | ```yaml 358 | foo: bar 359 | ``` 360 | 361 | 362 | #### Reading file in markdown link and producing code block 363 | 364 | 365 | 366 | [> yaml < description](./samples/example.yml) 367 | 368 | 369 | ```yaml 370 | foo: bar 371 | ``` 372 | 373 | 374 | ### Using inlined values 375 | 376 | #### Using inlined data in inline code and producing code block 377 | 378 | 379 | 380 | `> yaml foo: true` 381 | 382 | 383 | ```yaml 384 | foo: true 385 | ``` 386 | 387 | 388 | #### Using inlined data in code blocks and producing code block 389 | 390 | 391 | 392 | ```yml > yaml 393 | foo: true 394 | ``` 395 | 396 | 397 | ```yaml 398 | foo: true 399 | ``` 400 | 401 | 402 | #### Using inlined data in one-line comments and producing code block 403 | 404 | 405 | 406 | 407 | 408 | 409 | ```yaml 410 | foo: true 411 | ``` 412 | 413 | 414 | #### Using inlined data in multiline comments and producing code block 415 | 416 | 417 | 418 | 421 | 422 | 423 | ```yaml 424 | foo: true 425 | ``` 426 | 427 | 428 | #### Using inlined data in markdown link and producing code block 429 | 430 | 431 | 432 | [> yaml description](./samples/example.yml) 433 | 434 | 435 | ```yaml 436 | ./samples/example.yml 437 | ``` 438 | 439 | 440 | ## Sourcing environment variables 441 | 442 | ### Executing shell commands 443 | 444 | #### Executing command in inline code and sourcing env variable(s) 445 | 446 | 447 | 448 | `! $ echo 'foo=bar'` 449 | 450 | ``> $ echo "\`\$foo\` is $foo"`` 451 | 452 | 453 | `$foo` is bar 454 | 455 | 456 | #### Executing command in code blocks with data line and sourcing env variable(s) 457 | 458 | 459 | 460 | ```env ! $ sed 's/.*/\0 # hmm/' 461 | foo=bar 462 | ``` 463 | 464 | ``> $ echo "\`\$foo\` is $foo"`` 465 | 466 | 467 | `$foo` is bar 468 | 469 | 470 | #### Executing command in code blocks and sourcing env variable(s) 471 | 472 | 473 | 474 | ```sh ! $ 475 | echo 'foo=bar' 476 | ``` 477 | 478 | ``> $ echo "\`\$foo\` is $foo"`` 479 | 480 | 481 | `$foo` is bar 482 | 483 | 484 | #### Executing command in one-line comments and sourcing env variable(s) 485 | 486 | 487 | 488 | 489 | 490 | ``> $ echo "\`\$foo\` is $foo"`` 491 | 492 | 493 | `$foo` is bar 494 | 495 | 496 | #### Executing command in multiline comments with data line and sourcing env variable(s) 497 | 498 | 499 | 500 | 503 | 504 | ``> $ echo "\`\$foo\` is $foo"`` 505 | 506 | 507 | `$foo` is bar 508 | 509 | 510 | #### Executing command in multiline comments and sourcing env variable(s) 511 | 512 | 513 | 514 | 517 | 518 | ``> $ echo "\`\$foo\` is $foo"`` 519 | 520 | 521 | `$foo` is bar 522 | 523 | 524 | #### Executing command in markdown link and sourcing env variable(s) 525 | 526 | 527 | 528 | [! $ description](./samples/gen-env.sh) 529 | 530 | ``> $ echo "\`\$foo\` is $foo"`` 531 | 532 | 533 | `$foo` is bar 534 | 535 | 536 | ### Reading files contents 537 | 538 | #### Reading file in inline code and sourcing env variable(s) 539 | 540 | 541 | 542 | `! < ./samples/example.env` 543 | 544 | ``> $ echo "\`\$foo\` is $foo"`` 545 | 546 | 547 | `$foo` is bar 548 | 549 | 550 | #### Reading file in code blocks and sourcing env variable(s) 551 | 552 | 553 | 554 | ```filelist ! < 555 | ./samples/example.env 556 | ``` 557 | 558 | ``> $ echo "\`\$foo\` is $foo"`` 559 | 560 | 561 | `$foo` is bar 562 | 563 | 564 | #### Reading file in one-line comments and sourcing env variable(s) 565 | 566 | 567 | 568 | 569 | 570 | ``> $ echo "\`\$foo\` is $foo"`` 571 | 572 | 573 | `$foo` is bar 574 | 575 | 576 | #### Reading file in multiline comments and sourcing env variable(s) 577 | 578 | 579 | 580 | 583 | 584 | ``> $ echo "\`\$foo\` is $foo"`` 585 | 586 | 587 | `$foo` is bar 588 | 589 | 590 | #### Reading file in markdown link and sourcing env variable(s) 591 | 592 | 593 | 594 | [! < description](./samples/example.env) 595 | 596 | ``> $ echo "\`\$foo\` is $foo"`` 597 | 598 | 599 | `$foo` is bar 600 | 601 | 602 | ### Using inlined values 603 | 604 | #### Using inlined data in inline code and sourcing env variable(s) 605 | 606 | 607 | 608 | `! foo=bar` 609 | 610 | ``> $ echo "\`\$foo\` is $foo"`` 611 | 612 | 613 | `$foo` is bar 614 | 615 | 616 | #### Using inlined data in code blocks and sourcing env variable(s) 617 | 618 | 619 | 620 | ```env ! 621 | foo=bar 622 | ``` 623 | 624 | ``> $ echo "\`\$foo\` is $foo"`` 625 | 626 | 627 | `$foo` is bar 628 | 629 | 630 | #### Using inlined data in one-line comments and sourcing env variable(s) 631 | 632 | 633 | 634 | 635 | 636 | ``> $ echo "\`\$foo\` is $foo"`` 637 | 638 | 639 | `$foo` is bar 640 | 641 | 642 | #### Using inlined data in multiline comments and sourcing env variable(s) 643 | 644 | 645 | 646 | 649 | 650 | ``> $ echo "\`\$foo\` is $foo"`` 651 | 652 | 653 | `$foo` is bar 654 | 655 | 656 | The end! 657 | --------------------------------------------------------------------------------