prepare for adding info manual and auto-completion

Signed-off-by: Mattias Andrée <maandree@operamail.com>

2 files changed, 142 insertions, 0 deletions

diff --git a/doc/example b/doc/example
new file mode 100644
index 0000000..6212c06
--- /dev/null
+++ b/doc/example
@@ -0,0 +1,64 @@
+((value command ponysay)
+	(default (arg MESSAGE) (files -0) (suggest message) (desc 'Message spoken by the pony'))
+	
+	(multiple unargumented
+		((options -h --help)                      (complete --help)        (desc 'Show summary of options'))
+		((options -v --version)                   (complete --version)     (desc 'Show version of program'))
+		((options -c --compress)                  (complete --compress)    (desc 'Compress message'))
+		((options -l --list)                      (complete --list)        (desc 'List all MLP:FiM ponies'))
+		((options -L --altlist --symlist)         (complete --symlist)     (desc 'List all MLP:FiM ponies, with symlink mapping'))
+		((options +l ++list)                      (complete ++list)        (desc 'List all non-MLP:FiM ponies'))
+		((options +K ++altlist ++symlist)         (complete ++symlist)     (desc 'List all non-MLP:FiM ponies, with symlink mapping'))
+		((options -A --all)                       (complete --all)         (desc 'List all ponies'))
+		((options +A ++all --altall --symall)     (complete --symall)      (desc 'List all ponies, with symlink mapping'))
+		((options -b --bubblelist --balloonlist)  (complete --balloonlist) (desc 'List all balloon styles'))
+		((options -o --pony-only --ponyonly)      (complete --pony-only)   (desc 'Print just the pony'))
+		((options -X --256-colours --256colours --x-colours)               (desc 'Use xterm colours'))
+		((options -V --tty-colours --ttycolours --vt-colours)              (desc 'Use linux vt colours'))
+		((options -K --kms-colours --kmscolours)                           (desc 'Utilise kms support'))
+	)
+	
+	; in files, -0 mean to not accept files, you can use to before other arguments to disallow them,
+	;           -a means accept all files, -d → directory, -D → door, -f → regular or pipe, -l → symlink (allowed by default on all), -r → regular
+	(multiple argumented
+		((options -f --file --pony)       (complete --file --pony) (arg PONY)    (suggest pony-f)  (files -f *.pony)  (desc 'Specify the pony that should printed'))
+		((options +f ++file ++pony)       (complete ++file ++pony) (arg PONY)    (suggest pony+f)  (files -f *.pony)  (desc 'Specify the extrapony that should printed'))
+		((options -q --quote)             (complete --quote)       (arg PONY)    (suggest pony-q)  (files -f *.pony)  (desc 'Specify the pony that should quote herself'))
+		((options -b --bubble --balloon)  (complete --balloon)     (arg STYLE)   (suggest balloon) (files -f (case (ponysay *.say) (ponyhink *.think)))  (desc 'Specify message balloon style'))
+		((options -W --wrap)              (complete --wrap)        (arg COLUMN)  (suggest wrap)    (files -0)         (desc 'Specify wrapping column'))
+		((options +c --colour)            (complete --colour)      (arg ANSI-COLOUR)               (files -0)         (desc 'Specify colour of the balloon, balloon link and message'))
+		((options --colour-bubble --colour-balloon)                (arg ANSI-COLOUR)               (files -0)         (desc 'Specify colour of the balloon'))
+		((options --colour-link)                                   (arg ANSI-COLOUR)               (files -0)         (desc 'Specify colour of the balloon link'))
+		((options --colour-msg --colour-message)                   (arg ANSI-COLOUR)               (files -0)         (desc 'Specify colour of the message'))
+		((options --colour-pony)                                   (arg ANSI-COLOUR)               (files -0)         (desc 'Specify colour of the pony (if uncoloured)'))
+		((options --colour-wrap --colour-hyphen)                   (arg ANSI-COLOUR)               (files -0)         (desc 'Specify addition colour of wrapping hyphen'))
+	)
+	
+	; `bind` copies everything that is missing except `options` and `suggest`
+	(variadic (options --f --files --ponies) (bind -f) (desc 'Specify the ponies that may be printed'))
+	(variadic (options ++f ++files ++ponies) (bind +f) (desc 'Specify the extraponies that may be printed'))
+	(variadic (options --q --quotes)         (bind -q) (desc 'Specify the pony that may quote themself'))
+	
+	(suggestion message (verbatim MESSAGE)
+	)
+	(suggestion pony-f  (exec "'/usr/bin/ponysay'" --onelist)
+	                    (no-exec ls "'/usr/share/ponysay/ponies'" .pony)
+	)
+	(suggestion pony+f  (exec "'/usr/bin/ponysay'" ++onelist)
+		    	    (no-exec ls "'/usr/share/ponysay/extraponies'" .pony)
+	)
+	(suggestion pony-q  (exec "'/usr/bin/ponysay'" --quoters)
+		    	    (no-exec ls "'/usr/share/ponysay/ponies'" .pony)
+	)
+	(suggestion balloon (exec "'/usr/bin/ponysay'" --balloonlist)
+		    	    (no-exec ls "'/usr/share/ponysay/balloons'" (case (ponysay .say) (ponythink .think)))
+	)
+	(suggestion wrap    (verbatim none inherit 100 60)
+		    	    (calc (pipe (stty size)
+			    	  	(cut -d ' ' -f 2)
+				  ) - 10
+			    )
+	)
+	; in addition to `pipe`(|) to following are also possible `fullpipe`(|&) `cat`(;) `and`(&&) `or`(||)
+)
+
diff --git a/doc/syntax b/doc/syntax
new file mode 100644
index 0000000..ca44109
--- /dev/null
+++ b/doc/syntax
@@ -0,0 +1,78 @@
+auto-auto-complete ::= _ program _
+
+program ::= '(' _ value _ body ')'
+
+body ::= [{(multiple | default | unargumented | argumented | variadic | suggestion) _}]
+
+_value ::= __ name | _ value | _ case
+
+value ::= name | variable | case
+
+variable ::= '(' _ "value" __ name _ [{value _}] ')'
+
+case ::= '(' _ "case" {_ a_case} _ ')'
+
+a_case ::= '(' {_ value} _ ')'
+
+multiple ::= '(' _ "multiple" <keyword=_value> [{_ '(' _ <item=anything> _ ')'}] _ ')'
+         ==> [{'(' <keyword> ' ' <item>  ')'}]
+
+anything ::= [{_ value | _ '(' anything _ ')'}]
+
+default ::= '(' _ "default" (4-:_ ) _ ')'
+
+unargumented ::= '(' _ "unargumented" (3-:_ (options | complete | desc)) _ ')'
+
+argumented ::= '(' _ "argumented" (6-:_ (options | complete | arg | suggest | files | bind | desc)) _ ')'
+
+variadic ::= '(' _ "variadic" (6-:_ (options | complete | arg | suggest | files | bind | desc)) _ ')'
+
+options ::= '(' _ "options" _value [{_ value}] ')'
+
+complete ::= '(' _ "complete" _value [{_ value}] ')'
+
+arg ::= '(' _ "arg" _value ')'
+
+suggest ::= '(' _ "suggest" _value ')'
+
+files ::= '(' _ "files" _value [{_ value}] ')'
+::=  {"-0" | "-a" | "-d" | "-D" | "-f" | "-l" | "-r"} [{value}]
+
+bind ::= '(' _ "bind" _value ')'
+
+desc ::= '(' _ "desc" _value ')'
+
+suggestion ::= '(' _ "suggestion" _ value {_ a_suggestion} _ ')'
+
+a_suggestion ::= '(' _ (exec | noexec | ls | verbatim | calc) _ ')'
+
+exec ::= 'exec' (__ value | _ any_exec) [{_ value | _ any_exec}]
+
+noexec ::= ls | verbatim
+
+ls ::= 'ls' _value [_ value]
+
+verbatim ::= 'verbatim' _value [{_ value}]
+
+calc ::= 'calc' (__ value | _ any_exec) [{_ value | _ any_exec}]
+
+any_exec ::= '(' _ exec_type (__ value | _ any_exec) [{_ value | _ any_exec}] _ ')'
+
+exec_type ::= "exec" | "calc" | "pipe" | "fullpipe" | "cat" | "and" | "or"
+
+name ::= {letter | escape | squote | dquote}
+
+letter :: $any ^ ' ' ^ \t ^ \n ^ \r ^ \t ^ '\' ^ \' ^ \"
+
+escape ::= '\' $any
+
+squote ::= \' [{$any ^ '\' ^ \' | escape}] \'
+
+dquote ::= \" [{$any ^ '\' ^ \" | escape}] \"
+
+comment ::= ('#' | ';') [{$any}] \z
+
+__ ::= {' ' | \t | \n | \r | \f | comment}
+
+_ ::= [__]
+