/**
* Cible la partie de la chaîne de caractères commençant à l'occurrence $mStart et terminant à $mEnd.<br/>
* Toutes les méthodes appelées par la suite ne s'appliqueront que sur la partie du texte qui a été ciblée par cette méthode.
* Même la méthode \Aouka\Text\Manipulator::get() !<br/>Après avoir ciblé une partie du texte et lui avoir appliqué des transformations,
* il est possible de revenir à l'intégralité du texte d'origine tout en conservant le résultat des modifications
* avec la méthode \Aouka\Text\Manipulator::end().
*
* <p>
* Exemples d'utilisation :<br/>
* Ciblage de la partie du texte située :
* <ul>
* <li>- jusqu'à la fin de la 3ème phrase (incluse) ->focus(NULL, array(3, \Aouka\Text\InterfaceText::SENTENCE).</li>
* <li>- avant le début de la 3ème phrase (exclue) ->focus(NULL, array(3, \Aouka\Text\Regex::sentence(), FALSE).</li>
* <li>- entre le 15ème mot (exclu) et le dernier mot "toto" (inclus) ->focus(array(15, \Aouka\Text\Regex::word(), FALSE), array(-1, "`(toto)`")).</li>
* <li>- après la 3ème lettre "a" (exclue) ->focus(array(3, \Aouka\Text\Regex::create("`(a)`"), FALSE), NULL).</li>
* <ul>
* </p>
*
* @param array|null $mStart Si $mStart vaut NULL, le ciblage commence à partir du début de la chaîne.<br/>
* Si $mStart est un tableau, il doit contenir entre 2 et 3 éléments : <br/>
* <ul>
* <li>
* - Le premier de ces éléments est un nombre entier qui détermine la position n de l'ancre à partir de
* laquelle débute le ciblage. Si ce nombre est positif le ciblage commencera à la énième ancre à partir
* du début de la chaîne ; s'il est négatif, le ciblage débutera à la énième ancre à partir de la fin.
* S'il vaut 0, l'ancre ne sera pas prise en compte pour le ciblage de début.
* </li>
* <li>
* - Le deuxième de ces éléments est objet \Aouka\Text\Regex, une expression rationnelle ou une constante de l'interface
* \Aouka\Text\InterfaceText. Il détermine l'ancre à utiliser.
* </li>
* <li>
* - Le troisième élément est optionnel. Il définit si l'ancre doit être incluse ou exclue du ciblage. Par
* défaut, l'ancre est incluse. Il peut être une expression rationnelle sous la forme d'une chaîne de caractères
* ou d'un objet \Aouka\Text\Regex. Cela peut aussi être une constante de la classe \Aouka\Text\Interface.
* </li>
* <ul>
* @param array|null $mEnd Si $mEnd vaut NULL, le ciblage termine à la fin de la chaîne.<br/>
* Si $mEnd est un tableau, il doit contenir entre 2 et 3 éléments : <br/>
* <ul>
* <li>
* - Le premier de ces éléments est un nombre entier qui détermine la position n de l'ancre à partir de
* laquelle termine le ciblage. Si ce nombre est positif le ciblage terminera à la énième ancre à partir
* du début de la chaîne ; s'il est négatif, le ciblage terminera à la énième ancre à partir de la fin.
* S'il vaut 0, l'ancre ne sera pas prise en compte pour le ciblage de fin.
* </li>
* <li>
* - Le deuxième de ces éléments est objet \Aouka\Text\Regex, une expression rationnelle ou une constante de l'interface
* \Aouka\Text\InterfaceText. Il détermine l'ancre à utiliser.
* </li>
* <li>
* - Le troisième élément est optionnel. Il définit si l'ancre doit être incluse ou exclue du ciblage. Par
* défaut, l'ancre est incluse. Il peut être une expression rationnelle sous la forme d'une chaîne de caractères
* ou d'un objet \Aouka\Text\Regex. Cela peut aussi être une constante de la classe \Aouka\Text\Interface.
* </li>
* <ul>
*/
public function __construct($mStart, $mEnd = null)
{
$aArgs = func_get_args();
$aArgs[1] = isset($aArgs[1]) ? $aArgs[1] : null;
for ($i = 0; $i <= 1; $i++) {
$iArgIndex = $i + 1;
if (!is_array($aArgs[$i]) && !is_null($aArgs[$i])) {
throw ExceptionType::invalidArgument("Argument #{$iArgIndex} doit être un tableau ou null.", Exception::FROM_HANDLER);
}
if ($aArgs[$i] !== null) {
$aParams = array_values($aArgs[$i]);
if (count($aParams) < 2 || !is_int($aParams[0])) {
throw ExceptionType::invalidArgument("Argument #{$iArgIndex} n'est pas un tableau indexé ayant comme premier élément un entier positif et second élément une expression rationnelle.\n\t\t\t\t\t\tLe troisième élément est optionnel. C'est un booléen déterminant si l'ancre de focus doit être incluse dans le ciblage.", Exception::FROM_HANDLER);
}
try {
$aArray = array('regex' => Regex::create($aParams[1]), 'offset' => $aParams[0], 'include' => (bool) (isset($aParams[2]) ? $aParams[2] : self::$_bDefaultInclusion));
} catch (\Exception $oException) {
throw ExceptionType::invalidArgument("Argument #{$iArgIndex} n'a pas comme second élément une expression rationnelle, un objet Aouka\\Text\\Regex ou une constante de Aouka\\Text\\InterfaceText.", Exception::FROM_HANDLER);
}
if (!$i) {
$this->_aInterval['start'] = $aArray;
} else {
$this->_aInterval['end'] = $aArray;
}
}
}
}
protected function _getWordRegex()
{
$sAdditionalChars = '';
if ($this->_sAdditionalChars) {
$aAdditionalChars = preg_split('//' . $this->_m(), $this->_sAdditionalChars, -1, PREG_SPLIT_NO_EMPTY);
$sAdditionalChars = implode('', array_map(function ($sAdditionalChar) {
return '|' . preg_quote($sAdditionalChar, '`');
}, $aAdditionalChars));
}
return Regex::create("`((?:[^[:space:][:punct:]]{$sAdditionalChars})+)`")->setModifiers($this->_m());
}
/**
* Formate sous forme littérale l'expression rationnelle à utiliser.
*
* @return void
* @throws \Exception
*/
protected function _formatPattern()
{
// Si on reçoit une chaîne de caractères, on la considère comme un pattern valide
if (is_string($this->_mPattern)) {
return;
}
// Si le pattern est un entier, c'est qu'il s'agit d'une constante
// on construit alors sa regex
if (is_int($this->_mPattern)) {
$this->_mPattern = Regex::create($this->_mPattern);
}
// Si le pattern est un objet \Aouka\Regex, on construit l'expression sous sa forme littérale
if ($this->_mPattern instanceof Regex) {
$this->_mPattern = '`(' . $this->_mPattern->getExpression() . ')`' . $this->_m();
return;
}
throw ExceptionType::invalidArgument("Le pattern fourni n'est pas correct.", Exception::FROM_HANDLER);
}
protected function _setAllowableTagNames()
{
Regex::create('`<(\\w+)(?:.+?)>`')->setModifiers($this->_m())->matchAll($this->_sAllowableTags, $aTags);
$this->_aAllowableTagNames = $aTags[1];
}
