1<?php
2// This file is part of Moodle - http://moodle.org/
3//
4// Moodle is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// Moodle is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
16
17/**
18 * Language string based on David Mudrak langstring from local_amos.
19 *
20 * @package    tool_customlang
21 * @copyright  2020 Ferran Recio <ferran@moodle.com>
22 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23 */
24
25namespace tool_customlang\local\mlang;
26
27use moodle_exception;
28use stdclass;
29
30/**
31 * Class containing a lang string cleaned.
32 *
33 * @package    tool_customlang
34 * @copyright  2020 Ferran Recio <ferran@moodle.com>
35 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36 */
37
38/**
39 * Represents a single string
40 */
41class langstring {
42
43    /** @var string identifier */
44    public $id = null;
45
46    /** @var string */
47    public $text = '';
48
49    /** @var int the time stamp when this string was saved */
50    public $timemodified = null;
51
52    /** @var bool is deleted */
53    public $deleted = false;
54
55    /** @var stdclass extra information about the string */
56    public $extra = null;
57
58    /**
59     * Class constructor.
60     *
61     * @param string $id string identifier
62     * @param string $text string text
63     * @param int $timemodified
64     * @param int $deleted
65     * @param stdclass $extra
66     */
67    public function __construct(string $id, string $text = '', int $timemodified = null,
68            int $deleted = 0, stdclass $extra = null) {
69
70        if (is_null($timemodified)) {
71            $timemodified = time();
72        }
73        $this->id           = $id;
74        $this->text         = $text;
75        $this->timemodified = $timemodified;
76        $this->deleted      = $deleted;
77        $this->extra        = $extra;
78    }
79
80    /**
81     * Given a string text, returns it being formatted properly for storing in AMOS repository.
82     *
83     * Note: This method is taken directly from local_amos as it is highly tested and robust.
84     * The Moodle 1.x part is keep on puspose to make it easier the copy paste from both codes.
85     * This could change in the future when AMOS stop suporting the 1.x langstrings.
86     *
87     * We need to know for what branch the string should be prepared due to internal changes in
88     * format required by get_string()
89     * - for get_string() in Moodle 1.6 - 1.9 use $format == 1
90     * - for get_string() in Moodle 2.0 and higher use $format == 2
91     *
92     * Typical usages of this methods:
93     *  $t = langstring::fix_syntax($t);          // sanity new translations of 2.x strings
94     *  $t = langstring::fix_syntax($t, 1);       // sanity legacy 1.x strings
95     *  $t = langstring::fix_syntax($t, 2, 1);    // convert format of 1.x strings into 2.x
96     *
97     * Backward converting 2.x format into 1.x is not supported
98     *
99     * @param string $text string text to be fixed
100     * @param int $format target get_string() format version
101     * @param int $from which format version does the text come from, defaults to the same as $format
102     * @return string
103     */
104    public static function fix_syntax(string $text, int $format = 2, ?int $from = null): string {
105        if (is_null($from)) {
106            $from = $format;
107        }
108
109        // Common filter.
110        $clean = trim($text);
111        $search = [
112            // Remove \r if it is part of \r\n.
113            '/\r(?=\n)/',
114
115            // Control characters to be replaced with \n
116            // LINE TABULATION, FORM FEED, CARRIAGE RETURN, END OF TRANSMISSION BLOCK,
117            // END OF MEDIUM, SUBSTITUTE, BREAK PERMITTED HERE, NEXT LINE, START OF STRING,
118            // STRING TERMINATOR and Unicode character categorys Zl and Zp.
119            '/[\x{0B}-\r\x{17}\x{19}\x{1A}\x{82}\x{85}\x{98}\x{9C}\p{Zl}\p{Zp}]/u',
120
121            // Control characters to be removed
122            // NULL, ENQUIRY, ACKNOWLEDGE, BELL, SHIFT {OUT,IN}, DATA LINK ESCAPE,
123            // DEVICE CONTROL {ONE,TWO,THREE,FOUR}, NEGATIVE ACKNOWLEDGE, SYNCHRONOUS IDLE, ESCAPE,
124            // DELETE, PADDING CHARACTER, HIGH OCTET PRESET, NO BREAK HERE, INDEX,
125            // {START,END} OF SELECTED AREA, CHARACTER TABULATION {SET,WITH JUSTIFICATION},
126            // LINE TABULATION SET, PARTIAL LINE {FORWARD,BACKWARD}, REVERSE LINE FEED,
127            // SINGLE SHIFT {TWO,THREE}, DEVICE CONTROL STRING, PRIVATE USE {ONE,TWO},
128            // SET TRANSMIT STATE, MESSAGE WAITING, {START,END} OF GUARDED AREA,
129            // {SINGLE {GRAPHIC,} CHARACTER,CONTROL SEQUENCE} INTRODUCER, OPERATING SYSTEM COMMAND,
130            // PRIVACY MESSAGE, APPLICATION PROGRAM COMMAND, ZERO WIDTH {,NO-BREAK} SPACE,
131            // REPLACEMENT CHARACTER.
132            '/[\0\x{05}-\x{07}\x{0E}-\x{16}\x{1B}\x{7F}\x{80}\x{81}\x{83}\x{84}\x{86}-\x{93}\x{95}-\x{97}\x{99}-\x{9B}\x{9D}-\x{9F}\x{200B}\x{FEFF}\x{FFFD}]++/u',
133
134            // Remove trailing whitespace at the end of lines in a multiline string.
135            '/[ \t]+(?=\n)/',
136        ];
137        $replace = [
138            '',
139            "\n",
140            '',
141            '',
142        ];
143        $clean = preg_replace($search, $replace, $clean);
144
145        if (($format === 2) && ($from === 2)) {
146            // Sanity translations of 2.x strings.
147            $clean = preg_replace("/\n{3,}/", "\n\n\n", $clean); // Collapse runs of blank lines.
148
149        } else if (($format === 2) && ($from === 1)) {
150            // Convert 1.x string into 2.x format.
151            $clean = preg_replace("/\n{3,}/", "\n\n\n", $clean); // Collapse runs of blank lines.
152            $clean = preg_replace('/%+/', '%', $clean); // Collapse % characters.
153            $clean = str_replace('\$', '@@@___XXX_ESCAPED_DOLLAR__@@@', $clean); // Remember for later.
154            $clean = str_replace("\\", '', $clean); // Delete all slashes.
155            $clean = preg_replace('/(^|[^{])\$a\b(\->[a-zA-Z0-9_]+)?/', '\\1{$a\\2}', $clean); // Wrap placeholders.
156            $clean = str_replace('@@@___XXX_ESCAPED_DOLLAR__@@@', '$', $clean);
157            $clean = str_replace('&#36;', '$', $clean);
158
159        } else if (($format === 1) && ($from === 1)) {
160            // Sanity legacy 1.x strings.
161            $clean = preg_replace("/\n{3,}/", "\n\n", $clean); // Collapse runs of blank lines.
162            $clean = str_replace('\$', '@@@___XXX_ESCAPED_DOLLAR__@@@', $clean);
163            $clean = str_replace("\\", '', $clean); // Delete all slashes.
164            $clean = str_replace('$', '\$', $clean); // Escape all embedded variables.
165            // Unescape placeholders: only $a and $a->something are allowed. All other $variables are left escaped.
166            $clean = preg_replace('/\\\\\$a\b(\->[a-zA-Z0-9_]+)?/', '$a\\1', $clean); // Unescape placeholders.
167            $clean = str_replace('@@@___XXX_ESCAPED_DOLLAR__@@@', '\$', $clean);
168            $clean = str_replace('"', "\\\"", $clean); // Add slashes for ".
169            $clean = preg_replace('/%+/', '%', $clean); // Collapse % characters.
170            $clean = str_replace('%', '%%', $clean); // Duplicate %.
171
172        } else {
173            throw new moodle_exception('Unknown get_string() format version');
174        }
175        return $clean;
176    }
177}
178