archived-doc-es/reference/yaml/callbacks.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 80872147aa52367137bd3d168412f70cbe2ddf9c Maintainer: edwincartagenah Status: ready -->
<!-- Reviewed: yes -->

<chapter xml:id="yaml.callbacks" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Callbacks</title>

 <section xml:id="yaml.callbacks.parse">
  <title>Análisis de callbacks</title>
  <para>
   Los análisis de <type>callable</type>s son invocados por las funciones
   <function>yaml_parse</function>, <function>yaml_parse_file</function> o
   <function>yaml_parse_url</function> cuando encuentran una etiqueta YAML
   registrada. Al callback se le pasa el valor de la entidad de la etiqueta, la etiqueta,
   y los flags que indican el estilo escalar de la entidad. El callback debe
   devolver los datos que el convertidor YAML debe emitir para esta entidad.
  </para>
  <example>
   <title>Ejemplo de análisis de callback</title>
   <programlisting role="php">
<![CDATA[
<?php
/**
 * Análisis de callback para un tag yaml.
 * @param mixed $valor Datos del archivo yaml
 * @param string $tag Etiqueta que desencadenó el callback
 * @param int $flags Estilo escalar de la entidad (ver YAML_*_SCALAR_STYLE)
 * @return mixed Valor que el convertidor YAML debería emitir para el valor dado
 */
function tag_callback ($valor, $tag, $flags) {
  var_dump(func_get_args()); // depurando
  return "Hola {$valor}";
}

$yaml = <<<YAML
saludo: !ejemplo/hola Mundo
YAML;

$resultado = yaml_parse($yaml, 0, $ndocs, array(
    '!ejemplo/hola' => 'tag_callback',
  ));

var_dump($resultado);
?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
<![CDATA[
array(3) {
  [0]=>
  string(5) "Mundo"
  [1]=>
  string(14) "!ejemplo/hola"
  [2]=>
  int(1)
}
array(1) {
  ["saludo"]=>
  string(11) "Hola Mundo"
}
]]>
   </screen>
  </example>
 </section>

 <section xml:id="yaml.callbacks.emit">
  <title>Emitir callbacks</title>
  <para>
   Las emisiones de callbacks son invocadas cuando una instancia de una clase registrada es
   emitida por la función <function>yaml_emit</function> o la función
   <function>yaml_emit_file</function>. El callback se pasa al objeto a
   ser emitido. El callback debe devolver un array que contenga dos claves:
   &quot;<literal>tag</literal>&quot; y &quot;<literal>data</literal>&quot;.
   El valor asociado con la clave &quot;<literal>tag</literal>&quot; debe
   ser un string a ser usado como la etiqueta YAML en la salida. El valor asociado
   con la clave &quot;<literal>data</literal>&quot; será encodeado como YAML
   y será emitido en lugar del objeto interceptado.
  </para>
  <example>
   <title>Ejemplo de emisión de callback</title>
   <programlisting role="php">
<![CDATA[
<?php
class EmitExample {
  public $data;    // los datos podrían ser ajustables en cualquier tipo de pecl/yaml

  public function __construct ($d) {
    $this->data = $d;
  }

  /**
   * Yaml emite la función de callback, referida a la llamada yaml_emit por el nombre de la clase.
   *
   * Se espera que devuelva un array con 2 valores:
   *   - 'tag': etiqueta personalizada para esta serialización
   *   - 'data': valor que se convierte a yaml (ya sea array, string, bool, número)
   *
   * @param object $obj Objeto a ser emitido
   * @return array Etiqueta y datos sustitutivos a emitir
   */
  public static function yamlEmit (EmitExample $obj) {
    return array(
      'tag' => '!example/emit',
      'data' => $obj->data,
    );
  }
}

$emit_callbacks = array(
  'EmitExample' => array('EmitExample', 'yamlEmit')
);

$t = new EmitExample(array('a','b','c'));
$yaml = yaml_emit(
  array(
    'example' => $t,
  ),
  YAML_ANY_ENCODING,
  YAML_ANY_BREAK,
  $emit_callbacks
);
var_dump($yaml);
?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
<![CDATA[
string(43) "---
example: !example/emit
- a
- b
- c
...
"
]]>
   </screen>
  </example>
 </section>

</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->