From 089cb5ccce5ca1958cdce9a724e2f47e860c3f5f Mon Sep 17 00:00:00 2001 From: Tony Tkacik Date: Sun, 11 Jun 2017 17:23:55 +0200 Subject: [PATCH] shelldoc: Added micro markup support for shell comments. Added support for micro markup to ease reading and to highlight keywords and headings in documentation derived from shell comments. nuxfs and nux-runner takes advantage from this. Signed-off-by: Tony Tkacik --- bin/nux-runner | 21 ++++++++-------- bin/nuxfs | 59 ++++++++++++++++++++++++++++++++++++++------- inc/nux-base.inc.sh | 50 ++++++++++++++++++++++++++++++++++---- 3 files changed, 105 insertions(+), 25 deletions(-) diff --git a/bin/nux-runner b/bin/nux-runner index cb57c7e..20aeac5 100755 --- a/bin/nux-runner +++ b/bin/nux-runner @@ -16,33 +16,32 @@ readonly NUX_RUNNER=$NUX_RUNNER_BIN_DIR/nux-runner; nux.include nux-runner ## -## Tasks provided by 'nux-runner': +## Commands provided by 'nux-runner': -## debug - Runs specified task with debug messages enabled. +## debug Runs specified task with debug messages enabled. task.debug() { N_LOG_debug=1 nux-runner.run "$@" } -## trace - Runs specified task with debug & trace enabled. +## trace Runs specified task with debug & trace enabled. task.trace() { N_LOG_debug=1; N_LOG_trace=2; nux-runner.run "$@" } -## help - Shows this help +## help Shows this help task.help() { - echo Usage: $NUX_SCRIPTNAME [task] [options] + echo Usage: $NC_Bold$NUX_SCRIPTNAME ${NC_No}${NC_White}\${NC_No} [\] echo - grep "^\#\#\# " "$NUX_SCRIPT" | cut -d\# -f4- - echo - echo " Available Tasks: " - grep "^\#\# " "$NUX_SCRIPT" | cut -d\# -f3- - echo - grep "^\#\# " "$NUX_RUNNER" | cut -d\# -f3- + grep -E "^\#\#\#( |$)" "$NUX_SCRIPT" | cut -d\# -f4- | cut -d" " -f2- | nux.help.shelldoc echo + echo "Available Commands: " + nux.help.comment "$NUX_SCRIPT" + nux.help.comment "$NUX_RUNNER" + nux.exec.optional task.help.detailed } ## diff --git a/bin/nuxfs b/bin/nuxfs index 9538338..23c5dff 100755 --- a/bin/nuxfs +++ b/bin/nuxfs @@ -1,7 +1,31 @@ #!/usr/bin/env nux-runner -### Filesystem Layout manager +### # nuxfs - Filesystem layout manager ### +### *nuxfs* command uses file structure definition present in *.nuxfs* file +### to understand intented state of directory / filesystem of user. +### +### This definition is not only used to create filesystem hierarchy, checkout +### git repositories but also to verify state of filesystem afterwards. +### +### ## Example of .nuxfs file in home directory +### +### *dir* github +### *git* nux-env https://github.com/tonydamage/nux-env.git +### *git* bats https://github.com/sstephenson/bats.git +### *enddir* +### *link* .bashrc github/nux-env/bashrc +### +### This *.nuxfs* file describes simple home structure. If we execute +### **nuxfs apply** command, it will performs filesystem changes in order to +### recreate structure described in *.nuxfs* file. In case of example it is +### equivalent of executing: +### mkdir -p github +### git clone https://github.com/tonydamage/nux-env.git github/nux-env +### git clone https://github.com/sstephenson/bats.git +### ln -s github/nux-env/bashrc .bashrc +### + local WORKDIR=$(pwd) local TEMPLATE_DIR=$NUX_ENV_DIR/templates local SUFFIX=".nuxfs" @@ -13,7 +37,9 @@ nux.use nuxfs GIT_BIN=$(which git) -## check - Verifies that directory matches nuxfs specification +## check Verifies that directories and files matches the specification +## in *.nuxfs* definition +## task.check() { nuxfs.dsl.process "$@"; } @@ -22,12 +48,27 @@ task.describe() { nuxfs.dsl.process "$@"; } - -## apply - Creates missing files as described in nuxfs definition. +## apply Creates missing files as specified in *.nuxfs* definition. +## **DOES NOT MODIFY** existing files breaking specification. +## task.apply() { nuxfs.dsl.process "$@"; } +## fix Performs apply and tries to fix warnings and errors and files as +## specified in nuxfs definition. This operation **DOES MODIFY** +## existing files. +## +task.fix() { + nuxfs.dsl.process "$@"; +} + +## help.dsl Displays help for **nuxfs DSL language** +## +task.help.dsl() { + nux.help.comment "$NUX_INC_DIR/dsl/nuxfs.dsl" +} + nuxfs.dsl.process() { WORKDIR=$(pwd); TARGET=$1; @@ -59,7 +100,7 @@ nuxfs.dsl.process() { nux.log debug nuxfs definition: $NC_White$NUXFS_DEF$NC_No nux.log debug $NC_White"target directory:$Nc_No" nux.log debug " relative to def:" $NC_White$TARGET_RELATIVE$NC_No - nux.log debug " absoulte path: " $NC_White$TARGET_ABSOLUTE$NC_No + nux.log debug " absolute path: " $NC_White$TARGET_ABSOLUTE$NC_No if test -e "$NUXFS_DEF"; then # #NUXFS_TARGET_FOUND=0; @@ -73,7 +114,8 @@ nuxfs.dsl.process() { fi } -## init - Initializes a directory using template +## init Initializes a directory using template +## function task.init { if [ $# -eq 0 ]; then nux.log debug "No template specified. Creating empty $SUFFIX definition." @@ -104,9 +146,8 @@ function task.init { task.create } +## template - List available templates ## -## template - List available templates -# function task.template { nux.log debug $NUX_ENV_DIR nuxfs.template.list @@ -174,7 +215,7 @@ function nuxfs.dsl.capture.file { fi; } -## capture - Captures current directory to nuxfs syntax +## capture - Captures current directory to nuxfs syntax function task.capture { if [ $# -eq 0 ]; then nuxfs.dsl.capture.dir . diff --git a/inc/nux-base.inc.sh b/inc/nux-base.inc.sh index 1243a99..33c7679 100644 --- a/inc/nux-base.inc.sh +++ b/inc/nux-base.inc.sh @@ -2,12 +2,33 @@ readonly NUX_INC_DIR=$(dirname $(realpath ${BASH_SOURCE[0]})) readonly NUX_ENV_DIR=$(dirname $NUX_INC_DIR) -# Color defintions +# Color definitions -readonly NC_No='\033[0m' # No Color +readonly nc_bold=`tput setaf 0` +readonly nc_bg_bold=`tput setab 0` +readonly nc_black=`tput setab 0` +readonly nc_bg_black=`tput setab 0` +readonly nc_cyan=`tput setaf 6` +readonly nc_bg_cyan=`tput setab 6` +readonly nc_magenta=`tput setaf 5` +readonly nc_bg_magenta=`tput setab 5` +readonly nc_red=`tput setaf 1` +readonly nc_bg_red=`tput setab 1` +readonly nc_white=`tput setaf 7` +readonly nc_bg_white=`tput setab 7` +readonly nc_green=`tput setaf 2` +readonly nc_bg_green=`tput setab 2` +readonly nc_yellow=`tput setaf 3` +readonly nc_bg_yellow=`tput setab 3` +readonly nc_blue=`tput setaf 4` +readonly nc_bg_blue=`tput setab 4` +readonly nc_end=`tput sgr0` + +readonly NC_Bold=`tput bold` +readonly NC_No=`tput sgr0` # No Color readonly NC_Black='\033[0;30m' readonly NC_Green='\033[0;32m' -readonly NC_Red='\033[0;31m' +readonly NC_Red=$nc_bold$nc_red readonly NC_BrownOrange='\033[0;33m' readonly NC_Blue='\033[0;34m' readonly NC_Purple='\033[0;35m' @@ -16,11 +37,11 @@ readonly NC_LightGray='\033[0;37m' readonly NC_DarkGray='\033[1;30m' readonly NC_LightRed='\033[1;31m' readonly NC_LightGreen='\033[1;32m' -readonly NC_Yellow='\033[1;33m' +readonly NC_Yellow=$nc_yellow readonly NC_LightBlue='\033[1;34m' readonly NC_LightPurple='\033[1;35m' readonly NC_LightCyan='\033[1;36m' -readonly NC_White='\033[1;37m' +readonly NC_White=$nc_white # Color for message levels NC_info=$NC_LightGray @@ -86,3 +107,22 @@ function nux.exec.optional { function nux.dirty.urlencode { echo -n "$1" | sed "s/ /%20/g" } + +function nux.help.comment { + local source="$1" + grep -E "^\#\#( |$)" "$source" \ + | cut -d\# -f3- \ + | cut -d" " -f2- \ + | nux.help.shelldoc + +} + +function nux.help.shelldoc { + cat | sed -r \ + -e "s/^## ?(.*)/${NC_White}\1${NC_No}/gI" \ + -e "s/^# ?(.*)/${NC_Bold}\1${NC_No}/gI" \ + -e "s/^ ?[a-z0-9.-_]*/${NC_Bold}&${NC_No}/gI" \ + -e "s/\*\*([^*]*)\*\*/${NC_Bold}\1${NC_No}/gI" \ + -e "s/\*([^*]*)\*/${NC_White}\1${NC_No}/gI" \ + +}