سيارة التحكم عن بُعد

الدوال

يمكنك تعريف دوال مخصّصة بنفسك في jq لتغلّف بها أي منطق تحتاجه. تعمل الدوال تمامًا كما تعمل الدوال المدمجة: فهي تأخذ مدخلًا وتُنتج صفرًا أو مخرجًا واحدًا أو أكثر.

تعريف دالة

يمكنك تعريف دالة في jq باستخدام الصيغة التالية:

# no arguments
def funcname: expression;

# or with arguments
def funcname(args): expression;

• تبدأ بكلمة def المفتاحية،
• ونقطتان قبل جسم الدالة،
• ويتكوّن الجسم من تعبير واحد،
• وتنتهي بفاصلة منقوطة،
• وكما في بقية صيغة jq، يمكنك استخدام أي مسافات بيضاء لتحسين القراءة.

أين توضع الدوال

يجب تعريف الدوال قبل استخدامها: فما يلي خطأ:

def A: B(10);
def B(n): n + 1;
A
# => error: B/1 is not defined

وهذا يعني أنه يجب عليك وضع الدوال في أعلى كود jq، قبل التعبير «الرئيسي».

الدوال المتداخلة

يمكن أن تكون الدوال متداخلة:

def A:
    def B(n): n + 1;
    B(10)
    ;
A
# => 11

هنا لا تظهر دالة B إلا داخل جسم A.

النطاق

تُنشئ الدالة نطاقًا جديدًا للمتغيرات والدوال المتداخلة.

الوسائط

وسائط الدالة تُفصل بفواصل منقوطة لا بفواصل. على سبيل المثال، دالة تأخذ عددًا، ثم تضيف إليه عددًا وتضرب الناتج في عدد:

def add_mul(adder; multiplier): (. + adder) * multiplier;

10 | add_mul(5; 4)    # => 60

10 | add_mul(5, 4)
# error: add_mul/1 is not defined

الوسائط هي تعبيرات

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

باستخدام دالة add_mul كمثال:

10 | add_mul(. + 5; . - 2)    # => 200

ما الذي يحدث هنا؟

• يحصل الوسيط adder على التعبير . + 5
  • فعندما تنفّذ الدالة . + adder، يصبح ذلك . + . + 5
  • ويُقيَّم ذلك إلى 25 بما أن . == 10
• وبالمثل، الوسيط multiplier هو التعبير . - 2
  • ويُقيَّم ذلك إلى 8
  • ثم تكون النتيجة 25 * 8 == 200

الوسائط كقيم

أحيانًا قد ترغب في «تجسيد» وسيط في متغير:

def my_func(arg):
    arg as $arg
    | other stuff ...
;

وهناك صيغة مختصرة لذلك:

def my_func($arg):
    other stuff ...
;

لاحظ أن هذا مجرّد «سكر نحوي»: فالاسم arg بدون $ لا يزال ضمن النطاق في الدالة.

عدد الوسائط

للدوال عدد وسائط، أي عدد الوسائط التي تأخذها.

ويمكن للدوال أن تستخدم الاسم نفسه بعدد مختلف من الوسائط. وتوضّح دالة range المدمجة ذلك: فالدوال range/1 وrange/2 وrange/3 تتعايش جميعًا.

قد يكون هذا مفيدًا لتعريف دوال عودية تحمل حالتها عبر الوسائط. على سبيل المثال، يمكن تنفيذ map هكذا:

def my_map($accumulator; func):
    if length == 0
        then $accumulator
        else first as $elem | .[1:] | my_map($accumulator + [$elem | func]; func)
    end
    ;

def my_map(func):
    my_map([]; func)
    ;

[1, 2, 3, 4] | my_map(. * 10)   # => [10, 20, 30, 40]

العودية

يُجري jq تحسين الاستدعاء الذيلّي، لكن للدوال ذات عدد الوسائط صفر فقط.

الوحدات

وحدة jq هي ملف لا يحتوي إلا على دوال. وتُضمّ الوحدات إلى برنامج jq بأمرَي include أو import.