[Summary view]

Differences Between: [Versions 39 and 310] [Versions 39 and 311] [Versions 39 and 400] [Versions 39 and 401] [Versions 39 and 402] [Versions 39 and 403]

   1  <?php
   2  
   3  // This file is part of Moodle - http://moodle.org/
   4  //
   5  // Moodle is free software: you can redistribute it and/or modify
   6  // it under the terms of the GNU General Public License as published by
   7  // the Free Software Foundation, either version 3 of the License, or
   8  // (at your option) any later version.
   9  //
  10  // Moodle is distributed in the hope that it will be useful,
  11  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  // GNU General Public License for more details.
  14  //
  15  // You should have received a copy of the GNU General Public License
  16  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  17  
  18  /**
  19   * Command line utility functions and classes
  20   *
  21   * @package    core
  22   * @subpackage cli
  23   * @copyright  2009 Petr Skoda (http://skodak.org)
  24   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  25   */
  26  
  27  // NOTE: no MOODLE_INTERNAL test here, sometimes we use this before requiring Moodle libs!
  28  
  29  /**
  30   * Write a text to the given stream
  31   *
  32   * @param string $text text to be written
  33   * @param resource $stream output stream to be written to, defaults to STDOUT
  34   */
  35  function cli_write($text, $stream=STDOUT) {
  36      fwrite($stream, $text);
  37  }
  38  
  39  /**
  40   * Write a text followed by an end of line symbol to the given stream
  41   *
  42   * @param string $text text to be written
  43   * @param resource $stream output stream to be written to, defaults to STDOUT
  44   */
  45  function cli_writeln($text, $stream=STDOUT) {
  46      cli_write($text.PHP_EOL, $stream);
  47  }
  48  
  49  /**
  50   * Get input from user
  51   * @param string $prompt text prompt, should include possible options
  52   * @param string $default default value when enter pressed
  53   * @param array $options list of allowed options, empty means any text
  54   * @param bool $casesensitive true if options are case sensitive
  55   * @return string entered text
  56   */
  57  function cli_input($prompt, $default='', array $options=null, $casesensitiveoptions=false) {
  58      cli_writeln($prompt);
  59      cli_write(': ');
  60      $input = fread(STDIN, 2048);
  61      $input = trim($input);
  62      if ($input === '') {
  63          $input = $default;
  64      }
  65      if ($options) {
  66          if (!$casesensitiveoptions) {
  67              $input = strtolower($input);
  68          }
  69          if (!in_array($input, $options)) {
  70              cli_writeln(get_string('cliincorrectvalueretry', 'admin'));
  71              return cli_input($prompt, $default, $options, $casesensitiveoptions);
  72          }
  73      }
  74      return $input;
  75  }
  76  
  77  /**
  78   * Returns cli script parameters.
  79   * @param array $longoptions array of --style options ex:('verbose'=>false)
  80   * @param array $shortmapping array describing mapping of short to long style options ex:('h'=>'help', 'v'=>'verbose')
  81   * @return array array of arrays, options, unrecognised as optionlongname=>value
  82   */
  83  function cli_get_params(array $longoptions, array $shortmapping=null) {
  84      $shortmapping = (array)$shortmapping;
  85      $options      = array();
  86      $unrecognized = array();
  87  
  88      if (empty($_SERVER['argv'])) {
  89          // bad luck, we can continue in interactive mode ;-)
  90          return array($options, $unrecognized);
  91      }
  92      $rawoptions = $_SERVER['argv'];
  93  
  94      //remove anything after '--', options can not be there
  95      if (($key = array_search('--', $rawoptions)) !== false) {
  96          $rawoptions = array_slice($rawoptions, 0, $key);
  97      }
  98  
  99      //remove script
 100      unset($rawoptions[0]);
 101      foreach ($rawoptions as $raw) {
 102          if (substr($raw, 0, 2) === '--') {
 103              $value = substr($raw, 2);
 104              $parts = explode('=', $value);
 105              if (count($parts) == 1) {
 106                  $key   = reset($parts);
 107                  $value = true;
 108              } else {
 109                  $key = array_shift($parts);
 110                  $value = implode('=', $parts);
 111              }
 112              if (array_key_exists($key, $longoptions)) {
 113                  $options[$key] = $value;
 114              } else {
 115                  $unrecognized[] = $raw;
 116              }
 117  
 118          } else if (substr($raw, 0, 1) === '-') {
 119              $value = substr($raw, 1);
 120              $parts = explode('=', $value);
 121              if (count($parts) == 1) {
 122                  $key   = reset($parts);
 123                  $value = true;
 124              } else {
 125                  $key = array_shift($parts);
 126                  $value = implode('=', $parts);
 127              }
 128              if (array_key_exists($key, $shortmapping)) {
 129                  $options[$shortmapping[$key]] = $value;
 130              } else {
 131                  $unrecognized[] = $raw;
 132              }
 133          } else {
 134              $unrecognized[] = $raw;
 135              continue;
 136          }
 137      }
 138      //apply defaults
 139      foreach ($longoptions as $key=>$default) {
 140          if (!array_key_exists($key, $options)) {
 141              $options[$key] = $default;
 142          }
 143      }
 144      // finished
 145      return array($options, $unrecognized);
 146  }
 147  
 148  /**
 149   * Print or return section separator string
 150   * @param bool $return false means print, true return as string
 151   * @return mixed void or string
 152   */
 153  function cli_separator($return=false) {
 154      $separator = str_repeat('-', 79).PHP_EOL;
 155      if ($return) {
 156          return $separator;
 157      } else {
 158          cli_write($separator);
 159      }
 160  }
 161  
 162  /**
 163   * Print or return section heading string
 164   * @param string $string text
 165   * @param bool $return false means print, true return as string
 166   * @return mixed void or string
 167   */
 168  function cli_heading($string, $return=false) {
 169      $string = "== $string ==".PHP_EOL;
 170      if ($return) {
 171          return $string;
 172      } else {
 173          cli_write($string);
 174      }
 175  }
 176  
 177  /**
 178   * Write error notification
 179   * @param $text
 180   * @return void
 181   */
 182  function cli_problem($text) {
 183      cli_writeln($text, STDERR);
 184  }
 185  
 186  /**
 187   * Write to standard error output and exit with the given code
 188   *
 189   * @param string $text
 190   * @param int $errorcode
 191   * @return void (does not return)
 192   */
 193  function cli_error($text, $errorcode=1) {
 194      cli_writeln($text.PHP_EOL, STDERR);
 195      die($errorcode);
 196  }
 197  
 198  /**
 199   * Print an ASCII version of the Moodle logo.
 200   *
 201   * @param int $padding left padding of the logo
 202   * @param bool $return should we print directly (false) or return the string (true)
 203   * @return mixed void or string
 204   */
 205  function cli_logo($padding=2, $return=false) {
 206  
 207      $lines = array(
 208          '                               .-..-.       ',
 209          ' _____                         | || |       ',
 210          '/____/-.---_  .---.  .---.  .-.| || | .---. ',
 211          '| |  _   _  |/  _  \\/  _  \\/  _  || |/  __ \\',
 212          '* | | | | | || |_| || |_| || |_| || || |___/',
 213          '  |_| |_| |_|\\_____/\\_____/\\_____||_|\\_____)',
 214      );
 215  
 216      $logo = '';
 217  
 218      foreach ($lines as $line) {
 219          $logo .= str_repeat(' ', $padding);
 220          $logo .= $line;
 221          $logo .= PHP_EOL;
 222      }
 223  
 224      if ($return) {
 225          return $logo;
 226      } else {
 227          cli_write($logo);
 228      }
 229  }
 230  
 231  /**
 232   * Substitute cursor, colour, and bell placeholders in a CLI output to ANSI escape characters when ANSI is available.
 233   *
 234   * @param string $message
 235   * @return string
 236   */
 237  function cli_ansi_format(string $message): string {
 238      global $CFG;
 239  
 240      $replacements = [
 241          "<newline>" => "\n",
 242          "<bell>" => "\007",
 243  
 244          // Cursor movement: https://www.tldp.org/HOWTO/Bash-Prompt-HOWTO/x361.html.
 245          "<cursor:save>"     => "\033[s",
 246          "<cursor:restore>"  => "\033[u",
 247          "<cursor:up>"       => "\033[1A",
 248          "<cursor:down>"     => "\033[1B",
 249          "<cursor:forward>"  => "\033[1C",
 250          "<cursor:back>"     => "\033[1D",
 251      ];
 252  
 253      $colours = [
 254          'normal'        => '0;0',
 255          'black'         => '0;30',
 256          'darkGray'      => '1;30',
 257          'red'           => '0;31',
 258          'lightRed'      => '1;31',
 259          'green'         => '0;32',
 260          'lightGreen'    => '1;32',
 261          'brown'         => '0;33',
 262          'yellow'        => '1;33',
 263          'lightYellow'   => '0;93',
 264          'blue'          => '0;34',
 265          'lightBlue'     => '1;34',
 266          'purple'        => '0;35',
 267          'lightPurple'   => '1;35',
 268          'cyan'          => '0;36',
 269          'lightCyan'     => '1;36',
 270          'lightGray'     => '0;37',
 271          'white'         => '1;37',
 272      ];
 273      $bgcolours = [
 274          'black'         => '40',
 275          'red'           => '41',
 276          'green'         => '42',
 277          'yellow'        => '43',
 278          'blue'          => '44',
 279          'magenta'       => '45',
 280          'cyan'          => '46',
 281          'white'         => '47',
 282      ];
 283  
 284      foreach ($colours as $colour => $code) {
 285          $replacements["<colour:{$colour}>"] = "\033[{$code}m";
 286      }
 287      foreach ($bgcolours as $colour => $code) {
 288          $replacements["<bgcolour:{$colour}>"] = "\033[{$code}m";
 289      }
 290  
 291      // Windows don't support ANSI code by default, but does if ANSICON is available.
 292      $isansicon = getenv('ANSICON');
 293      if (($CFG->ostype === 'WINDOWS') && empty($isansicon)) {
 294          return str_replace(array_keys($replacements), '', $message);
 295      }
 296  
 297      return str_replace(array_keys($replacements), array_values($replacements), $message);
 298  }