From 9b9dd8a137787673dc4fb037a62668ea81a8571b Mon Sep 17 00:00:00 2001 From: Leah Neukirchen Date: Thu, 12 Oct 2017 15:05:07 +0200 Subject: Makefile: add pre-rendered man page --- Makefile | 3 ++ README | 166 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 169 insertions(+) create mode 100644 README diff --git a/Makefile b/Makefile index 4612074..8025ba0 100644 --- a/Makefile +++ b/Makefile @@ -20,4 +20,7 @@ install: FRC all install -m0755 $(ALL) $(DESTDIR)$(BINDIR) install -m0644 $(ALL:=.1) $(DESTDIR)$(MANDIR)/man1 +README: xe.1 + mandoc -Tutf8 $< | col -bx >$@ + FRC: diff --git a/README b/README new file mode 100644 index 0000000..117989f --- /dev/null +++ b/README @@ -0,0 +1,166 @@ +XE(1) General Commands Manual XE(1) + +NAME + xe – execute a command for every argument + +SYNOPSIS + xe [-0FLRnqv] [-p | -I replace-arg] [-N maxargs] [-j maxjobs] command ... + xe [flags ...] -f argfile command ... + xe [flags ...] -s shellscript + xe [flags ...] -a command ... -- args ... + xe [flags ...] -A argsep command ... argsep args ... + +DESCRIPTION + The xe utility constructs command lines from specified arguments, + combining some of the best features of xargs(1) and apply(1). + + xe means “execute for every ...”. + + xe supports different methods to specify arguments to commands: + + command ... + By default, arguments - separated by newlines - are read from the + standard input. The resulting command is constructed from the + command line parameters, replacing replace-arg (unless -p is + used, see below) with the read argument, and is executed with + execvp(3). + + In this mode, no shell is involved and replace-arg must appear as + a word on its own, i.e. ‘foo {} bar’ will work, but ‘foo{} bar’ + will not, where {} is the default value for replace-arg. + + If no argument is specified, the default is ‘printf %s\n’. + + -f argfile + Read arguments from argfile, instead of the standard input. + + This does not close the standard input for execution, it is + passed to the forked process. + + -s shellscript + In this mode, the single parameter shellscript is executed using + sh -c. In the script, the specified arguments can be accessed + using $1, $2, ... + + For example: + echo 'a\nb' | xe -N2 -s 'echo $2 $1' + + -a command ... -- args ... + In this mode, everything after -- is passed as args to command. + + -A argsep command ... argsep args ... + Same as -a, but the custom argument separator argsep is used to + distinguish between command and its args. + + The options are as follows: + + -0 Input filenames are separated by NUL bytes (instead of newlines, + which is the default) + + -F Fatal: stop and exit when a command execution fails. + + -L Run the resulting commands with line-buffered output; lines from + two jobs will not interleave. When used twice, or with -vv, also + prefix each line with the number of the job (see ENVIRONMENT) in + such a manner that the output can be piped to ‘sort -snk1’ to + group it. + + -R Return with status 122 when no arguments have been specified + (instead of 0, the default). xe never executes a command when no + arguments are specified. + + -n Dry run: don't run the resulting commands, just print them. + + -q Quiet mode: redirect standard output and standard error of + commands to /dev/null. + + -v Verbose: print commands to standard error before running them. + When used twice, also print job id and exit status for each + command. + + -p Enable make(1)-style percent rules. The first argument of + command ... is regarded as a pattern, see PERCENT RULES below. + Patterns without a slash are matched against the basenames only. + + Multiple runs of patterns and commands are separated by ‘+’. + Only the first matching percent rule is executed; in case no + pattern matches, no command is run. + + -I replace-arg + Replace first occurrence of replace-arg (default: {}) in the + resulting command with the argument(s). Pass an empty + replace-arg to disable the replace function. Contrary to + xargs(1) this will expand into multiple arguments when needed. + + -N maxargs + Pass up to maxargs arguments to each command (default: 1). + Using -N0 will pass as many arguments as possible. + + -j maxjobs + Run up to maxjobs processes concurrently. Using -j0 will run as + many processes as there are CPU cores running. If maxjobs ends + with an ‘x’, it is regarded as a multiplier of the number of + running CPU cores (rounded down, but using at least one core). + +PERCENT RULES + The percent rules of xe are similar to the globs of sh(1) or fnmatch(3): + ‘?’ matches a single character that is not ‘/’. ‘/’ matches one or + multiple ‘/’ in the string. ‘*’ matches zero or more characters, but + never ‘/’. ‘**’ matches zero or more characters, including ‘/’. Note + that all of these also match leading dots in file names. + + ‘{a,b,c}’ matches either a, b or c. ‘[abc]’ matches one of the + characters abc (but never ‘/’). ‘[!abc]’ matches all characters but abc. + Alternatively, ‘[^abc]’ can be used too. ‘[a-c]’ matches any character + in the range between a and c inclusive. In character ranges, characters + can be escaped using a backslash. + + In the pattern, a single occurrence of ‘%’ matches one or more + characters, and replaces the first occurrence of ‘%’ with the matched + string in the remaining arguments, which are then used as the command to + be executed. + +ENVIRONMENT + The environment variable ITER is passed to the child process and + incremented on each command execution. + +EXIT STATUS + xe follows the convention of GNU and OpenBSD xargs: + 0 on success + 123 if any invocation of the command exited with status 1 to 125. + 124 if the command exited with status 255 + 125 if the command was killed by a signal + 126 if the command cannot be run + 127 if the command was not found + 1 if some other error occurred + + Additionally, 122 is returned when -R was passed and the command was + never executed. + +EXAMPLES + Compress all .c files in the current directory, using all CPU cores: + xe -a -j0 gzip -- *.c + Remove all empty files, using lr(1): + lr -U -t 'size == 0' | xe -N0 rm + Convert .mp3 to .ogg, using all CPU cores: + xe -a -j0 -s 'ffmpeg -i "${1}" "${1%.mp3}.ogg"' -- *.mp3 + Same, using percent rules: + xe -a -j0 -p %.mp3 ffmpeg -i %.mp3 %.ogg -- *.mp3 + Similar, but hiding output of ffmpeg, instead showing spawned jobs: + xe -ap -j0 -vvq '%.{m4a,ogg,opus}' ffmpeg -y -i {} out/%.mp3 -- * + +SEE ALSO + apply(1), parallel(1), xapply(1), xargs(1) + +AUTHORS + Leah Neukirchen + +LICENSE + xe is in the public domain. + + To the extent possible under law, the creator of this work has waived all + copyright and related or neighboring rights to this work. + + http://creativecommons.org/publicdomain/zero/1.0/ + +Void Linux July 14, 2017 Void Linux -- cgit 1.4.1