aboutsummaryrefslogtreecommitdiff
path: root/man/man1/apf.1df
diff options
context:
space:
mode:
Diffstat (limited to 'man/man1/apf.1df')
-rw-r--r--man/man1/apf.1df65
1 files changed, 65 insertions, 0 deletions
diff --git a/man/man1/apf.1df b/man/man1/apf.1df
new file mode 100644
index 00000000..6f8804e0
--- /dev/null
+++ b/man/man1/apf.1df
@@ -0,0 +1,65 @@
+.TH APF 1df "August 2016" "Manual page for apf"
+.SH NAME
+.B apf
+\- add arguments to a command from a file
+.SH SYNOPSIS
+.B apf
+foorc
+foo --bar baz
+.SH DESCRIPTION
+Add newline-delimited arguments read from a file to a command's arguments
+(before any given ones) before running it. This is intended as a quick way of
+implementing *rc files for interactive shell calls to programs that don't
+support such files, without having to use broken environment variables like GNU
+grep(1)'s GREP_OPTIONS.
+.P
+This enables you to use arguments with shell metacharacters and spaces in them
+that you do not want expanded. The only exception is that you cannot have
+newlines in any of the arguments. This was done to keep POSIX sh(1)
+compatibility.
+.P
+For example, given this simple program in our $PATH, printargs:
+.P
+ $ cat /usr/bin/printargs
+ #!/bin/sh
+ printf '%s\\n' "$@"
+.P
+Which just prints its arguments:
+.P
+ $ printargs a b c
+ a
+ b
+ c
+.P
+We could do this:
+.P
+ $ printf '%s\\n' -f --flag --option '? foo bar *' > "$HOME"/.printargsrc
+.P
+ $ apf "$HOME"/.printargsrc printargs a b c
+ -f
+ --flag
+ --option
+ ? foo bar *
+ a
+ b
+ c
+.P
+We could then make a permanent wrapper script in two line:
+.P
+ $ cat >~/.local/bin/printargs
+ #!/bin/sh
+ exec apf "$HOME"/.printargsrc /usr/bin/printargs
+ ^D
+ $ chmod +x ~/.local/bin/printargs
+.P
+Or just a shell function, if it's needed interactively:
+.P
+ $ printargs() { apf "$HOME"/.printargsrc printargs "$@" ; }
+.P
+It's not considered an error if the file doesn't exist or is empty. If it's a
+directory or otherwise not byte-readable, an error will be printed to stderr,
+but execution of the called program will continue anyway. Blank lines or lines
+beginning with # are also ignored. Both leading and trailing whitespace is
+preserved.
+.SH AUTHOR
+Tom Ryder <tom@sanctum.geek.nz>