صفحة الصنف MatchData في روبي

تحوّل المكتبة Marshal مجموعات من كائنات روبب إلى سلاسل بتات (byte stream)، مما يسمح بتخزينها خارج البرنامج النصي النشط حاليًا. ثم يمكن بعد ذلك قراءة تلك البيانات وإعادة إنشاء الكائنات الأصلية.

تحتوي البيانات المرصوفة (Marshaled data) على أرقام إصدار رئيسية وثانوية مخزنة مع معلومات الكائن. في الاستخدام العادي ، تُحمّل فقط البيانات التي لها نفس رقم الإصدار الرئيسي، ورقم إصدار ثانوي مساوٍ أو أقل. وفي حال ضبط قيمة الراية "verbose" (عادةً باستخادم ‎-d أو ‎-v أو ‎-w أو ‎-verbose) يجب أن تتطابق الأرقام الرئيسية والثانوية تمامًا. إصدارات Marshal مستقلة عن إصدار روبي المستخدم. يمكنك استخلاص رقم الإصدار عن طريق قراءة أول بتّتين من البيانات المشحونة.

str = Marshal.dump("thing")
RUBY_VERSION   #=> "1.9.0"
str[0].ord     #=> 4
str[1].ord     #=> 8

لا يمكن تفريغ بعض الكائنات: في حال محاولة تفريغ كائنات تتضمن ارتباطات (bindings) أو إجراءات (procedure) أو توابع، أو كائنات IO، أو كائنات أحادية (singleton)، فسيطلق الخطأ TypeError.

إن كنت تريد تسلسلا (serialization) مخصصًا (على سبيل المثال ، إذا كنت تريد إجراء التسلسل وفق تنسيق معين) ، أو إذا كان الصنف يحتوي كائنات غير قابلة للتسلسل، فيمكنك إعداد قواعد التسلسل الخاصة بك.

هناك طريقتان للقيام بذلك، يمكن للكائنات أن تعرّف إما marshal_dump و marshal_load أو ‎_dump و ‎_load. سيكون لـ marshal_dump الأولوية على ‎_dump في حال تعريف كليهما. قد يُنتج marshal_dump سلاسل نصية أصغر.

اعتبارات أمنية

يمكن للتابع load فك تسلسل (deserialize) تقريبا أي صنف مُحمّل في عمليات روبي. في العديد من الحالات، يمكن أن يؤدي ذلك إلى تنفيذ التعليمات البرمجية عن بُعد، إن حُملت البيانات المرصوفة (Marshal data) من مصدر غير موثوق به.

ونتيجة لذلك ، فالتابع load:: ليس مناسبًا ليكون تنسيق تسلسل عام، ويجب ألا يتم تبديد (unmarshal) البيانات المُدخلة من قبل المستخدم أو غيرها من البيانات غير الموثوقة.

إذا كنت تريد فك تسلسل (deserialize) البيانات غير الموثوقة، فاستخدم JSON أو تنسيق تسلسل آخر لا يمكنه أن يحمّل إلا الأنواع "البدائية" البسيطة، مثل السلاسل النصية والمصفوفات والقواميس وما إلى ذلك. لا تسمح أبدًا لمدخلات المستخدم أن تحدد أنواع عشوائية لفك التسلسل.

marshal_dump و marshal_load

عند تفريغ (dumping) كائن سيتم استدعاء التابع marshal_dump. يجب أن يعيد التابع marshal_dump نتيجة تحتوي على المعلومات الضرورية لـ marshal_load لإعادة إنشاء الكائن. النتيجة يمكن أن تكون أي كائن.

عند تحميل كائن تم تفريغه باستخدام marshal_dump، يتم أولاً تحديد الكائن، ثم يُستدعى marshal_load وتُمرّر إليه النتيجة المُعادة من marshal_dump. يجب أن يعيد التابع marshal_load إنشاء الكائن انطلاقًا من المعلومات المُتضمنة في النتيجة.

مثال:

class MyObj
  def initialize name, version, data
    @name    = name
    @version = version
    @data    = data
  end

  def marshal_dump
    [@name, @version]
  end

  def marshal_load array
    @name, @version = array
  end
end

‎_dump و ‎_load

استخدم التابعين ‎ _dump و ‎_load عندما تريد تحديد الكائن الذي تود استعادته بنفسك.

عند تفريغ كائن، يُستدعى التابع ‎_dump مع تمرير عدد صحيح إليه إشارة إلى العمق الأقصى للكائنات التى ستُفرّغ (القيمة ‎ -‎‎1تعني تعطيل التحقق من العمق). يجب أن يعيد التابع ‎ _dump سلسلة نصية تحتوي على المعلومات الضرورية لإعادة إنشاء الكائن.

يأخذ الصنف method_load سلسلة نصية ويستخدمها لإعادة كائن من نفس الصنف.

مثال:

class MyObj
  def initialize name, version, data
    @name    = name
    @version = version
    @data    = data
  end

  def _dump level
    [@name, @version].join ':'
  end

  def self._load args
    new(*args.split(':'))
  end
end

لما كان التابع dump يعيد سلسلة نصية، يمكنك جعل التابع have_dump يعيد سلسلة مرصوفة ‎‏ (Marshal string)،

توابع الصنف العامة (Public Class Methods)

التابع ==

معامل التساوي - يتطابق كائنان من النوع matchdata إذا كانت السلاسل النصية المستهدفة منهما، والأنماط ومواضع المُطابقة متماثلة.

التابع []

تتصرف MatchData كمصفوفة، ويمكن الدخول إليهت باستخدام تقنيات فهرسة المصفوفات العادية. التعبير mtch[0] مكافئ للمتغير الخاص $&، لذلك فهو يعيد كامل السلسلة النصية المُطابقة. فيما تعيد التعابير mtch[1] و mtch[2] وهلم جرا، القيم المؤشرة (backdferences) المتطابقة (أجزاء النمط الموجودة بين قاسين).

التابع begin

يعيد ظظظ موضع (offset) بداية العنصر رقم n من مصفوفة التطابق في السلسلة النصية. n يمكن أن يكون سلسلة نصية أو رمز للإشارة إلى جزء مُطابق معيّن.

التابع captures

يعيد ظظظ مصفوفة الأجزاء المُطابقة (array of captures)؛ يكافئ mtch.to_a[1..-1].

التابع end

يعيد ظظظ موضع (offset) بداية العنصر رقم n من مصفوفة التطابق في السلسلة النصية. n يمكن أن يكون سلسلة نصية أو رمز للإشارة إلى جزء مُطابق معيّن.

التابع eql?

يتحقق من التساوي - كائنان من النوع matchdata يكونان متساويين إذا كانت السلاسل النصية التي يستهدفونها، والأنماط ومواضع التطابق متمائلة.

التابع hash

ينتج ظظظ قاموسًا (hash) استنادًا إلى السلسلة النصية المستهدفة والتعبير النمطي regexp ومواضع المطابقة للكائن اmatchdata.

التابع inspect

يعيد ظظظ نسخة قابلة للطباعة من mtch.

التابع length

يعيد ظظظ عدد العناصر في مجموعة المطابقة.

التابع named_captures

يعيد ظظظ قاموسًا (Hash) باستخدام الجزء المُطابق (capture) المعين .

التابع names

يعيد ظظظ قائمة بأسماء الأجزاء المُلتقطة (captures) كمصفوفة من سلاسل نصية. حيث يكافئ نفس mtch.regexp.names.

التابع offset

يعيد ظظظ مصفوفة ثنائية تحتوي موضعي (offsets) البداية والنهاية للمطابقة رقم n. الوسيط n يمكن أن يكون سلسلة نصية أو رمزًا للإشارة إلى مطابقة (capture) معينة.

التابع post_match

يعيد ظظظ الجزء الذي يلي المطابقة (match) الحالية من السلسلة النصية الأصلية. وهو يكافئ المتغير الخاص $'.

التابع pre_match

يعيد ظظظ الجزء الذي يسبق المطابقة (match) الحالية من السلسلة النصية الأصلية. وهو يكافئ المتغير الخاص $`.

التابع regexp

يعيد ظظظ التعبير النمطي regexp.

التابع size

يعيد ظظظ عدد العناصر في مصفوفة المطابقة.

التابع string

يعيد ظظظ نسخة مُجمدة من السلسلة النصية التي تم تمريرها إلى match.

التابع to_a

يعيد ظظظ مصفوفة المطابقات.

التابع to_s

يعيد ظظظ كامل السلسلة النصية المُطابَقة.

التابع values_at

يستخدم ظظظ الفهارس المعطاة index للدخول إلى القيم المُطابقة، ثم يعيد مجموعة من المطابقات المقابلة.

مصادر

• قسم الصنف Marshal في توثيق روبي الرسمي.