cvs: phpdoc-fa /language namespaces.xml

psalehpoor Tue Jun 24 17:28:12 2008 UTC Added files: /phpdoc-fa/language namespaces.xml Log: translation to persian

http://cvs.php.net/viewvc.cgi/phpdoc-fa/language/namespaces.xml?view=markup&rev=1.1 Index: phpdoc-fa/language/namespaces.xml +++ phpdoc-fa/language/namespaces.xml <?xml version="1.0" encoding="UTF-8"?> <!-- EN-Revision: 1.4 Maintainer: pedram Status: ready --> <!-- $Revision: 1.1 $ --> <chapter xml:id="language.namespaces" xmlns="http://docbook.org/ns/docbook" version="1.1"> <title>فضاهای نام</title> <sect1 xml:id="language.namespaces.rationale"> <title>مرور بر فضاهای نام</title> <simpara> فضاهای نام در PHP برای حل مشکل تعداد زیاد توابع در کتابخانه PHP ایجاد شده‌اند. در PHP تمام تعریف کلاس‌ها جهانی هستند. بنابراین وقتی یک نویسنده کتابخانه در تلاش است تا یک مجموعه API جدید بنویسد باید دقت نماید که نام توابع دیگر را برای خود انتخاب ننماید و بنابراین اسامی منحصر بفرد در این کتابخانه‌ها بتوانند به همراه یکدیگر وجود داشته باشند. معمولا با نام کلاس پیشوندی با رشته منحصر بفرد - به عنوان نمونه کلاس‌های پایگاه داده پیشوند <classname>My_Library_DB</classname> خواهند گرفت و غیره. همانطور که کتابخانه گسترش می‌یابد پیشوندها به آنها اضافه خواهد شد تا منحصر بفر باقی بمانند. </simpara> <simpara> فضای نام به به برنامه‌نویس اجازه می‌دهد تا حوزه نام‌ها را مدیریت نماید و بدون استفاده از نام‌های بلند این موضوع ممکن گردد و مشکل فضای جهانی را بدون ناخوانا کردن کد حل نماید. </simpara> <simpara> فضای نام در PHP پس از PHP 5.3.0 فراهم شده است. این بخش آزمایشی است و ممکن است تغییر یابد. </simpara> </sect1> <sect1 xml:id="language.namespaces.definition"> <title>تعریف فضای نام</title> <para> فضای نام با استفاده از کلمه کلیدی <literal>namespace</literal> در ابتدای فایل تعریف شود. نمونه: <example> <title>تعریف فضای نام</title> <programlisting role="php"> <![CDATA[ <?php namespace MyProject::DB; const CONNECT_OK = 1; class Connection { /* ... */ } function connect() { /* ... */ } ?> ]]> </programlisting> </example> چند نام فضای نام را می‌توان در چندین فایل استفاده کرد. </para> <para> فضای نام کلاس ثابت و تعریف تابع را دارد اما کد آزاد ندارد. </para> <para> تعریف فضای نام بصورت زیر عمل می‌نماید: <itemizedlist> <listitem> <simpara> در فضای نام تمام اسامی تمام کلاس‌ها تابع و ثابت‌ها در تعریف آنها بصورت خودکار پیشوند نام فضای نام را دریافت می‌کنند. نام کلاس همیشه نام کامل مانند نام کلاس بالا <classname>MyProject::DB::Connection</classname> است. </simpara> </listitem> <listitem> <simpara> تعریف‌های ثابت تعریف ساخته است که از نام فضای نام و نام ثابت تشکیل شده است. مانند ثابت‌های کلاس ثابت فضای نام تنها مقادیر ثابت در خود نگه می‌دارد. </simpara> </listitem> <listitem> <para> نام کلاس تعریف نشده (برای نمونه اسامی غیر شامل <literal>::</literal>) در زمان اجرا با استفاده از رویه زیر انجام میذشود: <orderedlist> <listitem> <simpara> کلاس در داخل فضای نام بدون (برای نمونه پیشوند نمودن نام با نام فضای نام فعلی) تلاش برای <link linkend="language.oop5.autoload">autoload</link> جستجو می‌گردد. </simpara> </listitem> <listitem> <simpara> کلاس در فضای نام جهانی بدون تلاش برای بارگذاری جستجو می‌گردد. </simpara> </listitem> <listitem> <simpara> بارگذاری خودکار برای نام در فضای نام فعلی انجام خواهد شد. </simpara> </listitem> <listitem> <simpara>اگر اقدام پیشین شکست بخرد جستجو نیز شکست خورده است.</simpara> </listitem> </orderedlist> </para> </listitem> <listitem> <para> نام تابع تایید نشده (برای نمونه نام بدون <literal>::</literal>) در زمان اجرا در فضای نام فعلی و سپس در حوزه جهانی جستجو خواهد شد. </para> </listitem> <listitem> <para> نام ثابت تایید نشده در زمان اجرا در فضای نام فعلی و سپس در فضای نام جهانی جستجو خواهد شد. </para> </listitem> </itemizedlist> <link linkend="language.namespaces.rules">قوانین تحلیل نام</link> را ببینید. </para> </sect1> <sect1 xml:id="language.namespaces.using"> <title>استفاده از فضای نام</title> <para> هر کلاس و تابع در فضای نام با استفاده از نام کامل می‌تواند خوانده شود برای نمونه <classname>MyProject::DB::Connection</classname> یا <classname>MyProject::DB::connect</classname>. <example> <title>استفاده از نام فضای نام دار</title> <programlisting role="php"> <![CDATA[ <?php require 'MyProject/Db/Connection.php'; $x = new MyProject::DB::Connection; MyProject::DB::connect(); ?> ]]> </programlisting> </example> </para> <para> فضای نام می‌تواند داخل متن فعلی (جهانی فضای نام) با استفاده از عملگر <literal>use</literal> وارد شود دستور عملگر به این صورت است: <informalexample> <programlisting role="php"> <![CDATA[ <?php /* ... */ use Some::Name as Othername; // The simplified form of use: use Foo::Bar; // which is the same as : use Foo::Bar as Bar; ?> ]]> </programlisting> </informalexample> نام گرفته شده بصورت زیر عمل خواهد کرد: هر بار کامپایلر در برابر نام محلی <literal>Othername</literal> قرار می‌گیرد (به عنوان نام تنها یایا پیشوند یک نام بلندتر <literal>::</literal>) نام <literal>Some::Name</literal> در جای آن جایگزین خواهد گردید. </para> <para> <literal>use</literal> تنها در حوزه جهانی قابل استفاده است و نه در داخل تابع یا کلاس. نام‌ها وارد شده از نقطه ورود به بعد تا پایان فایل فعلی تاثیر دارند. توصیه می‌گردد ورود در ابتدای فایل باشد تا از گمراهی خودداری نماید. </para> <para> <example> <title>وارد نمودن ودسترسی به فضای نام</title> <programlisting role="php"> <![CDATA[ <?php require 'MyProject/Db/Connection.php'; use MyProject::DB; use MyProject::DB::Connection as DbConnection; $x = new MyProject::DB::Connection(); $y = new DB::connection(); $z = new DbConnection(); DB::connect(); ?> ]]> </programlisting> </example> </para> <para> <note> <simpara> عملیات ورود در زمان کامپایل انجام می‌شود و تمام نام‌های محلی به نام کامل آنها توسط کامپایلر تبدیل خواهند شد. توجه کنید که نام‌های درون رشته‌ها ترجمه نخواهند گردید و callback براساس این قوانین عمل نخواهد کرد </simpara> </note> </para> </sect1> <sect1 xml:id="language.namespaces.global"> <title>فضای جهانی</title> <para> بدون تعریف هیچ فضای نام تمامتعریف‌های تابع و کلاس در فضای جهانی قرار خواهند گرفت همانطور که پیش از این در PHP عمل می‌شده است.قرار دادن پیشوند به نام با استفاده از <literal>::</literal> نام مورد نیاز برای فضای جهانی را در متن فضای نام ضروری خواهد ساخت. <example> <title>استفاده از تعریف فضای جهانی</title> <programlisting role="php"> <![CDATA[ <?php namespace A::B::C; /* This function is A::B::C::fopen */ function fopen() { /* ... */ $f = ::fopen(...); // call global fopen return $f; } ?> ]]> </programlisting> </example> </para> </sect1> <sect1 xml:id="language.namespaces.constant"> <title>__NAMESPACE__</title> <para> ثابت زمان کامپایل <constant>__NAMESPACE__</constant> توسط نام فضای نام فعلی تعیین خواهد گردید. بیرون از فضای نام این ثابت مقدار رشته خالی را خواهد داشت. این ثابت به خصوص برای نوشتن نام کامل نام‌های فضای نام محلی مور دیناز است. <example> <title>استفاده از __NAMESPACE__</title> <programlisting role="php"> <![CDATA[ <?php namespace A::B::C; function foo() { // do stuff } set_error_handler(__NAMESPACE__ . "::foo"); ?> ]]> </programlisting> </example> </para> </sect1> <sect1 xml:id="language.namespaces.rules"> <title>قوانین تحلیل نام</title> <para> نام‌ها با استفاده از قوانین زیر مورد تحلیل قرار می‌گیرند. <orderedlist> <listitem> <simpara> نام‌های تایید شده در طول کامپایل با توجه به قوانین کامپایل خواهند گردید. برای نمونه اگر فضای نام A::B::C وارد شده باشد یک فراخوانی برای <code>C::D::e()</code> به <code>A::B::C::D::e()</code> ترجمه خواهد شد. </simpara> </listitem> <listitem> <simpara> نام کلاس تایید نشده در طول کامپایل با توجه به قوانین ورود (جایگزینی نام کوتاه با نام کامل) ترجمه خواهند شد. برای نمونه اگر فضای نام <literal>A::B::C</literal> وارد شده باشد <code>new C()</code> به <code>new A::B::C()</code> ترجمه خواهد شد. </simpara> </listitem> <listitem> <simpara> در داخل یک فضای نام فراخوانی توابع تایید نشده که در فضای نام فعلی تعریف شده‌اند (در زمان فراخوانی شناخته شده‌اند) به عنوان فراخوانی این فضای نام‌ها در زمان کامپایل تفسیر خواهند گردید. </simpara> </listitem> <listitem> <simpara> در داخل فضای نام (فرض کنید A::B) به توابع تایید نشده در فضای نام فعلی در زمان اجرا تحلیل خواهند گردید. در اینجا چگونگی فراخوانی تابع <literal>foo()</literal> نشان داده شده است: </simpara> <orderedlist> <listitem> <simpara> بدنبال یک تابع در فضای نام فعلی می‌گردد: <literal>A::B::foo()</literal>. </simpara> </listitem> <listitem> <simpara> تلاش می‌نماید تا تابع <emphasis>internal</emphasis> را یافته و <literal>foo()</literal> را اجرا نماید. </simpara> </listitem> </orderedlist> <simpara> برای فراخوانی یک تابع تعریف شده توسط کاربر در فضای نام جهانی <literal>::foo()</literal> استفاده خواهد شد. </simpara> </listitem> <listitem> <simpara> در یک فضای نام (فرض کنید <literal>A::B</literal>) نام کلاس تایید نشده را در زمان اجرا تحلیل می‌نماید. در اینجا چگونگی فراخوانی <code>new C()</code> نشان داده شده است: </simpara> <orderedlist> <listitem> <simpara> بدنبال یک کلاس از فضای نام فعلی خواهد گشت: <literal>A::B::C</literal>. </simpara> </listitem> <listitem> <simpara> تلاش خواهد کرد که کلاس <emphasis>internal</emphasis> را یافته و <literal>C</literal> را اجرا نماید. </simpara> </listitem> <listitem> <simpara> تلاش خواهد کرد بصورت خودکار <literal>A::B::C</literal> را بارگذاری نماید. </simpara> </listitem> </orderedlist> <simpara> برای ارجاع به یک کلاس تعریف شده توسط کاربر در فضای نام جهانی باید از <code>new ::C()</code> استفاده شود. </simpara> </listitem> <listitem> <simpara> فراخوانی توابع تایید نشده در زمان اجرا تحلیل خواهند گردید. در این جا چگونگی فراخوانی <literal>A::B::foo()</literal> نشان داده شده است: </simpara> <orderedlist> <listitem> <simpara> بدنبال تابع <literal>foo()</literal> در فضای نام <literal>A::B</literal> خواهند گشت. </simpara> </listitem> <listitem> <simpara> بدنبال یک کلاس <literal>A::B</literal> گشته و متد استاتیک <literal>foo()</literal> را فرا خواهد خواند. اگر مورد نیاز باشد کلاس بصورت خودکار بارگذاری خواهد شد. </simpara> </listitem> </orderedlist> </listitem> <listitem> <simpara> کلاس تایید شده در زمان کامپایل تحلیل خواهد گردید برای نمونه <code>new A::B::C()</code> به کلاس <classname>C</classname> از فضای نام <literal>A::B</literal> اشاره خواهد کرد. </simpara> </listitem> </orderedlist> </para> <example> <title>تحلیل نام نشان داده شده است</title> <programlisting role="php"> <![CDATA[ <?php namespace A; // function calls foo(); // first tries to call "foo" defined in namespace "A" // then calls internal function "foo" ::foo(); // calls function "foo" defined in global scope // class references new B(); // first tries to create object of class "B" defined in namespace "A" // then creates object of internal class "B" new ::B(); // creates object of class "B" defined in global scope // static methods/namespace functions from another namespace B::foo(); // first tries to call function "foo" from namespace "A::B" // then calls method "foo" of internal class "B" ::B::foo(); // first tries to call function "foo" from namespace "B" // then calls method "foo" of class "B" from global scope // static methods/namespace functions of current namespace A::foo(); // first tries to call function "foo" from namespace "A::A" // then tries to call method "foo" of class "A" from namespace "A" // then tries to call function "foo" from namespace "A" // then calls method "foo" of internal class "A" ::A::foo(); // first tries to call function "foo" from namespace "A" // then calls method "foo" of class "A" from global scope ?> ]]> </programlisting> </example> </sect1> </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:"../../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 -->