ArgTools

ArgRead = Union{AbstractString, AbstractCmd, IO}

أنواع ArgRead هي اتحاد للأنواع التي يعرفها دالة arg_read كيفية تحويلها إلى مقبضات IO قابلة للقراءة. انظر arg_read لمزيد من التفاصيل.

ArgWrite = Union{AbstractString, AbstractCmd, IO}

أنواع ArgWrite هي اتحاد من الأنواع التي يعرفها دالة arg_write لكيفية تحويلها إلى مقبضات IO قابلة للكتابة، باستثناء Nothing التي تتعامل معها arg_write عن طريق إنشاء ملف مؤقت. انظر arg_write لمزيد من التفاصيل.

arg_read(f::Function, arg::ArgRead) -> f(arg_io)

تقبل دالة arg_read وسيطًا arg يمكن أن يكون أيًا من هذه:

• AbstractString: مسار ملف لفتحه للقراءة
• AbstractCmd: أمر للتنفيذ، يتم القراءة من مخرجاته القياسية
• IO: مقبض IO مفتوح للقراءة منه

سواءً كانت النتيجة طبيعية أو حدث خطأ، سيتم إغلاق المسار الذي تم فتحه قبل العودة من arg_read وسيتم تفريغ مقبض IO ولكن لن يتم إغلاقه قبل العودة من arg_read.

ملاحظة: عند فتح ملف، ستقوم ArgTools بتمرير lock = false إلى استدعاء open(...) للملف. لذلك، يجب عدم استخدام الكائن الذي تم إرجاعه من هذه الدالة من عدة خيوط. قد يتم تخفيف هذا القيد في المستقبل، مما لن يكسر أي كود يعمل.

arg_write(f::Function, arg::ArgWrite) -> arg
arg_write(f::Function, arg::Nothing) -> tempname()

تقبل دالة arg_read وسيطًا arg يمكن أن يكون أيًا من هذه:

• AbstractString: مسار ملف لفتحه للكتابة
• AbstractCmd: أمر للتنفيذ، يكتب إلى مدخلاته القياسية
• IO: مقبض IO مفتوح للكتابة
• Nothing: يجب كتابة مسار مؤقت

إذا عاد الجسم بشكل طبيعي، سيتم إغلاق المسار الذي تم فتحه عند الانتهاء؛ بينما يظل وسيط مقبض IO مفتوحًا ولكن يتم تفريغه قبل العودة. إذا كان الوسيط هو nothing، فسيتم فتح مسار مؤقت للكتابة وإغلاقه عند الانتهاء، وسيتم إرجاع المسار من arg_write. في جميع الحالات الأخرى، يتم إرجاع arg نفسه. هذه نمط مفيد حيث يمكنك بشكل متسق إرجاع ما تم كتابته، سواء تم تمرير وسيط أم لا.

إذا حدث خطأ أثناء تقييم الجسم، سيتم حذف المسار الذي تم فتحه بواسطة arg_write للكتابة، سواء تم تمريره كسلسلة نصية أو كمسار مؤقت تم إنشاؤه عندما يكون arg هو nothing.

ملاحظة: عند فتح ملف، ستقوم ArgTools بتمرير lock = false إلى استدعاء open(...) للملف. لذلك، يجب عدم استخدام الكائن الذي تم إرجاعه من هذه الدالة من عدة خيوط. قد يتم تخفيف هذا القيد في المستقبل، مما لن يكسر أي كود يعمل.

arg_isdir(f::Function, arg::AbstractString) -> f(arg)

تأخذ دالة arg_isdir المتغير arg الذي يجب أن يكون مسارًا إلى دليل موجود (يتم رفع خطأ خلاف ذلك) وتقوم بتمرير ذلك المسار إلى f وأخيرًا تعيد نتيجة f(arg). هذه بالتأكيد أقل أداة مفيدة تقدمها ArgTools وتوجد في الغالب من أجل التماثل مع arg_mkdir ولتقديم رسائل خطأ متسقة.

arg_mkdir(f::Function, arg::AbstractString) -> arg
arg_mkdir(f::Function, arg::Nothing) -> mktempdir()

تأخذ دالة arg_mkdir المتغير arg الذي يجب أن يكون إما واحدًا من:

• مسار إلى دليل فارغ موجود بالفعل،
• مسار غير موجود يمكن إنشاؤه كدليل، أو
• nothing وفي هذه الحالة يتم إنشاء دليل مؤقت.

في جميع الحالات، يتم إرجاع المسار إلى الدليل. إذا حدث خطأ أثناء f(arg)، يتم إرجاع الدليل إلى حالته الأصلية: إذا كان موجودًا بالفعل ولكنه كان فارغًا، فسيتم إفراغه؛ إذا لم يكن موجودًا، فسيتم حذفه.

arg_readers(arg :: AbstractString, [ type = ArgRead ]) do arg::Function
    ## إعداد ما قبل الاختبار ##
    @arg_test arg begin
        arg :: ArgRead
        ## اختبار باستخدام `arg` ##
    end
    ## تنظيف ما بعد الاختبار ##
end

تأخذ دالة arg_readers مسارًا ليتم قراءته وكتلة do ذات حجة واحدة، والتي يتم استدعاؤها مرة واحدة لكل نوع من أنواع قارئ الاختبار التي يمكن أن يتعامل معها arg_read. إذا تم إعطاء حجة type الاختيارية، فسيتم استدعاء كتلة do فقط للقارئين الذين ينتجون حججًا من هذا النوع.

الحجة arg المرسلة إلى كتلة do ليست قيمة الحجة نفسها، لأن بعض أنواع حجج الاختبار تحتاج إلى التهيئة والتصفية لكل حالة اختبار. اعتبر حجة مقبض ملف مفتوح: بمجرد أن تستخدمه لاختبار واحد، لا يمكنك استخدامه مرة أخرى؛ تحتاج إلى إغلاقه وفتح الملف مرة أخرى للاختبار التالي. يمكن تحويل هذه الدالة arg إلى مثيل ArgRead باستخدام @arg_test arg begin ... end.

arg_writers([ type = ArgWrite ]) do path::String, arg::Function
    ## إعداد ما قبل الاختبار ##
    @arg_test arg begin
        arg :: ArgWrite
        ## اختبار باستخدام `arg` ##
    end
    ## تنظيف ما بعد الاختبار ##
end

تأخذ دالة arg_writers كتلة do، والتي يتم استدعاؤها مرة واحدة لكل نوع كاتب اختبار يمكن أن يتعامل معه arg_write مع path مؤقت (غير موجود) و arg الذي يمكن تحويله إلى أنواع وسائط قابلة للكتابة مختلفة تكتب إلى path. إذا تم إعطاء الوسيطة الاختيارية type، فإن كتلة do يتم استدعاؤها فقط للكتاب الذين ينتجون وسائط من هذا النوع.

الـ arg الممرر إلى كتلة do ليس قيمة الوسيطة نفسها، لأن بعض أنواع الوسائط الاختبارية تحتاج إلى التهيئة والانتهاء لكل حالة اختبار. اعتبر وسيطة مقبض ملف مفتوح: بمجرد أن تستخدمه لاختبار واحد، لا يمكنك استخدامه مرة أخرى؛ تحتاج إلى إغلاقه وفتح الملف مرة أخرى للاختبار التالي. يمكن تحويل هذه الدالة arg إلى مثيل ArgWrite باستخدام @arg_test arg begin ... end.

هناك أيضًا طريقة arg_writers تأخذ اسم مسار مثل arg_readers:

arg_writers(path::AbstractString, [ type = ArgWrite ]) do arg::Function
    ## إعداد ما قبل الاختبار ##
    @arg_test arg begin
        # هنا `arg :: ArgWrite`
        ## اختبار باستخدام `arg` ##
    end
    ## تنظيف ما بعد الاختبار ##
end

تكون هذه الطريقة مفيدة إذا كنت بحاجة إلى تحديد path بدلاً من استخدام اسم المسار الذي تم إنشاؤه بواسطة tempname(). نظرًا لأن path يتم تمريره من خارج arg_writers، فإن المسار ليس وسيطة في كتلة do في هذا الشكل.

@arg_test arg1 arg2 ... body

تُستخدم ماكرو @arg_test لتحويل دوال arg المقدمة من arg_readers و arg_writers إلى قيم فعلية للوسائط. عندما تكتب @arg_test arg body، فإنها تعادل arg(arg -> body).