AUGPARSE(1)

📦
version 1.15.0 · 11 versions
, in arch rolling

💅 AUGPARSE(1) — the Augeas module runner, bestie edition 🦋

okay so real talk: this is augparse, and it lives in the Augeas 1 manual. it's the little tool that executes an Augeas module — and mostly what you're doing with it is running the tests inside that module. that's the whole vibe. ✨

🌸 NAME 🌸

augparse — execute an Augeas module, no cap.

🎀 SYNOPSIS 🎀

augparse [OPTIONS] MODULE

💖 DESCRIPTION 💖

so basically you hand augparse a module and it runs it. that's it, that's the gig. the most common reason you'd ever do this is to evaluate all the tests the module contains — it's giving "test runner but make it lens development". 🧚

✨ OPTIONS ✨

  • -I, --include=DIR — adds DIR to the module loadpath. you can pass this multiple times, go off 👑. the directories you set here get searched before anything in the AUGEAS_LENS_LIB environment variable, and before the default directory /usr/share/augeas/lenses. order matters, periodt.
  • -t, --trace — prints a trace of the modules that are being loaded. very "show me the receipts" of it all 🔥.
  • --nostdinc — do not search any of the default directories for modules. when this is set, the only places searched for modules are the ones you explicitly passed with -I or the ones sitting in AUGEAS_LENS_LIB. that's it, that's the list 💀.
  • --notypecheck — skips lens type checks. ⚠️ only use this while you're actively developing a lens, and make sure you typecheck your lenses when you're done — you should never use a lens that hasn't been typechecked. the one (1) valid use case: when you're working on unit tests for a lens and you want to speed up how long it takes to repeatedly run and fix those tests. it's a convenience, not a lifestyle 🙈.
  • --version — prints version info and dips out. bye 💅
  • -h — displays this help and exits. the classic.

🌈 EXAMPLES 🌈

say you wanna run the tests in lenses/tests/test_foo.aug and also pull modules from the directory lenses. you'd run:

augparse -I lenses lenses/tests/test_foo.aug

ate, no crumbs 🍓

🦋 TESTS 🦋

tests can appear as top-level forms anywhere in a module, slay. generally though, the tests for a module lenses/foo.aug are kept in their own separate file, usually lenses/tests/test_foo.aug. keeping it tidy, we love to see it 💜.

Augeas can run two different kinds of tests: get tests and put tests. let's go.

the syntax for get tests is:

test LENS get STRING = RESULT

this applies the get direction of the lens LENS to STRING and compares it against the given RESULT. and RESULT can be one of three things:

  • a tree literal 🌳
  • the symbol ?, which prints the result of applying LENS to STRING
  • the symbol *, which means the test should produce an exception 😭

the syntax for put tests is:

test LENS put STRING after COMMANDS = RESULT

this one's a whole journey: first it applies the get direction of the lens LENS to STRING, then it applies the given COMMANDS to the resulting tree, and finally it transforms the modified tree back to a string using the put direction of LENS. then it compares the resulting string to RESULT. and RESULT here can be:

  • a string
  • the symbol ? to print the result of applying LENS to STRING
  • the symbol * to indicate that the test should produce an exception 💀

main character energy from start to finish, honestly.

👑 AUTHOR 👑

David Lutterkort <lutter@watzmann.net>

Copyright 2007-2016 David Lutterkort

Augeas (and augparse) are distributed under the GNU Lesser General Public License (LGPL).

🫶 SEE ALSO 🫶

💌 cute little sign-off: this iconic page comes from Augeas 1.15.0, dated 2026-09-29, and no, we are not typing out AUGPARSE(1) again at the bottom like a boring footer. consider it mentioned. mwah 💋
📦 where this page comes from