man/augparse.pod

   1 =head1 NAME
   2
   3 augparse - execute an Augeas module
   4
   5 =head1 SYNOPSIS
   6
   7 augparse [OPTIONS] MODULE
   8
   9 =head1 DESCRIPTION
  10
  11 Execute an Augeas module, most commonly to evaluate the tests it contains.
  12
  13 =head1 OPTIONS
  14
  15 =over 4
  16
  17 =item B<-I>, B<--include>=I<DIR>
  18
  19 Add DIR to the module loadpath. Can be given multiple times. The
  20 directories set here are searched before any directories specified in the
  21 AUGEAS_LENS_LIB environment variable, and before the default directory
  22 F</usr/share/augeas/lenses>.
  23
  24 =item B<-t>, B<--trace>
  25
  26 Print a trace of the modules that are being loaded.
  27
  28 =item B<--nostdinc>
  29
  30 Do not search any of the default directories for modules. When this option
  31 is set, only directories specified explicitly with B<-I> or specified in
  32 B<AUGEAS_LENS_LIB> will be searched for modules.
  33
  34 =item B<--notypecheck>
  35
  36 Do not perform lens type checks. Only use this option during lens
  37 development and make sure you typecheck lenses when you are done developing
  38 - you should never use a lens that hasn't been typechecked. This option is
  39 sometimes useful when you are working on unit tests for a lens to speed up
  40 the time it takes to repeatedly run and fix tests.
  41
  42 =item B<--version>
  43
  44 Print version information and exit.
  45
  46 =item B<-h>
  47
  48 Display this help and exit
  49
  50 =back
  51
  52 =head1 EXAMPLES
  53
  54 To run the tests in F<lenses/tests/test_foo.aug> and use modules from the
  55 directory F<lenses>, run
  56
  57 =over 4
  58
  59 augparse -I lenses lenses/tests/test_foo.aug
  60
  61 =back
  62
  63 =head1 TESTS
  64
  65 Tests can appear as top-level forms anywhere in a module. Generally, the
  66 tests for a module F<lenses/foo.aug> are kept in a separate file, usually
  67 in F<lenses/tests/test_foo.aug>.
  68
  69 There are two different kinds of tests that Augeas can run: B<get> and
  70 B<put> tests. The syntax for B<get> tests is
  71
  72 =over 4
  73
  74 test LENS get STRING = RESULT
  75
  76 =back
  77
  78 which applies the I<get> direction of the lens LENS to STRING and compares
  79 it with the given RESULT. RESULT can either be a tree literal, the symbol
  80 B<?> to print the result of applying LENS to STRING, or the symbol B<*> to
  81 indicate that the test should produce an exception.
  82
  83 The syntax for B<put> tests is
  84
  85 =over 4
  86
  87 test LENS put STRING after COMMANDS = RESULT
  88
  89 =back
  90
  91 which first applies the I<get> direction of the lens LENS to STRING, then
  92 applies the given COMMANDS to the resulting tree, and finally transforms
  93 the modified tree back to a string using the I<put> direction of LENS. The
  94 resulting string is then compared to RESULT, which can be a string, the
  95 symbol B<?> to print the result of applying LENS to STRING, or the symbol
  96 B<*> to indicate that the test should produce an exception.
  97
  98 =head1 AUTHOR
  99
 100 David Lutterkort <lutter@watzmann.net>
 101
 102 =head1 COPYRIGHT AND LICENSE
 103
 104 Copyright 2007-2016 David Lutterkort
 105
 106 Augeas (and augparse) are distributed under the GNU Lesser General Public
 107 License (LGPL)
 108
 109 =head1 SEE ALSO
 110
 111 B<Augeas> project homepage L<http://www.augeas.net/>
 112
 113 L<augtool>