-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathgenerate_docs
118 lines (101 loc) · 6.91 KB
/
generate_docs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
cd "$(dirname "$(readlink -f "$(which "$0")")")"
CODE_FILES='vclod* extensions/* post*/* connections/* includes/*'
exclusions=$(grep -E '^\s*[A-Z_]+=' $CODE_FILES | grep -v vclod_op | sed 's/^[^:]*://;s/=/ /' | awk '{r=$1".*"$1; if($0 !~ r) print "-e"$1;}' | sort| uniq | paste -sd' ')
echo '# Configuration -- Enviornment Variables' >docs/Configuration.md
echo '# Dependencies -- Where What External Programs are Used' >docs/Dependencies.md
cat << EOF | tee -a docs/Dependencies.md >>docs/Configuration.md
## Scope
Name | Used by:
-----|----------
Global | the whole directory. Only Editable in the Global config file
Script | a single script
Connections | used in .sql and .dst as defaults
Includes | Used at the script level or inside the .sh extension [See more](/docs/sh.md)
Extensions | the given dot extensions
Post | log processing after the script has run
EOF
cat << EOF >>docs/Configuration.md
NOTE: Setting the variable in the config file must be of the form \`VAR_NAME=...\` otherwise it will not be exported. Enviornment Variables given on the command line will be overridden by config files unless the variable is defined in the form \`VAR_NAME=\${VAR_NAME:=value to set}\` (or left to the default).
## Recognized Variables
Here is an automated listing of all Enviornment Variables, their Scopes and Default Values. \`\$INPUT_DIR\` is the Local directory of the script.
Name | Scope | Defaults | Description
-----|-------|----------|------------
$( { grep -onE '\$\{[A-Z_]+:[?=-]' $CODE_FILES | grep -vw $exclusions | sed 's/[${:=?-]/ /g' | while read f n v ; do
f2="$(echo "$f" | sed -r 's#^([^.]+)([.].+)?/#\1|#;s/^vclod_do_dir$/Global|/;s/^includes.script$/Script|/;s/^vclod.*/Global|Script/')"
sed -nr "${n} s@^.*\{${v}:[?=-](([$][{][^{}]+}|[^{}]+)*)\}[^#]*#? *@$v |$f2 |\\1|@p" "$f"; done; cat << CONNS
$(find connections/* | awk -F'/' 'BEGIN {split("HOST/DB/USER/PASSWORD",vs)}
{for (v in vs) {
print "VCLOD_"vs[v]"|"$1"|"$2"||Base level default "tolower(vs[v]);
print "VCLOD_"toupper($2)"_"vs[v]"|"$1"|"$2"|$VCLOD_"vs[v]"|Default "tolower(vs[v])" for "$2" connections";
}}')
CONNS
} | sort | awk -F'|' '
function concat_ws(value, sep, new) {return (value=="") ? new : ((new=="") ? value : value sep new)}
function reset() {g=s=c=i=e=p=""}
function prt_l(name, list) {return (list=="") ? "" : concat_ws(name, ": ", list)}
function prt() {gsub(/[ \t]+$/, "", cur); print cur"|"concat_ws(concat_ws(concat_ws(g, ", ", s), ", ", concat_ws(prt_l("Post", p), ",", prt_l("Includes", i))), ", ", concat_ws(prt_l("Extensions",e), ", ", prt_l("Connections",c)))"|"v"|"d}
function set_nv() {gsub(/[ \t]+$/, "", $3); switch ($2) {
case "Global": g=$2; if($3=="Script" && $1 !~ /^CONFIG/) s=$3; break;
case "Script": s=$2; break;
case "connections": c=concat_ws(c," ",$3); break;
case "extensions": e=concat_ws(e," ",$3); break;
case "includes": i=concat_ws(i," ",$3); break;
case "post": p=concat_ws(p," ",$3); break; }}
BEGIN {cur=v=d="";reset()}
$1==cur {set_nv(); if (d!=$5) print "WARNING: inconsistent definitions for "cur >"/dev/stderr"}
$1!=cur {if(cur!=""&&d!~"PRIVATE")prt();cur=$1;reset();v=$4;d=$5;set_nv()}
END {if(d!~"PRIVATE")prt()}')
EOF
cat << EOF >>docs/Dependencies.md
Name | Scope | Note
-----|-------|-----$(sed -r 's/^([a-z]+)([=<>]+[0-9.]+)?\s*[#]?$/\1 /g;/^ *$/ d' DEPENDENCIES | sort | while read c n ; do printf '\n%s|' "$c" ; grep -El "^((#!)?[^#]*[^A-Za-z0-9])?$c([^A-Za-z0-9]|$)" $CODE_FILES | sed -r 's#^vclod_do_dir$#Global#;s#^includes/script$#Script#;s#([.][^/]+)?/# #' | sort | awk 'NR==1 {printf "%s", toupper(substr($1,1,1))substr($1,2);l_d=$1}
l_d!=$1 {printf "<br />%s", toupper(substr($1,1,1))substr($1,2)}
NF==2 && (NR==1 || l_d!=$1) {printf ":"}
NF==2 {printf " %s", $2}
{l_d=$1}'; printf '|%s' "$n" ; done)
EOF
cat << EOF >docs/Operation.md
# Operation -- Dot Extensions
## Location
Name | Description
-----|------------
ANY | Normal processing. takes stdin (or the contents of the file), does something, and leaves output for the next thing (or logging).
TERM | Ends the .extension chain by redirecting stdin somewhere else
PIPE | Pass Through: Must be in the middle of a .extension chain
WRAP | Runs another .extension tree as a child
FLOW | Controls the flow of the application, allowing for branches
## Option
Many extensions have the abilty to accept one and only one option in the .extension chain. This is signified as \`<base_filename>.<other_optional_extensions>.<extension>-<option>.<more_optional_extensions>\`. All other behavior modification is handled with Configuration Variables. Options allow 2 of the same extension to be present in the same .extension chain while exhibiting different behavior. Most often, the option value is a file name (due to the nature of the .extension chain, these filenames may not themselves have a .extension). If another file is accepted, the default for the option will be \`\$base_filename\`
## Extensions
Name | Location | Option Default | Description
-----|----------|----------------|------------
$(grep -oE '( |\$(\{ext_opt(:[?=-]([$][{][^{]+}|[/$0-9A-Za-z_-]+)*)?}|ext_opt)|#(ANY|TERM|PIPE|WRAP|FLOW|CMD) .*$)' extensions/* | sed -r 's|extensions/([^:]+):|\1 |;s/\$\{?ext_opt:?[?=-]?/eo /;s/}$//;s/#//' | uniq | awk '
function concat_ws(value, sep, new) {return (value=="") ? new : value sep new}
function tail() {ret=""; for (i=3; i<=NF; i++) ret=concat_ws(ret," ",$i); return ret}
function err(msg) {print "WARNING: "msg" for "cur >"/dev/stderr"}
function p() {if(cur!="") {if(l=="")err("missing location");if(d=="")err("missing description");if(e=="")e="Not Used";print cur"|"l"|"e"|"d;l="";e="";d="";}}
BEGIN {cur="";l="";e="";d=""}
$1!=cur {p();cur=$1}
$1==cur && $2=="eo" && e=="" {e=tail();if(e=="") e="Used, No Default"}
$1==cur && $2=="eo" && e!="Used, No Default" && e!=tail() && tail()!="" {err("inconsistent ext_opt default")}
$1==cur && $2~/^(ANY|TERM|PIPE|WRAP|FLOW)$/ {if(l!="" && l!=$2) err("inconsistent location");l=$2;d=concat_ws(d," ",tail())}
$1==cur && $2=="CMD" {d=concat_ws(d," ","[See more](/docs/"cur".md)")}
END {p()}')
EOF
for f in $(grep -l '^#CMD' extensions/*) ; do
cat << EOF > docs/"$(basename "$f")".md
# .$(basename "$f") Extension Details and Commands
$(grep '^#CMD' -A100 "$f" | sed -r '/^#TBL */{s/^#TBL *//p;s/[^|]+/--/g;};s/^#(CMD *)? //')
EOF
done
cat << EOF >> docs/sh.md
Collection | Description
-----------|------------
$(grep '^#' includes/* | sed -r '/# *NOTE[: ]/d;s@^[^/]+/([^:]+):# *(.*?)$@\1|\2@' | awk -F'|' '$1==cur {printf "<br />"$2} $1!=cur {if (cur) printf "\n"; printf $1"|"$2; cur=$1} END {printf "\n"}')
The available shell functions that are available are described below:
Collection | Function Name | Description
-----------|---------------|------------
$(grep -E '^(function [a-z_]+|[a-z_]+ *[(][)])[ {]+#' includes/* | sed -r 's@^[^/]+/([^:]+): *(function +)?([^ ({#]+)[ (){#]*@\1|\3|@;/PRIVATE/d')
EOF
grep -rn TODO * | sed -rn 's/^([^:]+):([0-9]+:)(.*[^ ])? *(#+) *TODO:? *(.*)$/\4|\1 Line \2\3|\5/p' | sort | sed -r 's/^#+[|]([^|]+)[|]/\n\1\n/' >TODO
#commit -m"$@"