لقراءة محتويات ملف Markdown محلي في اختصارات Mac، حوّل إدخال الملف إلى نص قبل استخدامه. تحقّق من النتيجة باستخدام عيّنة مؤقتة؛ وإذا فشل التحويل، فاقرأ الملف باستخدام cat وأرسل محتوياته إلى الاختصار عبر أنبوب.

هذا الشرح مخصص لاختيار ملف Markdown محلي واحد في Finder وعرض نصه المصدر حرفيًا، بما في ذلك علامات العناوين وعلامات الترقيم في القوائم. والتمييز المهم هنا هو بين ثلاثة أشياء: الملف المحدد، ومسار الملف، والنص المخزن داخله.

لماذا يتلقى الاختصار ملفًا بدلًا من نصه؟

يوفر Finder إدخالًا من نوع ملف. وتعرّف Apple نوعي الإدخال Files وText في الاختصارات كنوعين منفصلين: فقد يكون الملف مستندًا من أي نوع، بينما النص هو نص عادي بلا تنسيق مطبّق. لذلك، فإن قبول ملف Markdown لا يعني بحد ذاته أن الإجراء التالي سيتلقى محتوياته كنص. فهم أنواع الإدخال في الاختصارات على Mac.

تستخدم الاختصارات محرك Content Graph للتحويل بين الأنواع عندما تتطلب الإجراءات ذلك. وتوثّق Apple أيضًا خيارًا صريحًا للتحكم في ذلك: انقر على رمز متغير وغيّر Type الخاص به. يختلف هذا التحويل عن اختيار خاصية مثل اسم الملف. فالاسم أو المسار لا يزال مجرد وصف للملف. محرك Content Graph، ضبط المتغيرات في الاختصارات على Mac.

يشرح دليل Apple المذكور آلية التحويل، لكنه لا يضمن تحويل كل ملف يحمل الامتداد .md إلى نصه المصدر. تعامل مع التحويل على أنه أمر يجب التحقق منه باستخدام محتوى معروف. وتوفر الطريقة المعتمدة على الأوامر أدناه مسارًا صريحًا لقراءة الملف إذا لم ينتج التحويل الأصلي النص المتوقع.

أنشئ ملف Markdown مؤقتًا بمحتوى معروف

استخدم هذه العيّنة الاصطناعية حتى لا يُظن خطأً أن ظهور اسم الملف يعني نجاح القراءة. الصق إعداد الإعداد الكامل في Terminal. فهو ينشئ مجلدًا مؤقتًا جديدًا، ويكتب ملفًا نموذجيًا واحدًا، ويفتح ذلك المجلد في Finder.

demo_dir=$(/usr/bin/mktemp -d /tmp/markdown-shortcuts.XXXXXX) &&
printf '%s\n' '# Sample board' '' '- Blue square' '- Green circle' > "$demo_dir/sample.md" &&
/usr/bin/open "$demo_dir"

محتويات الملف المتوقعة هي:

# Sample board

- Blue square
- Green circle

يخبر الخيار -d الأمر mktemp بإنشاء مجلد، وتتيح له أحرف X اللاحقة اختيار اسم فريد. لذلك، يحصل كل إعداد ناجح على مجلد جديد. وإذا فشل الإنشاء، تمنع سلسلة && تشغيل الأوامر اللاحقة. توزّع Apple الدليل mktemp المعني.

يكتب الأمر printf الأسطر الاصطناعية، بما فيها السطر الفارغ. وينشئ توجيه خرجه الملف sample.md داخل المجلد الجديد. يمكن لتوجيه الإخراج العادي > أن يستبدل ملفًا موجودًا، لذا أبقِ هذا الإعداد كما هو بدلًا من تغيير وجهته إلى مستند موجود. يوفر المجلد الجديد الحماية من تعارض الأسماء في هذا المثال. دليل Apple الخاص بـ printf، إدخال وإخراج الصدفة.

أنشئ اختصارًا في Finder يطلب النص صراحةً

أنشئ اختصارًا باسم Read Markdown Text. توثّق Apple إنشاء اختصار باستخدام زر الإضافة في شريط الأدوات، وتسميته، وإضافة إجراءات من مكتبة الإجراءات. إنشاء اختصار مخصص على Mac.

اضبط نقطة دخوله من Finder:

  1. افتح لوحة Details الخاصة بالاختصار.
  2. فعّل Use as Quick Action وحدد Finder.
  3. في كتلة الإدخال أعلى المحرر، اسمح بـ Files وText. تدعم الملفات سير العمل في Finder، بينما يدعم النص الطريقة البديلة عبر Terminal أدناه.
  4. في حالة عدم وجود إدخال، اختر Stop and Respond واكتب Select one example Markdown file.

توثّق Apple خيار Finder وتشير إلى أن إدخال ملف أو مجلد قد يكون ضروريًا لتمكينه. كما يتيح إعداد الإدخال إيقاف الاختصار مع إظهار رد عند عدم تلقي أي إدخال. تشغيل اختصار أثناء العمل على Mac، تحديد مدخلات الاختصار.

أضف الآن إجراءات معالجة المحتوى:

  1. أضف إجراء Text.
  2. ضع متغير Shortcut Input وحده في حقل النص.
  3. انقر على رمز ذلك المتغير، وافتح قائمة Type، ثم اختر Text. تجنب اختيار خاصية اسم الملف.
  4. أضف Quick Look بعد إجراء Text، مستخدمًا مخرجات إجراء Text.

يطلب تحويل المتغير الصريح نصًا عند استخدام الإدخال. ومخرجات إجراء Text التالية هي القيمة التي ينبغي استخدامها في خطوات معالجة النص اللاحقة. توثّق Apple تغيير أنواع المتغيرات عبر محرر المتغيرات. ضبط المتغيرات في الاختصارات على Mac.

للتأكد من السلوك في الإصدار المثبّت لديك، انقر مع الضغط على مفتاح Control على أيقونة أحد الإجراءات واختر Show Info. توثّق Apple هذه الطريقة لفحص المدخلات التي يقبلها الإجراء والمخرجات التي ينتجها. وهي مفيدة خصوصًا عند تعديل اختصار موجود يحتوي على عدة متغيرات للملفات والنصوص. التنقل في قائمة الإجراءات في الاختصارات على Mac.

في Finder، حدد sample.md فقط، وانقر عليه مع الضغط على Control، ثم اختر Quick Actions، وبعدها Read Markdown Text. توثّق Apple طريقة التشغيل هذه. إذا لم يظهر الاختصار، فتحقق أولًا من إعداد Finder وأنواع الإدخال المقبولة. تشغيل اختصار أثناء العمل على Mac.

تتضمن النتيجة الناجحة # Sample board وعنصري القائمة كليهما. أما ظهور sample.md وحده أو مسار مجلده فلا يجتاز هذا التحقق. توصي Apple بإدراج Quick Look بين الإجراءات لفحص المحتوى الذي يمر عبر الاختصار. اختبار الإجراءات في الاختصارات على Mac.

إذا فشل التحويل، فاقرأ المحتوى قبل استدعاء الاختصارات

استخدم Terminal لتوضيح عملية القراءة صراحةً. يشير دليل Apple لـ Terminal إلى أن cat أداة لعرض محتويات ملفات النصوص. ويميّز دليل سطر الأوامر للاختصارات بين إدخال الملف الممرر باستخدام -i والنص الممرر عبر أنبوب. عرض ملفات النصوص في Terminal على Mac، تشغيل الاختصارات من سطر الأوامر.

ما يلي استمرار لمثال الإعداد، وليس برنامجًا مستقلًا. شغّله في علامة تبويب Terminal نفسها بعد نجاح الإعداد، مع حفظ الاختصار بالاسم الدقيق Read Markdown Text:

(
    set -o pipefail

    if [ -f "$demo_dir/sample.md" ] && [ -r "$demo_dir/sample.md" ]; then
        /bin/cat "$demo_dir/sample.md" |
            /usr/bin/shortcuts run "Read Markdown Text"
    else
        printf '%s\n' 'The example file is missing or unreadable.' >&2
        exit 1
    fi
)

هنا، يقرأ cat الملف ويكتب محتوياته إلى المخرج القياسي. وينقل الأنبوب تلك المحتويات إلى الاختصار. ويضمن وضع المسار بين علامتي اقتباس بقاءه وسيطًا واحدًا. ويتطلب الفحصان -f و-r وجود ملف عادي قابل للقراءة. مدخل إلى سطر الأوامر، دليل Apple الخاص بـ test.

تحصر الأقواس تغيير خيار الصدفة في مجموعة الأوامر هذه. ويجعل pipefail فشل أي مرحلة من مراحل خط الأنابيب ظاهرًا في حالة خروج المجموعة. ولا تضمن الفحوص الأولية بقاء الملف متاحًا طوال عملية قراءة لاحقة؛ فإذا واجه cat خطأ في القراءة، فافحص ذلك الخطأ بدلًا من اعتبار معاينة جزئية مكتملة.

تغيّر هذه الطريقة البديلة المحتوى الوارد إلى الاختصار من ملف إلى نص. وهي لا تعيد تسمية ملف Markdown ولا تنشئ مستندًا محوّلًا. ويمكن لإجرائي Text وQuick Look الحاليين فحص هذا النص الوارد.

لهذه الأشكال الثلاثة من الأوامر معانٍ مختلفة:

شكل الأمر ما يتلقاه الاختصار
shortcuts run "Read Markdown Text" -i "$demo_dir/sample.md" إدخال ملف؛ ولا يزال التحويل مطلوبًا داخل الاختصار.
printf '%s\n' "$demo_dir/sample.md" | shortcuts run "Read Markdown Text" مسار الملف كنص.
cat "$demo_dir/sample.md" | shortcuts run "Read Markdown Text" محتويات الملف عبر الإدخال القياسي.

يوضح الجدول التمييز الذي توثّقه Apple بين تمرير مسارات الملفات باستخدام -i وتمرير النص عبر أنبوب. وتحدد العملية السابقة للأنبوب ما إذا كان ذلك النص مسارًا أم محتوى المستند. تشغيل الاختصارات من سطر الأوامر.

شخّص النتيجة قبل إضافة مزيد من الإجراءات

استخدم العيّنة المعروفة لتحديد ما يجب إصلاحه:

  • لا يظهر سوى اسم ملف: تحقق مما إذا كان المتغير يستخرج خاصية الاسم بدلًا من طلب النص.
  • لا يظهر سوى مسار: تحقق مما إذا كان الأمر يطبع المسار بدلًا من قراءة الملف.
  • يفشل التحويل الأصلي، لكن طريقة Terminal تعمل: استخدم طريقة القراءة الصريحة لسير العمل هذا؛ فتغيير تسمية الإدخال وحده لم يحل مشكلة التحويل.
  • لا يُستقبل أي إدخال: شغّل الاختصار من ملف Finder المحدد أو باستخدام أمر Terminal الموثّق. تشغيل اختصار من Dock لا يمرر الملف المحدد تلقائيًا.
  • المصدر فارغ: قارنه بالعيّنة. فالملف الفارغ الصالح يختلف عن الملف المفقود.

توثّق Apple خصائص المتغيرات على نحو منفصل عن تحويل نوع المحتوى، وتشير إلى أن الاختصارات المشغّلة من Dock قد لا تتلقى أي إدخال أولي. تساعد هذه الفروق على تحديد موضع الخلل قبل تغيير الإجراءات اللاحقة. ضبط المتغيرات في الاختصارات على Mac، تحديد مدخلات الاختصار.

أبقِ سير العمل مقتصرًا على ملف نصي محلي صغير واحد أثناء الاختبار. فالاختيار المتعدد يتطلب قرارًا منفصلًا بشأن معالجة كل ملف أو دمج محتوياته. يثبت هذا المثال إمكانية قراءة النص المصدر؛ وهو ليس إجراءً لنسخ الملف بايتًا ببايت.

بعد أن تعرض المعاينة العنوان والأسطر المدرجة المتوقعة، صِل إجراءات معالجة النص اللاحقة بمخرجات إجراء Text. أبقِ العيّنة الاصطناعية حتى يعمل المسار كاملًا، ثم احذف مجلدها المؤقت من Finder. نقطة التحقق الأساسية بسيطة: يجب أن يتلقى الإجراء التالي محتوى المستند الذي تحققت منه.

المصادر