lib/clilib.php

   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 }