1 files changed, 327 insertions, 0 deletions
diff --git a/src/parset.pod b/src/parset.pod
new file mode 100644
index 0000000..ef381db
--- /dev/null
+++ b/src/parset.pod
@@ -0,0 +1,327 @@
+#!/usr/bin/perl -w
+
+# SPDX-FileCopyrightText: 2021-2024 Ole Tange, http://ole.tange.dk and Free Software and Foundation, Inc.
+# SPDX-License-Identifier: GFDL-1.3-or-later
+# SPDX-License-Identifier: CC-BY-SA-4.0
+
+=encoding utf8
+
+=head1 NAME
+
+parset - set shell variables in parallel
+
+
+=head1 SYNOPSIS
+
+B<parset> I<variablename> [options for GNU Parallel]
+
+B<env_parset> I<variablename> [options for GNU Parallel]
+
+=head1 DESCRIPTION
+
+B<parset> is a shell function that puts the output from GNU
+B<parallel> into shell variables.
+
+B<env_parset> is a shell function that puts the output from
+B<env_parallel> into shell variables.
+
+The B<parset> and B<env_parset> functions are defined as part of
+B<env_parallel>.
+
+If I<variablename> is a single variable name, this will be treated as
+the destination variable. If the variable is defined as an associative
+array (using B<typeset -A myassoc>), this will be used. Otherwise the
+variable will be made into a normal array.
+
+If I<variablename> contains multiple names separated by ',' or space,
+the names will be the destination variables. The number of names must
+be at least the number of jobs.
+
+
+=head1 OPTIONS
+
+Same as GNU B<parallel>, but they are put I<after> the destination
+variable.
+
+
+=head1 SUPPORTED SHELLS
+
+=head2 Bash/Zsh/Ksh/Mksh
+
+=head3 Examples
+
+Put output into B<myarray>:
+
+  parset myarray seq 3 ::: 4 5 6
+  echo "${myarray[1]}"
+
+Put output into vars B<$seq, $pwd, $ls>:
+
+  parset "seq pwd ls" ::: "seq 10" pwd ls
+  echo "$ls"
+
+Put output into vars B<$seq, $pwd, $ls>:
+
+  into_vars=(seq pwd ls)
+  parset "${into_vars[*]}" ::: "seq 10" pwd ls
+  echo "$ls"
+
+Put output into associative array B<myassoc> (not supported for mksh):
+
+  typeset -A myassoc
+  parset myassoc seq ::: 4 5 ::: 6 7
+  echo "${myassoc[4 7]}"
+
+The commands to run can be an array:
+
+  cmd=("echo first" "echo '<<joe  \"double  space\"  cartoon>>'" "pwd")
+  parset data ::: "${cmd[@]}"
+  echo "${data[1]}"
+  echo "${data[2]}"
+
+B<parset> can read from stdin (standard input) if it is a file:
+
+  parset res echo < parallel_input_file
+
+but B<parset> can I<not> be part of a pipe. In particular this means
+it cannot read from a pipe or write to a pipe:
+
+  seq 10 | parset res echo Does not work
+
+but must instead use a tempfile:
+
+  seq 10 > parallel_input
+  parset res echo :::: parallel_input
+  echo "${res[1]}"
+  echo "${res[9]}"
+
+or a FIFO:
+
+  mkfifo input_fifo
+  seq 30 > input_fifo &
+  parset res echo :::: input_fifo
+  echo "${res[1]}"
+  echo "${res[29]}"
+
+or Bash/Zsh/Ksh process substitution:
+
+  parset res echo :::: <(seq 100)
+  echo "${res[1]}"
+  echo "${res[99]}"
+
+
+=head3 Installation
+
+Put this in the relevant B<$HOME/.bashrc> or B<$HOME/.zshenv> or B<$HOME/.kshrc>:
+
+  . `which env_parallel.bash`
+  . `which env_parallel.zsh`
+  source `which env_parallel.ksh` 
+
+E.g. by doing:
+
+  echo '. `which env_parallel.bash`' >> $HOME/.bashrc
+  echo '. `which env_parallel.zsh`' >> $HOME/.zshenv
+  echo 'source `which env_parallel.ksh`' >> $HOME/.kshrc
+
+or by doing:
+
+  env_parallel --install
+
+
+=head2 ash/dash (FreeBSD's /bin/sh)
+
+=head3 Examples
+
+ash does not support arrays.
+
+Put output into vars B<$seq, $pwd, $ls>:
+
+  parset "seq pwd ls" ::: "seq 10" pwd ls
+  echo "$ls"
+
+B<parset> can read from stdin (standard input) if it is a file:
+
+  parset res1,res2,res3 echo < parallel_input_file
+
+but B<parset> can not be part of a pipe. In particular this means it
+cannot read from a pipe or write to a pipe:
+
+  seq 3 | parset res1,res2,res3 echo Does not work
+
+but must instead use a tempfile:
+
+  seq 3 > parallel_input
+  parset res1,res2,res3 echo :::: parallel_input
+  echo "$res1"
+  echo "$res2"
+  echo "$res3"
+
+or a FIFO:
+
+  mkfifo input_fifo
+  seq 3 > input_fifo &
+  parset res1,res2,res3 echo :::: input_fifo
+  echo "$res1"
+  echo "$res2"
+  echo "$res3"
+
+=head3 Installation
+
+Put the relevant one of these into B<$HOME/.profile>:
+
+  . `which env_parallel.sh`
+  . `which env_parallel.ash`
+  . `which env_parallel.dash`
+
+E.g. by doing:
+
+  echo '. `which env_parallel.ash`' >> $HOME/.bashrc
+
+or by doing:
+
+  env_parallel --install
+
+
+=head1 EXIT STATUS
+
+Same as GNU B<parallel>.
+
+
+=head1 AUTHOR
+
+When using GNU B<parallel> for a publication please cite:
+
+O. Tange (2011): GNU Parallel - The Command-Line Power Tool, ;login:
+The USENIX Magazine, February 2011:42-47.
+
+This helps funding further development; and it won't cost you a cent.
+If you pay 10000 EUR you should feel free to use GNU Parallel without citing.
+
+Copyright (C) 2007-10-18 Ole Tange, http://ole.tange.dk
+
+Copyright (C) 2008-2010 Ole Tange, http://ole.tange.dk
+
+Copyright (C) 2010-2024 Ole Tange, http://ole.tange.dk and Free
+Software Foundation, Inc.
+
+
+=head1 LICENSE
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3 of the License, or
+at your option any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+=head2 Documentation license I
+
+Permission is granted to copy, distribute and/or modify this
+documentation under the terms of the GNU Free Documentation License,
+Version 1.3 or any later version published by the Free Software
+Foundation; with no Invariant Sections, with no Front-Cover Texts, and
+with no Back-Cover Texts.  A copy of the license is included in the
+file LICENSES/GFDL-1.3-or-later.txt.
+
+=head2 Documentation license II
+
+You are free:
+
+=over 9
+
+=item B<to Share>
+
+to copy, distribute and transmit the work
+
+=item B<to Remix>
+
+to adapt the work
+
+=back
+
+Under the following conditions:
+
+=over 9
+
+=item B<Attribution>
+
+You must attribute the work in the manner specified by the author or
+licensor (but not in any way that suggests that they endorse you or
+your use of the work).
+
+=item B<Share Alike>
+
+If you alter, transform, or build upon this work, you may distribute
+the resulting work only under the same, similar or a compatible
+license.
+
+=back
+
+With the understanding that:
+
+=over 9
+
+=item B<Waiver>
+
+Any of the above conditions can be waived if you get permission from
+the copyright holder.
+
+=item B<Public Domain>
+
+Where the work or any of its elements is in the public domain under
+applicable law, that status is in no way affected by the license.
+
+=item B<Other Rights>
+
+In no way are any of the following rights affected by the license:
+
+=over 2
+
+=item *
+
+Your fair dealing or fair use rights, or other applicable
+copyright exceptions and limitations;
+
+=item *
+
+The author's moral rights;
+
+=item *
+
+Rights other persons may have either in the work itself or in
+how the work is used, such as publicity or privacy rights.
+
+=back
+
+=back
+
+=over 9
+
+=item B<Notice>
+
+For any reuse or distribution, you must make clear to others the
+license terms of this work.
+
+=back
+
+A copy of the full license is included in the file as
+LICENCES/CC-BY-SA-4.0.txt
+
+=head1 DEPENDENCIES
+
+B<parset> uses GNU B<parallel>.
+
+
+=head1 SEE ALSO
+
+B<parallel>(1), B<env_parallel>(1), B<bash>(1).
+
+
+=cut