nuxfs: Added docs & shorthands for error testing.

Signed-off-by: Tony Tkacik <tonydamage@gmail.com>

inc/dsl/nuxfs.check.dsl

@@ -3,7 +3,7 @@
 link.entered() {
   nux.log debug  "Testing '$abs_path' as link"
   if test ! -h "$abs_path"; then
-    nuxfs.error "$rel_path" "is not symlink."
+    .error "is not symlink."
     return
   fi
   local REAL_LINK=$(readlink "$abs_path")
@@ -13,26 +13,26 @@ link.entered() {
     local cdir=$(dirname "$abs_path")
     MAT_TARGET=$(realpath "$cdir/$target")
     if test "$MAT_REAL" = "$MAT_TARGET"; then
-      nuxfs.warning "$rel_path" "is using different definition for target '$3'"
+      .warning "is using different definition for target '$3'"
     else
-      nuxfs.error "$rel_path" "links to $REAL_LINK instead of $target"
+      .error "links to $REAL_LINK instead of $target"
       return
     fi
   fi
   if test ! -e "$abs_path"; then
-    nuxfs.warning "$rel_path" "target '$NC_White$target$NC_No' does not exists."
+    .warning "target '$NC_White$target$NC_No' does not exists."
   fi
 }
 
 git.entered() {
   nux.log debug "Testing '$rel_path' as git repository"
   if test ! -e "$rel_path/.git"; then
-    nuxfs.error "$rel_path" "is not git repository"
+    .error "$rel_path" "is not git repository"
     return
   fi
   local remotes=$(grep "$origin" "$rel_path/.git/config" | wc -l)
   if [ $remotes -eq 0 ]; then
-    nuxfs.error "$rel_path" "Does not refer git remote '$origin'"
+    .error "$rel_path" "Does not refer git remote '$origin'"
     return;
   fi
 }

inc/dsl/nuxfs.dsl

@@ -1,12 +1,69 @@
 #/bin/sh
 
+## # NUXFS Domain Specific Language
+##
+## *nuxfs* command has its own DSL to describe rules and structure of filesystem
+## and content of files. It 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. When *nuxfs apply*
+## is executed in folder containing this file, it is equivalent of executing
+## following commands:
+##
+##    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
+##
+## If we manually remove *github/bats* directory and run *nuxfs check* afterwards
+## the *github/bats* directory will be reported as missing.
+##
+## If we execute *nuxfs apply*, only missing *github/bats* will be cloned.
+##
+## # Available Keywords
+
+##   dir <name>
+##        Block keyword which defines directory with specified *name*.
+##        All subsequent keywords represent nested items in these directory
+##        unless **enddir** keyword is encountered.
+##
 .block dir name
+
+##   link <name> <target>
+##        Defines a symbolik link with specified *name*, which points to
+##        specified target
+##
 .keyword link name target
+
+##   git <name> <origin>
+##      Defines an existence of folder with specified *name*, which
+##      is git repository clone of specified *origin*
+##
 .keyword git name origin
+
 .keyword origin
 .keyword name name
 .keyword template
-.keyword exists
+
+##   exists <name>
+##        Defines an existence of file with specified *name*.
+##        When *nuxfs check* is executed absence of this file would result
+##        into error report.
+##
+.keyword exists name
+
+##
 .keyword should-not-exists
 
 directory() {
@@ -17,6 +74,43 @@ sdir() {
   dir "$@"
   enddir
 }
+##
+## #Using custom keywords
+##
+## *nuxfs* allows for addition of custom directory specific keywords,
+## since it is based on *nuxdsl* library.
+##
+## FIXME: Describe how to add keywords
+##
+.info() {
+  nux.dsl.info "$rel_path" "$@"
+}
+
+.warning() {
+  nux.dsl.warning "$rel_path" "$@"
+}
+
+.error() {
+  nux.dsl.error "$rel_path" "$@"
+}
+
+.should.eq() {
+  local actual="$1"
+  local expected="$2"
+  shift;shift;
+  if [ "$actual" != "$expected" ]; then
+    .warning "$@"
+  fi
+}
+
+.must.eq() {
+  local actual="$1"
+  local expected="$2"
+  shift;shift;
+  if [ "$actual" != "$expected" ]; then
+    .error "$@"
+  fi
+}
 
 .allways.preprocess() {
   abs_path=$(realpath -Lms "$NUXFS_DEF_DIR/$path");
@@ -31,7 +125,7 @@ sdir() {
 
 .check.failed() {
   if [ -z "$NUXFS_IGNORE_MISSING" ]; then
-    nux.dsl.error "$rel_path" does not exists.
+    .error does not exists.
   fi
 }
 dir.entered() {