MDL-21249 improved php docs and adding direct access prevention in dtl
[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 *
3b596dbf 21 * @package moodlecore
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
9d068cd6 27/**
3b596dbf 28 * Get input from user
1275723f 29 * @param string $prompt text prompt, should include possible options
3b596dbf 30 * @param string $default default value when enter pressed
31 * @param array $options list of allowed options, empty means any text
32 * @param bool $casesensitive true if options are case sensitive
33 * @return string entered text
9d068cd6 34 */
3b596dbf 35function cli_input($prompt, $default='', array $options=null, $casesensitiveoptions=false) {
36 echo $prompt;
37 echo "\n: ";
38 $input = fread(STDIN, 2048);
39 $input = trim($input);
40 if ($input === '') {
41 $input = $default;
9d068cd6 42 }
3b596dbf 43 if ($options) {
44 if (!$casesensitiveoptions) {
45 $input = strtolower($input);
9d068cd6 46 }
3b596dbf 47 if (!in_array($input, $options)) {
48 echo "Incorrect value, please retry.\n"; // TODO: localize, mark as needed in install
49 return cli_input($prompt, $default, $options, $casesensitiveoptions);
9d068cd6 50 }
51 }
3b596dbf 52 return $input;
9d068cd6 53}
54
55/**
3b596dbf 56 * Returns cli script parameters.
57 * @param array $longoptions array of --style options ex:('verbose'=>false)
58 * @param array $shortmapping array describing mapping of short to long style options ex:('h'=>'help', 'v'=>'verbose')
59 * @return array array of arrays, options, unrecognised as optionlongname=>value
9d068cd6 60 */
3b596dbf 61function cli_get_params(array $longoptions, array $shortmapping=null) {
62 $shortmapping = (array)$shortmapping;
63 $options = array();
64 $unrecognized = array();
9d068cd6 65
3b596dbf 66 if (empty($_SERVER['argv'])) {
67 // bad luck, we can continue in interactive mode ;-)
68 return array($options, $unrecognized);
9d068cd6 69 }
3b596dbf 70 $rawoptions = $_SERVER['argv'];
9d068cd6 71
3b596dbf 72 //remove anything after '--', options can not be there
73 if (($key = array_search('--', $rawoptions)) !== false) {
74 $rawoptions = array_slice($rawoptions, 0, $key);
9d068cd6 75 }
9d068cd6 76
3b596dbf 77 //remove script
78 unset($rawoptions[0]);
79 foreach ($rawoptions as $raw) {
80 if (substr($raw, 0, 2) === '--') {
81 $value = substr($raw, 2);
82 $parts = explode('=', $value);
83 if (count($parts) == 1) {
84 $key = reset($parts);
85 $value = true;
86 } else {
87 $key = array_shift($parts);
88 $value = implode('=', $parts);
9d068cd6 89 }
3b596dbf 90 if (array_key_exists($key, $longoptions)) {
91 $options[$key] = $value;
92 } else {
93 $unrecognized[] = $raw;
9d068cd6 94 }
9d068cd6 95
3b596dbf 96 } else if (substr($raw, 0, 1) === '-') {
97 $value = substr($raw, 1);
98 $parts = explode('=', $value);
99 if (count($parts) == 1) {
100 $key = reset($parts);
101 $value = true;
102 } else {
103 $key = array_shift($parts);
104 $value = implode('=', $parts);
105 }
106 if (array_key_exists($key, $shortmapping)) {
107 $options[$shortmapping[$key]] = $value;
108 } else {
109 $unrecognized[] = $raw;
9d068cd6 110 }
111 } else {
3b596dbf 112 $unrecognized[] = $raw;
113 continue;
9d068cd6 114 }
115 }
3b596dbf 116 //apply defaults
117 foreach ($longoptions as $key=>$default) {
118 if (!array_key_exists($key, $options)) {
119 $options[$key] = $default;
9d068cd6 120 }
9d068cd6 121 }
3b596dbf 122 // finished
123 return array($options, $unrecognized);
9d068cd6 124}
125
c31d94e8 126/**
127 * Print or return section separator string
128 * @param bool $return false means print, true return as string
129 * @return mixed void or string
130 */
131function cli_separator($return=false) {
132 $separator = str_repeat('-', 79)."\n";
133 if ($return) {
134 return $separator;
135 } else {
136 echo $separator;
137 }
138}
139
140/**
141 * Print or return section heading string
142 * @param string $string text
143 * @param bool $return false means print, true return as string
144 * @return mixed void or string
145 */
146function cli_heading($string, $return=false) {
147 $string = "== $string ==\n";
148 if ($return) {
149 return $string;
150 } else {
151 echo $string;
152 }
153}
154
9d068cd6 155/**
3b596dbf 156 * Write error notification
157 * @param $text
158 * @return void
9d068cd6 159 */
3b596dbf 160function cli_problem($text) {
161 fwrite(STDERR, $text, "\n");
9d068cd6 162}
3b596dbf 163
9d068cd6 164/**
3b596dbf 165 * Write to standard out and error with exit in error.
9d068cd6 166 *
3b596dbf 167 * @param string $text
168 * @param int $errorcode
169 * @return void (does not return)
9d068cd6 170 */
3b596dbf 171function cli_error($text, $errorcode=1) {
172 fwrite(STDERR, $text);
173 fwrite(STDERR, "\n");
174 die($errorcode);
9d068cd6 175}