miconf/README

   1 #miconf
   2 ##Name
   3 `miconf` - lightweight configuration utility
   4 ##Synopsis
   5         miconf -h
   6         miconf [options] -r directory
   7         miconf [options] template_file output_file
   8 ##Description
   9 `miconf` is a lightweight configuration utility based on simple template substitution technique and [Lua](http://www.lua.org/) expressions. It executes a configuration file (a Lua program), and then uses the results of the execution (its global state) in template substitution. It reads `template_file` and substitutes `<<<`*lua expression*`>>>` placeholders with evaluated *lua expression*. It also executes lines that start with `===`.
  10
  11 For example:
  12
  13         . . .
  14         === for x = 1, 3 do
  15         <<<x>>> ^ 3 = <<< x^3 >>>
  16         === end
  17         . . .
  18
  19 will result in the following output:
  20
  21         . . .
  22         1 ^ 3 = 1
  23         2 ^ 3 = 8
  24         3 ^ 3 = 27
  25         . . .
  26
  27
  28 When `miconf` is run in recoursive `-r` mode, it traverses `directory` recoursively and processes files based on the pattern (`-p` option) and the output of callback functions.
  29
  30 `miconf` executable is a self sufficient executable that requires only a C runtime.
  31
  32 ##Options
  33
  34 | Option  | Default value | Description | Example |
  35 | :--- | :--- | :--- | :--- |
  36 | -c file | 'config.lua' | config file | -c system.config |
  37 | -e block | '' | config block | -e 'host="foo"; ip="127.0.0.1"'|
  38 | -p pattern | '[.]template$' | template file name pattern | -p '^boo[.]' |
  39 | -t | | preserve temp files | |
  40 | -m | | disable chmod | |
  41 | -v | | verbose | |
  42
  43 ##Default hooks
  44
  45 The following "hooks" are used if you do not redefine them in your configuration files.
  46 These functions get called when `miconf` is run in recoursive mode using `-r` option. `miconf_dname_hook` is invoked for each subdirectory, and `miconf_fname_hook` is called for each regular file. `miconf_dname_hook` has to return a full path to the subdirectory to traverse, or `nil` to ignore the whole subdirectory. `miconf_fname_hook` has to return input and output file paths, or `(nil,nil)` in order to ignore the file. These functions allow you customize `miconf` behavior, i.e. what parts of your tree and what files to process, and how to come up with output file names. For example, you may keep your templates at a separate directory and output files into your output tree, etc.
  47
  48         function miconf_dname_hook(level,path,file)
  49            return path..(file and ("/"..file) or "")
  50         end
  51
  52         function miconf_fname_hook(level,pattern,path,file,type)
  53            ofile,cnt = file:gsub(pattern,"")
  54            if ofile and cnt==1 and ofile:len()>0 then
  55               return path..(file and ("/"..file) or ""), path.."/"..ofile
  56            else
  57               return nil,nil
  58            end
  59         end
  60
  61 ##Example
  62
  63 **`$ cat sample.config`**
  64
  65         b = 200
  66         c = "Hello, world!"
  67         if a < 100 then
  68            d = {x=a, "boo"}
  69         else
  70            d = {x=10, "foo"}
  71         end
  72
  73         function square(x)
  74            return x*x
  75         end
  76
  77 **`$ cat file.template`**
  78
  79         text0
  80         text1,<<<c>>>,text2
  81         === if b > 100 then
  82         text3
  83         === end
  84         text4
  85         === for i = 1, a do
  86         text5,<<<square(i)>>>,text6,<<<d[1]>>>,text7
  87         === end
  88         text8
  89
  90 **`$ miconf -v -e 'a=5' -c sample.config sample.template sample`**
  91
  92 **`$ cat sample`**
  93
  94         text0
  95         text1,Hello, world!,text2
  96         text3
  97         text4
  98         text5,1,text6,boo,text7
  99         text5,4,text6,boo,text7
 100         text5,9,text6,boo,text7
 101         text5,16,text6,boo,text7
 102         text5,25,text6,boo,text7
 103         text8
 104