.. -*- coding: utf-8 -*- .. role:: sref(numref) .. role:: xref(numref) .. Copyright (C) 2019, Wolfgang Scherer, .. .. This file is part of Administration. .. .. Permission is granted to copy, distribute and/or modify this document .. under the terms of the GNU Free Documentation License, Version 1.3 .. or any later version published by the Free Software Foundation; .. with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. .. A copy of the license is included in the section entitled "GNU .. Free Documentation License". .. inline comments (with du_comment_role) .. role:: rem(comment) .. role:: html(raw) :format: html .. role:: shx(code) :language: sh .. rst-class:: narrow xmedium xlarge xhuge xultra ################################################## :rem:`|||:sec:|||`\ Shell Option Evaluation Loop ################################################## .. >>CODD See `the components of a doctoral dissertation and their order `_ .. >>CODD Dedication .. >>CODD Epigraph .. >>CODD Abstract .. compound:: A generalized option evaluation loop is implemented in snippet `sh_b.opt-loop`. This chapter describes the algorithm employed. .. \|:here:| .. >>CODD Introduction ================================================== :rem:`|||:sec:|||`\ Shell Commmand Grammar ================================================== `BNF`_ for simple scripts: :: command: command-name | command-name options | command-name arguments | command-name options arguments options : option | option options option: option-symbol | option-symbol argument `BNF`_ for script implementing a command shell: :: command-shell: command-shell-name | command-shell-name options | command-shell-name command | command-shell-name options command .. _`BNF`: https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form ================================================== :rem:`|||:sec:|||`\ Option Loop Activity Diagram ================================================== .. uml:: _static/sh_b.opt-loop_act.puml ================================================== :rem:`|||:sec:|||`\ Option Loop Template ================================================== .. include:: _static/sh_b.opt-loop_act.snip ================================================== :rem:`|||:sec:|||`\ Snippet for defining an option ================================================== :file:`sh_b.opt-loop` contains shell comments with emacs lisp code for inserting an option definiton: .. code-block:: lisp ;; opt_short: o | opt_long: option | opt_arg: ARG => description: -o, --option ARG || ::fillme:: is considered blank, it does not have to be removed (let ((opt_short "::fillme::") (opt_long "::fillme::") (opt_arg "::fillme::")) (forward-line 1) (snip-insert "sh_b.opt-option" t t "sh" (concat " --key opt_short --value " opt_short " --key opt_long --value " opt_long " --key opt_arg --value " opt_arg))) The `::fillme::` tag is interpreted as if the parameter was blank. I.e., the `::fillme::` tags do not have to be deleted, only replaced as necessary. -------------------------------------------------- :rem:`||:sec:||`\ Example options -------------------------------------------------- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :rem:`|:sec:|`\ No parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following Emacs Lisp expression, which does not define any of :data:`opt_short`, :data:`opt_long` and :data:`opt_arg`, .. code-block:: lisp (progn (forward-line 1) (snip-insert "sh_b.opt-option" t t "sh")) results in the following snippet shell command and output: .. code-block:: sh >>>snc --mode 'sh' --key 'filename' --value 'sh_b.opt-option' --process --replace '/home/ws/snippets/sh_b.opt-option' # opt_=0 ) # opt_=1;; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :rem:`|:sec:|`\ All parameters = ::fillme:\: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following Emacs Lisp expression, which defines :data:`opt_short` as `::fillme::`, :data:`opt_long` as `::fillme::` and :data:`opt_arg` as `::fillme::`, .. code-block:: lisp (let ((opt_short "::fillme::") (opt_long "::fillme::") (opt_arg "::fillme::")) ;; ... ) results in the following snippet shell command and output: .. code-block:: sh >>>snc --mode 'sh' --key 'filename' --value 'sh_b.opt-option' --key opt_short --value ::fillme:: --key opt_long --value ::fillme:: --key opt_arg --value ::fillme:: --process --replace '/home/ws/snippets/sh_b.opt-option' # opt_=0 ) # opt_=1;; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :rem:`|:sec:|`\ opt_short = q, opt_long = quiet-day ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following Emacs Lisp expression, which defines :data:`opt_short` as `q`, :data:`opt_long` as `quiet-day` and :data:`opt_arg` as `::fillme::`, .. code-block:: lisp (let ((opt_short "q") (opt_long "quiet-day") (opt_arg "::fillme::")) ;; ... ) results in the following snippet shell command and output: .. code-block:: sh >>>snc --mode 'sh' --key 'filename' --value 'sh_b.opt-option' --key opt_short --value q --key opt_long --value quiet-day --key opt_arg --value ::fillme:: --process --replace '/home/ws/snippets/sh_b.opt-option' # -q, --quiet-day opt_quiet_day=0 -q|--q*) # --quiet-day opt_quiet_day=1;; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :rem:`|:sec:|`\ opt_short = q, opt_arg = INT ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following Emacs Lisp expression, which defines :data:`opt_short` as `q`, :data:`opt_long` as `::fillme::` and :data:`opt_arg` as `INT`, .. code-block:: lisp (let ((opt_short "q") (opt_long "::fillme::") (opt_arg "INT")) ;; ... ) results in the following snippet shell command and output: .. code-block:: sh >>>snc --mode 'sh' --key 'filename' --value 'sh_b.opt-option' --key opt_short --value q --key opt_long --value ::fillme:: --key opt_arg --value INT --process --replace '/home/ws/snippets/sh_b.opt-option' # -q INT opt_q='' -q) # INT opt_q="${2-}" test x"${2+set}" = xset && shift;; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :rem:`|:sec:|`\ opt_short = q, opt_long = quiet-day, opt_arg = INT ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following Emacs Lisp expression, which defines :data:`opt_short` as `q`, :data:`opt_long` as `quiet-day` and :data:`opt_arg` as `INT`, .. code-block:: lisp (let ((opt_short "q") (opt_long "quiet-day") (opt_arg "INT")) ;; ... ) results in the following snippet shell command and output: .. code-block:: sh >>>snc --mode 'sh' --key 'filename' --value 'sh_b.opt-option' --key opt_short --value q --key opt_long --value quiet-day --key opt_arg --value INT --process --replace '/home/ws/snippets/sh_b.opt-option' # -q, --quiet-day INT opt_quiet_day='' -q|--q*) # --quiet-day INT opt_quiet_day="${2-}" test x"${2+set}" = xset && shift;; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :rem:`|:sec:|`\ opt_long = quiet-day, opt_arg = INT ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following Emacs Lisp expression, which defines :data:`opt_short` as `::fillme::`, :data:`opt_long` as `quiet-day` and :data:`opt_arg` as `INT`, .. code-block:: lisp (let ((opt_short "::fillme::") (opt_long "quiet-day") (opt_arg "INT")) ;; ... ) results in the following snippet shell command and output: .. code-block:: sh >>>snc --mode 'sh' --key 'filename' --value 'sh_b.opt-option' --key opt_short --value ::fillme:: --key opt_long --value quiet-day --key opt_arg --value INT --process --replace '/home/ws/snippets/sh_b.opt-option' # --quiet-day INT opt_quiet_day='' --q*) # --quiet-day INT opt_quiet_day="${2-}" test x"${2+set}" = xset && shift;; -------------------------------------------------- :rem:`||:sec:||`\ Option generator snippet -------------------------------------------------- .. include:: _static/sh_b.opt-option.snip .. >>CODD Chapter .. >>CODD Conclusion .. >>CODD Appendix A .. \|:here:| .. >>CODD Notes .. ================================================== .. :rem:`|||:sec:|||`\ Footnotes .. ================================================== :html:`
` .. \[#] .. include:: doc_defs.inc .. include:: doc_defs_combined.inc .. include:: abbrev_defs.inc .. .. \||<-snap->|| doc_standalone .. include:: doc/doc_defs_secret.inc .. \||<-snap->|| doc_standalone .. \||<-snap->|| not_doc_standalone .. include:: doc_defs_secret.inc .. \||<-snap->|| not_doc_standalone .. _`Wolfgang Scherer`: wolfgang.scherer@gmx.de