parse-dockerfile

Dockerfile parser, written in Rust.

• Usage (CLI)
  • Installation
• Usage (Library)
• License

Usage (CLI)

parse-dockerfile command parses dockerfile and outputs a JSON representation of all instructions in dockerfile.

$ parse-dockerfile --help
parse-dockerfile

Parse a dockerfile and output a JSON representation of all instructions in dockerfile.

USAGE:
    parse-dockerfile [OPTIONS] <PATH>

ARGS:
    <PATH>       Path to the dockerfile (use '-' for standard input)

OPTIONS:
    -h, --help                        Print help information
    -V, --version                     Print version information

Examples

$ cat Dockerfile
ARG UBUNTU_VERSION=latest

FROM ubuntu:${UBUNTU_VERSION}
RUN echo

$ parse-dockerfile Dockerfile | jq
{
  "parser_directives": {
    "syntax": null,
    "escape": null,
    "check": null
  },
  "instructions": [
    {
      "kind": "ARG",
      "arg": {
        "span": {
          "start": 0,
          "end": 3
        }
      },
      "arguments": {
        "span": {
          "start": 4,
          "end": 18
        },
        "value": "UBUNTU_VERSION=latest"
      }
    },
    {
      "kind": "FROM",
      "from": {
        "span": {
          "start": 20,
          "end": 24
        }
      },
      "options": [],
      "image": {
        "span": {
          "start": 25,
          "end": 49
        },
        "value": "ubuntu:${UBUNTU_VERSION}"
      },
      "as_": null
    },
    {
      "kind": "RUN",
      "run": {
        "span": {
          "start": 50,
          "end": 53
        }
      },
      "options": [],
      "arguments": {
        "shell": {
          "span": {
            "start": 54,
            "end": 58
          },
          "value": "echo"
        }
      },
      "here_docs": []
    }
  ]
}

Installation

From source

cargo +stable install parse-dockerfile --locked

From prebuilt binaries

You can download prebuilt binaries from the Release page. Prebuilt binaries are available for macOS, Linux (gnu and musl), Windows (static executable), FreeBSD, and illumos.

# Get host target
host=$(rustc -vV | grep '^host:' | cut -d' ' -f2)
# Download binary and install to $HOME/.cargo/bin
curl --proto '=https' --tlsv1.2 -fsSL "https://github.com/taiki-e/parse-dockerfile/releases/latest/download/parse-dockerfile-$host.tar.gz" \
  | tar xzf - -C "$HOME/.cargo/bin"

Via Homebrew

You can install parse-dockerfile from the Homebrew tap maintained by us (x86_64/AArch64 macOS, x86_64/AArch64 Linux):

brew install taiki-e/tap/parse-dockerfile

Via Scoop (Windows)

You can install parse-dockerfile from the Scoop bucket maintained by us:

scoop bucket add taiki-e https://github.com/taiki-e/scoop-bucket
scoop install parse-dockerfile

Via cargo-binstall

You can install parse-dockerfile using cargo-binstall:

cargo binstall parse-dockerfile

On GitHub Actions

You can use taiki-e/install-action to install prebuilt binaries on Linux, macOS, and Windows. This makes the installation faster and may avoid the impact of problems caused by upstream changes.

- uses: taiki-e/install-action@parse-dockerfile

Usage (Library)

To use this crate as a library, add this to your Cargo.toml:

[dependencies]
parse-dockerfile = { version = "0.1", default-features = false }

[!NOTE] When using this crate as a library, we recommend disabling the default features because the default features enable CLI-related dependencies and the library part of this crate does not use them.

Examples

use parse_dockerfile::{parse, Instruction};

let text = r#"
ARG UBUNTU_VERSION=latest

FROM ubuntu:${UBUNTU_VERSION}
RUN echo
"#;

let dockerfile = parse(text).unwrap();

// Iterate over all instructions.
let mut instructions = dockerfile.instructions.iter();
assert!(matches!(instructions.next(), Some(Instruction::Arg(..))));
assert!(matches!(instructions.next(), Some(Instruction::From(..))));
assert!(matches!(instructions.next(), Some(Instruction::Run(..))));
assert!(matches!(instructions.next(), None));

// Iterate over global args.
let mut global_args = dockerfile.global_args();
let global_arg1 = global_args.next().unwrap();
assert_eq!(global_arg1.arguments.value, "UBUNTU_VERSION=latest");
assert!(matches!(global_args.next(), None));

// Iterate over stages.
let mut stages = dockerfile.stages();
let stage1 = stages.next().unwrap();
assert_eq!(stage1.from.image.value, "ubuntu:${UBUNTU_VERSION}");
let mut stage1_instructions = stage1.instructions.iter();
assert!(matches!(stage1_instructions.next(), Some(Instruction::Run(..))));
assert!(matches!(stage1_instructions.next(), None));
assert!(matches!(stages.next(), None));

See documentation for more information on parse-dockerfile as a library.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.