src/parset.pod

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