Add documentation for the var_representation PECL

Closes GH-885.
This commit is contained in:
Tyson Andre 2021-09-16 13:14:10 -04:00 committed by GitHub
parent 7c2251296a
commit 1f64cacbb5
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 413 additions and 0 deletions

View file

@ -162,6 +162,7 @@
<listitem><simpara><xref linkend="book.url"/></simpara></listitem>
<listitem><simpara><xref linkend="book.v8js"/></simpara></listitem>
<listitem><simpara><xref linkend="book.var"/></simpara></listitem>
<listitem><simpara><xref linkend="book.var_representation"/></simpara></listitem>
<listitem><simpara><xref linkend="book.varnish"/></simpara></listitem>
<listitem><simpara><xref linkend="book.wddx"/></simpara></listitem>
<listitem><simpara><xref linkend="book.win32service"/></simpara></listitem>
@ -377,6 +378,7 @@
<listitem><para><xref linkend="book.ui"/></para></listitem>
<listitem><para><xref linkend="book.uopz"/></para></listitem>
<listitem><para><xref linkend="book.v8js"/></para></listitem>
<listitem><para><xref linkend="book.var_representation"/></para></listitem>
<listitem><para><xref linkend="book.varnish"/></para></listitem>
<listitem><para><xref linkend="book.wddx"/></para></listitem>
<listitem><para><xref linkend="book.win32service"/></para></listitem>

View file

@ -0,0 +1,39 @@
<?xml version="1.0" encoding="utf-8"?>
<book xml:id="book.var_representation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<?phpdoc extension-membership="pecl" ?>
<title>var_representation</title>
<titleabbrev>var_representation</titleabbrev>
<preface xml:id="intro.var_representation">
&reftitle.intro;
<simpara>
The var_representation extension provides a compact alternative to <function>var_export</function> that properly escapes control characters.
</simpara>
</preface>
&reference.var-representation.setup;
&reference.var-representation.constants;
&reference.var-representation.reference;
</book>
<!-- 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
-->

View file

@ -0,0 +1,53 @@
<?xml version="1.0" encoding="utf-8"?>
<appendix xml:id="var-representation.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.constants;
&extension.constants;
<para>
<variablelist>
<varlistentry xml:id="constant.var-representation-single-line">
<term>
<constant>VAR_REPRESENTATION_SINGLE_LINE</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
<function>var_representation</function> flag indicating that newlines
should not be used for whitespace in variable representations.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.var-representation-unescaped">
<term>
<constant>VAR_REPRESENTATION_UNESCAPED</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
<function>var_representation</function> flag indicating that strings should be encoded
as single quoted strings with unescaped control characters.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
</appendix>
<!-- 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
-->

View file

@ -0,0 +1,222 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="function.var-representation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>var_representation</refname>
<refpurpose>Returns a short, readable, parsable string representation of a variable</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>var_representation</methodname>
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
</methodsynopsis>
<simpara>
<function>var_representation</function> (from the var_representation PECL) returns a string with structured information about the
given variable. It is similar to <function>var_export</function> with differences in indentation, string escaping, and array representations.
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
The variable to generate a representation of.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
Bitmask consisting of
<constant>VAR_REPRESENTATION_SINGLE_LINE</constant>,
<constant>VAR_REPRESENTATION_UNESCAPED</constant>.
The behaviour of these constants is described on the
<link linkend="var-representation.constants">var_representation constants</link> page.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the variable representation.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>var_representation</function> Examples</title>
<programlisting role="php">
<![CDATA[
<?php
$a = [1, 2, ['key' => 'value']];
echo var_representation($a), "\n";
echo var_representation($a, VAR_REPRESENTATION_SINGLE_LINE), "\n";
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
[
1,
2,
[
'key' => 'value',
],
]
[1, 2, ['key' => 'value']]
]]>
</screen>
</example>
</para>
<para>
<example>
<title>Escaping control characters</title>
<programlisting role="php">
<![CDATA[
<?php
echo var_representation("Content-Length: 123\r\n");
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
"Content-Length: 123\r\n"
]]>
</screen>
</example>
</para>
<para>
<example>
<title>Exporting <classname>stdClass</classname></title>
<programlisting role="php">
<![CDATA[
<?php
$person = new stdClass;
$person->name = 'ElePHPant ElePHPantsdotter';
$person->website = 'https://php.net/elephpant.php';
echo var_representation($person);
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
(object) [
'name' => 'ElePHPant ElePHPantsdotter',
'website' => 'https://php.net/elephpant.php',
]
]]>
</screen>
</example>
</para>
<para>
<example>
<title>Exporting classes</title>
<programlisting role="php">
<![CDATA[
<?php
class A { public $var; }
$a = new A;
$a->var = 5;
echo var_representation($a);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
\A::__set_state([
'var' => 5,
])
]]>
</screen>
</example>
</para>
<para>
<example>
<title>Using <link linkend="object.set-state">__set_state()</link></title>
<programlisting role="php">
<![CDATA[
<?php
class A
{
public $var1;
public $var2;
public static function __set_state($an_array)
{
$obj = new A;
$obj->var1 = $an_array['var1'];
$obj->var2 = $an_array['var2'];
return $obj;
}
}
$a = new A;
$a->var1 = 5;
$a->var2 = 'foo';
eval('$b = ' . var_representation($a) . ';'); // $b = \A::__set_state([
// 'var1' => 5,
// 'var2' => 'foo',
// ]);
var_dump($b);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
object(A)#2 (2) {
["var1"]=>
int(5)
["var2"]=>
string(3) "foo"
}
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>var_export</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- 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
-->

View file

@ -0,0 +1,27 @@
<?xml version="1.0" encoding="utf-8"?>
<reference xml:id="ref.var-representation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>var_representation &Functions;</title>
&reference.var-representation.entities.functions;
</reference>
<!-- 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
-->

View file

@ -0,0 +1,44 @@
<?xml version="1.0" encoding="utf-8"?>
<chapter xml:id="var-representation.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.setup;
<section xml:id="var-representation.requirements">
&reftitle.required;
&no.requirement;
</section>
<section xml:id="var-representation.installation">
&reftitle.install;
<para>
&pecl.moved;
</para>
<para>
&pecl.info;
<link xlink:href="&url.pecl.package;var_representation">&url.pecl.package;var_representation</link>.
</para>
<para>
&pecl.windows.download.avail;
</para>
</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
-->

View file

@ -0,0 +1,26 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- Do NOT translate this file -->
<versions>
<!-- Functions -->
<function name='var_representation' from='PECL var_representation &gt;= 0.1.0'/>
</versions>
<!-- 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
-->