feat: add 'export-file' function

Author: abbotto

.gitignore

@@ -7,6 +7,7 @@
 !.gitignore
 !.nvmrc
 !.travis.yml
+!CHANGELOG.md
 !CONTRIBUTING.md
 !README.md
 !package.json

.travis.yml

@@ -19,6 +19,7 @@ before_install:
     - tar --xz -xvf shellcheck-"${scversion}".linux.x86_64.tar.xz
     - sudo cp shellcheck-"${scversion}"/shellcheck /usr/bin/
     - shellcheck --version
+    - export ALLOW_EXTERNAL_SOURCE='-x '
 
 env:
   - CXX=g++-4.8

CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+---
+
+## [1.0.0](https://github.com/abbotto/shell-api/releases/tag/v1.0.0) - 2018-09-17
+### Added
+- `changelog` file.
+- [export-file](doc/api.md#export-file) function.
+
+### Changed
+- Updated examples.
+- Improved testing.
+- Code refactoring.
+
+### Removed
+- `import` function.
+
+### Fixed
+- Ensure aliases are expanded.
+
+## [0.2.0](https://github.com/abbotto/shell-api/releases/tag/v0.2.0) - 2018-08-05
+### Added
+- Placeholder support for the [pipe-file](doc/api.md#pipe-file) function.
+
+## [0.1.1](https://github.com/abbotto/shell-api/releases/tag/v0.1.1) - 2018-08-03
+### Changed
+- Fixed a documentation typo.
+
+## [0.1.0](https://github.com/abbotto/shell-api/releases/tag/v0.1.0) - 2018-08-01
+### Added
+- Build tools.
+- Configuration files.
+- API functions.
+- Tests.
+
+---
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

README.md

@@ -16,7 +16,7 @@ All functions have been tested in `bash`, `dash`, `ksh`, and `zsh`.
 
 ### The API
 - [confirm](doc/api.md#confirm)
-- [import](doc/api.md#import)
+- [export-file](doc/api.md#export-file)
 - [join-file](doc/api.md#join-file)
 - [pipe-file](doc/api.md#pipe-file)
 - [print-text](doc/api.md#print-text)
@@ -35,9 +35,9 @@ All functions have been tested in `bash`, `dash`, `ksh`, and `zsh`.
 
 ### Install
 
-- Install this project as an `npm` module.
+- Install this project via `npm`.
 
-      npm i shell-api
+      npm i shell-api --save
 
 - Symlink the `shell` directory within a project.
 
@@ -55,7 +55,7 @@ All functions have been tested in `bash`, `dash`, `ksh`, and `zsh`.
     # Load the whole framework at once
     . "${SHELL_API_PATH}"/shell-api
 
-    import ./.env
+    export-file ./.env
     require <SCRIPT>
 
     ...
@@ -67,12 +67,12 @@ All functions have been tested in `bash`, `dash`, `ksh`, and `zsh`.
     SCRIPT_PATH=$(cd "$(dirname "${0}")"; pwd)
     SHELL_API_PATH="${SCRIPT_PATH}/../.shell"
 
-    # Load specific parts of the framework
+    # Selectively load parts of the framework
     . "${SHELL_API_PATH}"/strict-mode
-    . "${SHELL_API_PATH}"/import
+    . "${SHELL_API_PATH}"/export-file
     . "${SHELL_API_PATH}"/require
 
-    import ./.env
+    export-file ./.env
     require <SCRIPT>
 
     ...

doc/api.md

@@ -11,13 +11,17 @@
 
 ---
 
-## [import](#import)
+## [export-file](#export-file)
 
-- Fetch a `.env` file and export it's environment variables.
+- Safely export an environment variable file.
+  - Properly handles newlines, nested quotes, and embedded variables.
+  - Will not overwrite previously set variables in the current process unless the `--force` or `-f` flag is passed.
 
-      Usage: import <ENV>
+        Usage: export-file <PATH>
 
-[source code](../shell/import)
+               export-file -f <PATH>
+
+[source code](../shell/export-file)
 
 ---
 
@@ -111,6 +115,8 @@ Reference: [Wikipedia](https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit)
 
 - Force POSIX-compliant behaviour.
 - Disable brace expansion.
+- Prevent errors in a pipeline from being masked.
+- Expand aliases.
 - Exit if a command has a non-zero exit status.
 - Throws an error if an undefined variable is referenced.
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "shell-api",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "description": "A POSIX-compliant framework for shell scripts",
   "main": "shell/shell-api",
   "scripts": {

shell/common/expand-aliases

@@ -0,0 +1,10 @@
+#!/usr/bin/env sh
+
+# Internal helper function
+
+# Expand aliases in BASH
+CURRENT_SHELL=$(ps -p $$ -oargs=)
+
+if test "${CURRENT_SHELL#*bash}" != "$CURRENT_SHELL"; then
+    eval "shopt -s expand_aliases"
+fi

shell/confirm

@@ -6,7 +6,6 @@ confirm(){
     if [ -z "${1}" ]; then
         echo "confirm: arguments are missing"
         return 127
-
     else
         QUESTION="${1}"
         YES_CALLBACK="${2}"
@@ -24,10 +23,8 @@ confirm(){
         # Respond to input
         if echo "$response" | grep -iq "^y"; then
             "${YES_CALLBACK}"
-
         elif [ -n "${2}" ]; then
             "${NO_CALLBACK}"
-
         fi
 
     fi

shell/export-file

@@ -0,0 +1,45 @@
+#!/usr/bin/env sh
+
+# Usage: doc/api.md#export-file
+
+# Create an alias
+. ./shell/common/expand-aliases
+alias export-file="export_file"
+
+export_file(){
+    if [ -z "${1}" ]; then
+        printf '%s\n' "export-file: arguments are missing"
+        return 127
+    fi
+
+	PROCESS_ENV_FILE=''
+
+	# Use the '-f' or '--force'  flag to
+	# overwrite previously exported variables
+	if [ "$1" = "-f" ] || [ "$1" = "--force" ] ; then
+		shift $(( $# > 0 ? 1 : 0 ))
+	else
+		PROCESS_ENV_FILE=$(mktemp)
+	fi
+
+	INPUT_ENV_FILE="${1}"
+
+	if [ ! -f "${INPUT_ENV_FILE}" ]; then
+		printf '%s\n' "Required resource not found: '${INPUT_ENV_FILE}'"
+	else
+		# Cache existing exported vars in a file so they can be preserved
+		# Calling 'set' in POSIX mode returns a list of exported variables
+		if [ -n "${PROCESS_ENV_FILE}" ]; then set > "${PROCESS_ENV_FILE}"; fi
+
+		# Export the target variables
+		set -a
+			. "$INPUT_ENV_FILE"
+
+			# Restore previously exported variables that belong to the current process
+			if [ -n "${PROCESS_ENV_FILE}" ]; then . "${PROCESS_ENV_FILE}"; fi
+		set +a
+
+		# Cleanup
+		rm -rf "${PROCESS_ENV_FILE}"
+	fi
+}