regex(3)

الاسم
regcomp, regexec, regerror, regfree - دوال التعبير النمطي POSIX

المكتبة
مكتبة سي المعيارية (libc، -lc)

موجز
#include <regex.h>

int regcomp(regex_t *restrict preg, const char *restrict regex,
            int cflags);
int regexec(const regex_t *restrict preg,
            const char *restrict string,
            size_t n, regmatch_t pmatch[_Nullable restrict n],
            int eflags);

size_t regerror(size_t errbuf_size;
            int errcode, const regex_t *_Nullable restrict preg,
            char errbuf[_Nullable restrict errbuf_size],
            size_t errbuf_size);
void regfree(regex_t *preg);

typedef struct {
size_t    re_nsub;
} regex_t;

typedef struct {
regoff_t  rm_so;
regoff_t  rm_eo;
} regmatch_t;

typedef /* ... */  regoff_t;

الوصف

  التجميع
تُستخدم regcomp() لتجميع تعبير نمطي إلى صيغة مناسبة لعمليات بحث regexec() لاحقة.

عند النجاح، يُهيأ مخبأ النمط عند *preg. regex هي سلسلة محارف منتهية بقيمة خالية. يجب أن يكون الإعداد المحلي نفسه عند تشغيل regexec().

بعد نجاح regcomp() ، يحمل preg->re_nsub عدد التعبيرات الفرعية في regex. لذا، فإن قيمة preg->re_nsub + 1 الممررة كـ n إلى regexec() كافية لالتقاط جميع التطابقات.

cflags هو OR على مستوى البتات لصفر أو أكثر مما يلي:

REG_EXTENDED
    استخدم صيغة التعبير النمطي الموسع POSIX عند تفسير regex. إذا لم يُضبط، تُستخدم صيغة التعبير النمطي الأساسي POSIX.

REG_ICASE
    لا تفرق بين حالة الأحرف. ستكون عمليات بحث regexec() اللاحقة باستخدام مخبأ النمط هذا غير حساسة لحالة الأحرف.

REG_NOSUB
    أبلغ فقط عن النجاح الكلي. ستستخدم regexec() فقط pmatch لـ REG_STARTEND، متجاهلة n.

REG_NEWLINE
    لا تطابق عوامل تشغيل تطابق أي حرف سطرًا جديدًا.

    قائمة غير مطابقة ([^...]) لا تحتوي على سطر جديد لا تطابق سطرًا جديدًا.

    عامل مطابقة بداية السطر (^) يطابق السلسلة الفارغة فورًا بعد سطر جديد، بغض النظر عن احتواء eflags، أعلام تنفيذ regexec()، على REG_NOTBOL.

    عامل مطابقة نهاية السطر ($) يطابق السلسلة الفارغة فورًا قبل سطر جديد، بغض النظر عن احتواء eflags على REG_NOTEOL.

  المطابقة
تُستخدم regexec() لمطابقة سلسلة محارف منتهية بقيمة فارغة مع مخبأ النمط المُجمَّع في *preg، الذي يجب أن يكون قد تمت تهيئته باستخدام regcomp(). eflags هو OR على مستوى البت لصفر أو أكثر من الأعلام التالية:

REG_NOTBOL
    عامل مطابقة بداية السطر يفشل دائمًا في المطابقة (لكن انظر علم التجميع REG_NEWLINE أعلاه). يمكن استخدام هذا العلم عندما تُمرَّر أجزاء مختلفة من سلسلة محارف إلى regexec() ولا ينبغي تفسير بداية السلسلة على أنها بداية السطر.

REG_NOTEOL
    عامل مطابقة نهاية السطر يفشل دائمًا في المطابقة (لكن انظر علم التجميع REG_NEWLINE أعلاه).

REG_STARTEND
    يطابق [string + pmatch[0].rm_so, string + pmatch[0].rm_eo) بدلاً من [string, strnul(string)). يسمح هذا بمطابقة وحدات البايت NUL المُضمَّنة. إذا تم إرجاع أي مطابقات (لم يُمرَّر REG_NOSUB إلى regcomp()، نجحت المطابقة، و n > 0)، فإنها تستبدل pmatch كالمعتاد، وتبقى إزاحات المطابقة نسبة إلى string (وليس string + pmatch[0].rm_so). هذا العلم هو امتداد BSD، غير موجود في POSIX.

  إزاحات المطابقة
ما لم يُمرَّر REG_NOSUB إلى regcomp()، يمكن الحصول على مواقع المطابقات داخل string: تملأ regexec() عناصر n من pmatch بالنتائج: يتوافق pmatch[0] مع المطابقة بأكملها، و pmatch[1] مع أول تعبير فرعي، وهكذا. إذا كان هناك مطابقات أكثر من n، يتم التخلص منها؛ إذا كان أقل، تُملأ العناصر غير المستخدمة من pmatch بقيم -1.

كل مطابقة صالحة مُعادة (غير -1) تتوافق مع النطاق [string + rm_so, string + rm_eo).

regoff_t هو نوع عدد صحيح مُوقَّع قادر على تخزين أكبر قيمة يمكن تخزينها إما في نوع ptrdiff_t أو نوع ssize_t.

  الإبلاغ عن الأخطاء
تُستخدم regerror() لتحويل رموز الخطأ التي يمكن إرجاعها بواسطة كل من regcomp() و regexec() إلى سلاسل محارف لرسائل الخطأ.

إذا لم يكن preg مؤشرًا فارغًا، يجب أن يكون errcode أحدث خطأ تم إرجاعه من عملية على preg.

إذا لم يكن errbuf_size 0، يتم نسخ ما يصل إلى errbuf_size بايت إلى errbuf؛ سلسلة محارف الخطأ تكون دائمًا منتهية بقيمة فارغة، ومُقتطعة لتناسب.

  التحرير
regfree() تُنهي تهيئة مخزن النمط عند *preg، مُحررةً أي ذاكرة مرتبطة؛ يجب أن يكون *preg قد هُيئ عبر regcomp().

قيمة الإرجاع
regcomp() تُرجع صفرًا عند التجميع الناجح أو رمز خطأ عند الفشل.

regexec() تُرجع صفرًا عند المطابقة الناجحة أو REG_NOMATCH عند الفشل.

regerror() تُرجع حجم المخزن المطلوب لاحتواء سلسلة المحارف.

الأخطاء
يمكن إرجاع الأخطاء التالية بواسطة regcomp():

REG_BADBR
    استخدام غير صحيح لعامل المرجع الخلفي.

REG_BADPAT
    استخدام غير صحيح لعوامل النمط مثل المجموعة أو القائمة.

REG_BADRPT
    استخدام غير صحيح لعوامل التكرار مثل استخدام '*' كأول محرف.

REG_EBRACE
    عوامل نطاق الأقواس غير المتطابقة.

REG_EBRACK
    عوامل قائمة الأقواس غير المتطابقة.

REG_ECOLLATE
    عنصر ترتيب غير صحيح.

REG_ECTYPE
    اسم فئة محارف غير معروف.

REG_EEND
    خطأ غير محدد. هذا غير مُعرَّف بواسطة POSIX.

REG_EESCAPE
    شرطة مائلة عكسية زائدة.

REG_EPAREN
    عوامل مجموعة الأقواس غير المتطابقة.

REG_ERANGE
    استخدام غير صحيح لعامل النطاق؛ على سبيل المثال، تحدث نقطة نهاية النطاق قبل نقطة البداية.

REG_ESIZE
    يتطلب التعبير النمطي المُجمَّع مخزن نمط أكبر من 64 كيلوبايت. هذا غير مُعرَّف بواسطة POSIX.

REG_ESPACE
    نفدت الذاكرة من روتينات regex.

REG_ESUBREG
    مرجع خلفي غير صحيح لتعبير فرعي.

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
regcomp(), regexec() | سلامة الخيوط | المنطقة (locale) آمنة لتعدد المسالك (MT-Safe)
regerror() | سلامة الخيوط | بيئة آمنة لتعدد الخيوط (MT-Safe)
regfree() | سلامة الخيوط | MT-Safe

المعايير
POSIX.1-2008.

التاريخ
POSIX.1-2001.

قبل POSIX.1-2008، كان مطلوبًا من regoff_t أن يكون قادرًا على تخزين أكبر قيمة يمكن تخزينها في نوع off_t أو نوع ssize_t.

تحذيرات
re_nsub مطلوب فقط أن يُهيَّأ إذا لم يُحدد REG_NOSUB، لكن جميع التطبيقات المعروفة تُهيِّئه بغض النظر.

قد يحتوي كل من regex_t و regmatch_t على أعضاء إضافيين (ويفعلون ذلك)، بأي ترتيب. ارجع إليهم دائمًا بالاسم.

أمثلة
    #include <stdcountof.h>
    #include <stdint.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <regex.h>

    static const char *const str =
            "1) John Driverhacker;\n2) John Doe;\n3) John Foo;\n";
    static const char *const re = "John.*o";

    int main(void)
    {
        static const char *s = str;
        regex_t     regex;
        regmatch_t  pmatch[1];
        regoff_t    off, len;

        if (regcomp(&regex, re, REG_NEWLINE))
            exit(EXIT_FAILURE);

        printf("String = \"%s\"\n", str);
        printf("Matches:\n");

        for (unsigned int i = 0; ; i++) {
            if (regexec(&regex, s, countof(pmatch), pmatch, 0))
                break;

            off = pmatch[0].rm_so + (s - str);
            len = pmatch[0].rm_eo - pmatch[0].rm_so;
            printf("#%u:\n", i);
            printf("offset = %jd; length = %jd\n", (intmax_t) off,
                    (intmax_t) len);
            printf("substring = \"%.*s\"\n", len, s + pmatch[0].rm_so);

            s += pmatch[0].rm_eo;
        }

        exit(EXIT_SUCCESS);
    }

انظر أيضًا
grep(1), regex(7)

قسم دليل glibc، التعبيرات النمطية

ترجمة
تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.