weekly release 3.8dev
[moodle.git] / lib / clilib.php
CommitLineData
5d995668 1<?php
3b596dbf 2
3// This file is part of Moodle - http://moodle.org/
4//
5d995668 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.
3b596dbf 14//
5d995668 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
9d068cd6 18/**
3b596dbf 19 * Command line utility functions and classes
9d068cd6 20 *
78bfb562 21 * @package core
3b596dbf 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
9d068cd6 25 */
9d068cd6 26
3604563c 27// NOTE: no MOODLE_INTERNAL test here, sometimes we use this before requiring Moodle libs!
78bfb562 28
028bbc5b
DM
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 */
35function 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 */
45function cli_writeln($text, $stream=STDOUT) {
46 cli_write($text.PHP_EOL, $stream);
47}
48
9d068cd6 49/**
3b596dbf 50 * Get input from user
1275723f 51 * @param string $prompt text prompt, should include possible options
3b596dbf 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
9d068cd6 56 */
3b596dbf 57function cli_input($prompt, $default='', array $options=null, $casesensitiveoptions=false) {
028bbc5b
DM
58 cli_writeln($prompt);
59 cli_write(': ');
3b596dbf 60 $input = fread(STDIN, 2048);
61 $input = trim($input);
62 if ($input === '') {
63 $input = $default;
9d068cd6 64 }
3b596dbf 65 if ($options) {
66 if (!$casesensitiveoptions) {
67 $input = strtolower($input);
9d068cd6 68 }
3b596dbf 69 if (!in_array($input, $options)) {
c0e8a8a5 70 cli_writeln(get_string('cliincorrectvalueretry', 'admin'));
3b596dbf 71 return cli_input($prompt, $default, $options, $casesensitiveoptions);
9d068cd6 72 }
73 }
3b596dbf 74 return $input;
9d068cd6 75}
76
77/**
3b596dbf 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
9d068cd6 82 */
3b596dbf 83function cli_get_params(array $longoptions, array $shortmapping=null) {
84 $shortmapping = (array)$shortmapping;
85 $options = array();
86 $unrecognized = array();
9d068cd6 87
3b596dbf 88 if (empty($_SERVER['argv'])) {
89 // bad luck, we can continue in interactive mode ;-)
90 return array($options, $unrecognized);
9d068cd6 91 }
3b596dbf 92 $rawoptions = $_SERVER['argv'];
9d068cd6 93
3b596dbf 94 //remove anything after '--', options can not be there
95 if (($key = array_search('--', $rawoptions)) !== false) {
96 $rawoptions = array_slice($rawoptions, 0, $key);
9d068cd6 97 }
9d068cd6 98
3b596dbf 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);
9d068cd6 111 }
3b596dbf 112 if (array_key_exists($key, $longoptions)) {
113 $options[$key] = $value;
114 } else {
115 $unrecognized[] = $raw;
9d068cd6 116 }
9d068cd6 117
3b596dbf 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;
9d068cd6 132 }
133 } else {
3b596dbf 134 $unrecognized[] = $raw;
135 continue;
9d068cd6 136 }
137 }
3b596dbf 138 //apply defaults
139 foreach ($longoptions as $key=>$default) {
140 if (!array_key_exists($key, $options)) {
141 $options[$key] = $default;
9d068cd6 142 }
9d068cd6 143 }
3b596dbf 144 // finished
145 return array($options, $unrecognized);
9d068cd6 146}
147
c31d94e8 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 */
153function cli_separator($return=false) {
028bbc5b 154 $separator = str_repeat('-', 79).PHP_EOL;
c31d94e8 155 if ($return) {
156 return $separator;
157 } else {
028bbc5b 158 cli_write($separator);
c31d94e8 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 */
168function cli_heading($string, $return=false) {
028bbc5b 169 $string = "== $string ==".PHP_EOL;
c31d94e8 170 if ($return) {
171 return $string;
172 } else {
028bbc5b 173 cli_write($string);
c31d94e8 174 }
175}
176
9d068cd6 177/**
3b596dbf 178 * Write error notification
179 * @param $text
180 * @return void
9d068cd6 181 */
3b596dbf 182function cli_problem($text) {
028bbc5b 183 cli_writeln($text, STDERR);
9d068cd6 184}
3b596dbf 185
9d068cd6 186/**
028bbc5b 187 * Write to standard error output and exit with the given code
9d068cd6 188 *
3b596dbf 189 * @param string $text
190 * @param int $errorcode
191 * @return void (does not return)
9d068cd6 192 */
3b596dbf 193function cli_error($text, $errorcode=1) {
028bbc5b 194 cli_writeln($text.PHP_EOL, STDERR);
3b596dbf 195 die($errorcode);
9d068cd6 196}
08e7f97e 197
85f8fe5e
DM
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 */
205function 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 {
028bbc5b 227 cli_write($logo);
85f8fe5e
DM
228 }
229}