src/parset.pod

   1 #!/usr/bin/perl -w
   2
   3 # SPDX-FileCopyrightText: 2021 Ole Tange, http://ole.tange.dk and Free Software and Foundation, Inc.
   4 # SPDX-License-Identifier: GFDL-1.3-or-later
   5 # SPDX-License-Identifier: CC-BY-SA-4.0
   6
   7 =encoding utf8
   8
   9 =head1 NAME
  10
  11 parset - set shell variables in parallel
  12
  13
  14 =head1 SYNOPSIS
  15
  16 B<parset> I<variablename> [options for GNU Parallel]
  17
  18 B<env_parset> I<variablename> [options for GNU Parallel]
  19
  20 =head1 DESCRIPTION
  21
  22 B<parset> is a shell function that puts the output from GNU
  23 B<parallel> into shell variables.
  24
  25 B<env_parset> is a shell function that puts the output from
  26 B<env_parallel> into shell variables.
  27
  28 The B<parset> and B<env_parset> functions are defined as part of
  29 B<env_parallel>.
  30
  31 If I<variablename> is a single variable name, this will be treated as
  32 the destination variable and made into an array.
  33
  34 If I<variablename> contains multiple names separated by ',' or space,
  35 the names will be the destination variables. The number of names must
  36 be at least the number of jobs - otherwise some tmp files will not be
  37 cleaned up.
  38
  39
  40 =head1 OPTIONS
  41
  42 Same as GNU B<parallel>, but they are put I<after> the destination
  43 variable.
  44
  45
  46 =head1 SUPPORTED SHELLS
  47
  48 =head2 Bash/Zsh/Ksh/Mksh
  49
  50 =head3 Examples
  51
  52 Put output into B<myarray>:
  53
  54   parset myarray seq 3 ::: 4 5 6
  55   echo "${myarray[1]}"
  56
  57 Put output into vars B<$seq, $pwd, $ls>:
  58
  59   parset "seq pwd ls" ::: "seq 10" pwd ls
  60   echo "$ls"
  61
  62 Put output into vars B<$seq, $pwd, $ls>:
  63
  64   into_vars=(seq pwd ls)
  65   parset "${into_vars[*]}" ::: "seq 10" pwd ls
  66   echo "$ls"
  67
  68 The commands to run can be an array:
  69
  70   cmd=("echo first" "echo '<<joe  \"double  space\"  cartoon>>'" "pwd")
  71   parset data ::: "${cmd[@]}"
  72   echo "${data[1]}"
  73   echo "${data[2]}"
  74
  75 B<parset> can read from stdin (standard input) if it is a file:
  76
  77   parset res echo < parallel_input_file
  78
  79 but B<parset> can not be part of a pipe. In particular this means it
  80 cannot read from a pipe or write to a pipe:
  81
  82   seq 10 | parset res echo Does not work
  83
  84 but must instead use a tempfile:
  85
  86   seq 10 > parallel_input
  87   parset res echo :::: parallel_input
  88   echo "${res[1]}"
  89   echo "${res[9]}"
  90
  91 or a FIFO:
  92
  93   mkfifo input_fifo
  94   seq 30 > input_fifo &
  95   parset res echo :::: input_fifo
  96   echo "${res[1]}"
  97   echo "${res[29]}"
  98
  99 or Bash/Zsh/Ksh process substitution:
 100
 101   parset res echo :::: <(seq 100)
 102   echo "${res[1]}"
 103   echo "${res[99]}"
 104
 105 Put output into an associative array (Bash only):
 106
 107   input=("value  A" "value  B")
 108   parset res echo This is ::: "${input[@]}"
 109
 110   # Zip the input and res arrays to a single associative array
 111   declare -A myassoc
 112   for ((i=0; $i<${#input[@]}; i++)); do
 113     myassoc[${input[i]}]=${res[i]}
 114   done
 115   echo "${myassoc["value  A"]}"
 116
 117 =head3 Installation
 118
 119 Put this in the relevant B<$HOME/.bashrc> or B<$HOME/.zshenv> or B<$HOME/.kshrc>:
 120
 121   . `which env_parallel.bash`
 122   . `which env_parallel.zsh`
 123   source `which env_parallel.ksh`
 124
 125 E.g. by doing:
 126
 127   echo '. `which env_parallel.bash`' >> $HOME/.bashrc
 128   echo '. `which env_parallel.zsh`' >> $HOME/.zshenv
 129   echo 'source `which env_parallel.ksh`' >> $HOME/.kshrc
 130
 131 or by doing:
 132
 133   env_parallel --install
 134
 135
 136 =head2 ash/dash (FreeBSD's /bin/sh)
 137
 138 =head3 Examples
 139
 140 ash does not support arrays.
 141
 142 Put output into vars B<$seq, $pwd, $ls>:
 143
 144   parset "seq pwd ls" ::: "seq 10" pwd ls
 145   echo "$ls"
 146
 147 B<parset> can read from stdin (standard input) if it is a file:
 148
 149   parset res1,res2,res3 echo < parallel_input_file
 150
 151 but B<parset> can not be part of a pipe. In particular this means it
 152 cannot read from a pipe or write to a pipe:
 153
 154   seq 3 | parset res1,res2,res3 echo Does not work
 155
 156 but must instead use a tempfile:
 157
 158   seq 3 > parallel_input
 159   parset res1,res2,res3 echo :::: parallel_input
 160   echo "$res1"
 161   echo "$res2"
 162   echo "$res3"
 163
 164 or a FIFO:
 165
 166   mkfifo input_fifo
 167   seq 3 > input_fifo &
 168   parset res1,res2,res3 echo :::: input_fifo
 169   echo "$res1"
 170   echo "$res2"
 171   echo "$res3"
 172
 173 =head3 Installation
 174
 175 Put the relevant one of these into B<$HOME/.profile>:
 176
 177   . `which env_parallel.sh`
 178   . `which env_parallel.ash`
 179   . `which env_parallel.dash`
 180
 181 E.g. by doing:
 182
 183   echo '. `which env_parallel.ash`' >> $HOME/.bashrc
 184
 185 or by doing:
 186
 187   env_parallel --install
 188
 189
 190 =head1 EXIT STATUS
 191
 192 Same as GNU B<parallel>.
 193
 194
 195 =head1 AUTHOR
 196
 197 When using GNU B<parallel> for a publication please cite:
 198
 199 O. Tange (2011): GNU Parallel - The Command-Line Power Tool, ;login:
 200 The USENIX Magazine, February 2011:42-47.
 201
 202 This helps funding further development; and it won't cost you a cent.
 203 If you pay 10000 EUR you should feel free to use GNU Parallel without citing.
 204
 205 Copyright (C) 2007-10-18 Ole Tange, http://ole.tange.dk
 206
 207 Copyright (C) 2008-2010 Ole Tange, http://ole.tange.dk
 208
 209 Copyright (C) 2010-2021 Ole Tange, http://ole.tange.dk and Free
 210 Software Foundation, Inc.
 211
 212
 213 =head1 LICENSE
 214
 215 This program is free software; you can redistribute it and/or modify
 216 it under the terms of the GNU General Public License as published by
 217 the Free Software Foundation; either version 3 of the License, or
 218 at your option any later version.
 219
 220 This program is distributed in the hope that it will be useful,
 221 but WITHOUT ANY WARRANTY; without even the implied warranty of
 222 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 223 GNU General Public License for more details.
 224
 225 You should have received a copy of the GNU General Public License
 226 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 227
 228 =head2 Documentation license I
 229
 230 Permission is granted to copy, distribute and/or modify this
 231 documentation under the terms of the GNU Free Documentation License,
 232 Version 1.3 or any later version published by the Free Software
 233 Foundation; with no Invariant Sections, with no Front-Cover Texts, and
 234 with no Back-Cover Texts.  A copy of the license is included in the
 235 file LICENSES/GFDL-1.3-or-later.txt.
 236
 237 =head2 Documentation license II
 238
 239 You are free:
 240
 241 =over 9
 242
 243 =item B<to Share>
 244
 245 to copy, distribute and transmit the work
 246
 247 =item B<to Remix>
 248
 249 to adapt the work
 250
 251 =back
 252
 253 Under the following conditions:
 254
 255 =over 9
 256
 257 =item B<Attribution>
 258
 259 You must attribute the work in the manner specified by the author or
 260 licensor (but not in any way that suggests that they endorse you or
 261 your use of the work).
 262
 263 =item B<Share Alike>
 264
 265 If you alter, transform, or build upon this work, you may distribute
 266 the resulting work only under the same, similar or a compatible
 267 license.
 268
 269 =back
 270
 271 With the understanding that:
 272
 273 =over 9
 274
 275 =item B<Waiver>
 276
 277 Any of the above conditions can be waived if you get permission from
 278 the copyright holder.
 279
 280 =item B<Public Domain>
 281
 282 Where the work or any of its elements is in the public domain under
 283 applicable law, that status is in no way affected by the license.
 284
 285 =item B<Other Rights>
 286
 287 In no way are any of the following rights affected by the license:
 288
 289 =over 2
 290
 291 =item *
 292
 293 Your fair dealing or fair use rights, or other applicable
 294 copyright exceptions and limitations;
 295
 296 =item *
 297
 298 The author's moral rights;
 299
 300 =item *
 301
 302 Rights other persons may have either in the work itself or in
 303 how the work is used, such as publicity or privacy rights.
 304
 305 =back
 306
 307 =back
 308
 309 =over 9
 310
 311 =item B<Notice>
 312
 313 For any reuse or distribution, you must make clear to others the
 314 license terms of this work.
 315
 316 =back
 317
 318 A copy of the full license is included in the file as
 319 LICENCES/CC-BY-SA-4.0.txt
 320
 321 =head1 DEPENDENCIES
 322
 323 B<parset> uses GNU B<parallel>.
 324
 325
 326 =head1 SEE ALSO
 327
 328 B<parallel>(1), B<env_parallel>(1), B<bash>(1).
 329
 330
 331 =cut