اشیاء shlex¶

یک نمونه از shlex متدهای زیر را دارد:

shlex.get_token()¶

یک توکن برمی‌گرداند. اگر توکن‌ها با استفاده از push_token() در پشته قرار گرفته باشند، یک توکن را از پشته خارج می‌کند. در غیر این صورت، یکی را از جریان ورودی می‌خواند. اگر خواندن بلافاصله با پایان پرونده مواجه شود، eof برگردانده می‌شود (رشته خالی ('') در حالت غیر POSIX و None در حالت POSIX).

shlex.push_token(str)¶

آرگومان را روی پشته‌ی توکن قرار دهید.

shlex.read_token()¶

یک توکن خام را بخوانید. پشته‌ی پس‌زدن (pushback stack) را نادیده بگیرید و درخواست‌های منبع را تفسیر نکنید. (این معمولاً نقطه‌ی ورود مفیدی نیست و تنها به‌خاطر کامل بودن در اینجا مستند شده است.)

shlex.sourcehook(filename)¶

هنگامی که shlex یک درخواست منبع را تشخیص می‌دهد (به source در زیر مراجعه کنید)، این متد توکن بعدی را به‌عنوان آرگومان دریافت می‌کند و انتظار می‌رود یک تاپل شامل یک نام پرونده و یک شیء شبه‌پرونده باز را برگرداند.

به‌طور معمول، این متد ابتدا هرگونه علامت نقل‌قول اطراف آرگومان را حذف می‌کند. اگر نتیجه یک مسیر مطلق باشد، یا هیچ درخواست منبع قبلی‌ای فعال نباشد، یا منبع قبلی یک جریان (مانند sys.stdin) باشد، نتیجه بدون تغییر باقی می‌ماند. در غیر این صورت، اگر نتیجه یک مسیر نسبی باشد، بخش پوشه از نام پرونده‌ای که بلافاصله قبل از آن در پشته‌ی درج منبع قرار دارد، به ابتدای آن افزوده می‌شود (این رفتار مشابه روشی است که پیش‌پردازنده‌ی C با #include "file.h" برخورد می‌کند).

نتیجه‌ی دستکاری‌ها به‌عنوان یک نام پرونده در نظر گرفته می‌شود و به‌عنوان اولین کامپوننت تاپل برگردانده می‌شود، و open() روی آن فراخوانی می‌شود تا کامپوننت دوم را به دست دهد. (توجه: این، معکوس ترتیب آرگومان‌ها در مقداردهی اولیه نمونه است!)

این قلاب در دسترس قرار گرفته است تا بتوانید از آن برای پیاده‌سازی مسیرهای جستجوی پوشه، افزودن پسوندهای پرونده و سایر ترفندهای فضای نام استفاده کنید. هیچ قلاب 'close' متناظری وجود ندارد، اما یک نمونه از shlex، هنگامی که جریان ورودی منبع EOF را برگرداند، متد close() آن را فراخوانی می‌کند.

برای کنترل صریح‌تر پشته‌سازی منبع، از متدهای push_source() و pop_source() استفاده کنید.

shlex.push_source(newstream, newfile=None)¶

یک جریان منبع ورودی را روی پشته ورودی قرار می‌دهد. اگر آرگومان filename تعیین شده باشد، بعداً برای استفاده در پیام‌های خطا در دسترس خواهد بود. این همان متدی است که به‌صورت داخلی توسط متد sourcehook() استفاده می‌شود.

shlex.pop_source()¶

آخرین منبع ورودی واردشده به پشته را از پشته ورودی بردارید. این همان متدی است که به‌صورت داخلی هنگامی استفاده می‌شود که تحلیل‌گر واژگانی (lexer) در یک جریان ورودی پشته‌ای به EOF برسد.

shlex.error_leader(infile=None, lineno=None)¶

این متد یک سرآغاز پیام خطا در قالب برچسب خطای کامپایلر C یونیکس تولید می‌کند؛ قالب به‌صورت '"%s", line %d: ' است، که در آن %s با نام پرونده منبع جاری و %d با شماره خط ورودی جاری جایگزین می‌شود (می‌توان از آرگومان‌های اختیاری برای بازنویسی این مقادیر استفاده کرد).

این سهولت فراهم شده است تا کاربران shlex تشویق شوند پیام‌های خطا را در قالب استاندارد و قابل‌تجزیه‌ای تولید کنند که Emacs و سایر ابزارهای Unix آن را درک می‌کنند.

نمونه‌های زیرکلاس‌های shlex دارای چند متغیر نمونه عمومی هستند که یا تحلیل واژگانی را کنترل می‌کنند یا می‌توان از آن‌ها برای اشکال‌زدایی استفاده کرد:

shlex.commenters¶

رشته‌ای از نویسه‌ها که به‌عنوان آغازگرهای توضیح شناخته می‌شوند. تمام نویسه‌ها از آغازگر توضیح تا پایان خط نادیده گرفته می‌شوند. به‌طور پیش‌فرض فقط شامل '#' است.

shlex.wordchars¶

رشته‌ای از نویسه‌ها که برای تشکیل توکن‌های چند نویسه‌ای انباشته می‌شوند. به‌طور پیش‌فرض، شامل تمام نویسه‌های الفباعددی ASCII و زیرخط می‌شود. در حالت POSIX، نویسه‌های لهجه‌دار در مجموعه Latin-1 نیز گنجانده می‌شوند. اگر punctuation_chars خالی نباشد، نویسه‌های ~-./*?=، که می‌توانند در مشخصات نام پرونده و پارامترهای خط فرمان ظاهر شوند، نیز در این ویژگی گنجانده می‌شوند و هر نویسه‌ای که در punctuation_chars ظاهر شود، در صورت وجود در wordchars، از آن حذف می‌شود. اگر whitespace_split روی True تنظیم شده باشد، این مورد بی‌اثر خواهد بود.

shlex.whitespace¶

تویسه‌هایی که فضای سفید در نظر گرفته می‌شوند و نادیده گرفته خواهند شد. فضای سفید مرز توکن‌ها را مشخص می‌کند. به‌طور پیش‌فرض، شامل فاصله، تب، تغذیه سطر و بازگشت به ابتدای سطر است.

shlex.escape¶

نویسه‌هایی که به‌عنوان نویسه‌های خنثی‌کننده در نظر گرفته می‌شوند. این مورد فقط در حالت POSIX استفاده می‌شود و به‌طور پیش‌فرض فقط شامل '\' است.

shlex.quotes¶

نویسه‌هایی که به‌عنوان علامت‌های نقل‌قول رشته در نظر گرفته می‌شوند. توکن تا زمانی که دوباره همان علامت نقل‌قول مشاهده شود انباشته می‌شود (بنابراین، انواع مختلف علامت‌های نقل‌قول، مانند پوسته، از یکدیگر محافظت می‌کنند). به‌طور پیش‌فرض، شامل علامت‌های نقل‌قول تکی و دوتایی ASCII است.

shlex.escapedquotes¶

نویسه‌های موجود در quotes که نویسه‌های خنثی‌کننده‌ی تعریف‌شده در escape را تفسیر می‌کنند. این مورد فقط در حالت POSIX استفاده می‌شود و به‌طور پیش‌فرض فقط شامل '"' است.

shlex.whitespace_split¶

اگر True باشد، توکن‌ها فقط بر اساس فضای سفید جدا می‌شوند. این قابلیت مفید است، برای مثال، برای تجزیه سطرهای فرمان با shlex و دریافت توکن‌ها به شیوه‌ای مشابه آرگومان‌های پوسته. هنگامی که همراه با punctuation_chars استفاده شود، توکن‌ها علاوه بر آن نویسه‌ها، بر اساس فضای سفید نیز جدا می‌شوند.

تغییر یافته در نسخه‌ی 3.8: ویژگی punctuation_chars با ویژگی whitespace_split سازگار شد.

shlex.infile¶

نام پرونده ورودی فعلی، که در ابتدا در زمان نمونه‌سازی کلاس تنظیم شده یا توسط درخواست‌های منبع بعدی روی پشته قرار گرفته است. بررسی این مقدار ممکن است هنگام ساخت پیام‌های خطا مفید باشد.

shlex.instream¶

جریان ورودی‌ای که این نمونه‌ی shlex نویسه‌ها را از آن می‌خواند.

shlex.source¶

این ویژگی به‌طور پیش‌فرض None است. اگر یک رشته به آن انتساب دهید، آن رشته به‌عنوان یک درخواست درج در سطح واژگانی مشابه کلیدواژه source در پوسته‌های مختلف تشخیص داده می‌شود. یعنی توکن بلافاصله بعدی به‌عنوان نام پرونده باز می‌شود و ورودی تا EOF از آن جریان دریافت می‌شود؛ در آن نقطه، متد close() آن جریان فراخوانی می‌شود و منبع ورودی دوباره جریان ورودی اصلی خواهد شد. درخواست‌های منبع می‌توانند تا هر تعداد سطحی روی هم انباشته شوند.

shlex.debug¶

اگر این ویژگی عددی و 1 یا بیشتر باشد، نمونه‌ای از shlex خروجی پیشرفت پرجزئیاتی درباره‌ی رفتار آن چاپ می‌کند. اگر نیاز به استفاده از این دارید، می‌توانید کد منبع ماژول را بخوانید تا جزئیات را بیاموزید.

shlex.lineno¶

شماره خط منبع (تعداد سطرهای جدید دیده‌شده تاکنون به‌علاوه یک).

shlex.token¶

بافر توکن (token buffer). ممکن است بررسی این مورد هنگام گرفتن استثناها مفید باشد.

shlex.eof¶

توکنی که برای تعیین پایان پرونده به کار می‌رود. این مقدار در حالت غیر POSIX به رشته‌ی خالی ('') و در حالت POSIX به None تنظیم می‌شود.

shlex.punctuation_chars¶

یک ویژگی فقط‌خواندنی. نویسه‌هایی که به‌عنوان نمادگذاری تلقی می‌شوند. دنباله‌های پیوسته‌ای از نویسه‌های نمادگذاری به‌عنوان یک توکن واحد بازگردانده خواهند شد. با این حال، توجه داشته باشید که هیچ‌گونه بررسی صحت معنایی انجام نخواهد شد: برای مثال، ممکن است '>>>' به‌عنوان یک توکن بازگردانده شود، حتی اگر پوسته‌ها آن را به‌عنوان چنین توکنی نشناسند.

اضافه شده در نسخه‌ی 3.6.

قواعد تجزیه¶

هنگام کار در حالت non-POSIX، shlex سعی می‌کند از قوانین زیر پیروی کند.

• نویسه‌های نقل‌قول درون کلمات تشخیص داده نمی‌شوند (Do"Not"Separate به‌عنوان کلمه‌ی واحد Do"Not"Separate تجزیه می‌شود)؛

• نویسه‌های خنثی‌سازی شناسایی نمی‌شوند؛

• قرار دادن نویسه‌ها درون علامت‌های نقل‌قول، مقدار لفظی تمام نویسه‌های درون علامت‌های نقل‌قول را حفظ می‌کند؛

• علامت‌های نقل‌قول پایانی، واژه‌ها را جدا می‌کنند ("Do"Separate به‌صورت "Do" و Separate تجزیه می‌شود)؛

• اگر whitespace_split برابر False باشد، هر نویسه‌ای که به‌عنوان نویسه کلمه‌ای، فضای سفید یا علامت نقل‌قول اعلام نشده باشد، به‌صورت یک توکن تک‌نویسه‌ای برگردانده می‌شود. اگر True باشد، shlex فقط کلمات را بر اساس فضای سفید جدا می‌کند؛

• EOF با یک رشته خالی ('') اعلام می‌شود؛

• تجزیه‌ی رشته‌های خالی ممکن نیست، حتی اگر داخل علامت نقل‌قول باشند.

هنگام کار در حالت POSIX، shlex تلاش می‌کند از قواعد تجزیه زیر پیروی کند.

• علامت‌های نقل‌قول حذف می‌شوند و کلمات را جدا نمی‌کنند ("Do"Not"Separate" به‌عنوان کلمه‌ی واحد DoNotSeparate تجزیه می‌شود)؛

• نویسه‌های خنثی‌سازی بدون علامت نقل‌قول (مثلاً '\') مقدار لفظی نویسه‌ای که پس از آن‌ها می‌آید را حفظ می‌کنند؛

• قراردادن نویسه‌ها درون علامت‌های نقل‌قولی که بخشی از escapedquotes نیستند (مانند "'") مقدار لفظی همه نویسه‌های درون علامت‌های نقل‌قول را حفظ می‌کند؛

• دربرگرفتن نویسه‌ها با علامت‌های نقل‌قولی که بخشی از escapedquotes هستند (مثلاً '"')، مقدار لفظی همه نویسه‌های درون علامت‌های نقل‌قول را حفظ می‌کند، به‌جز نویسه‌های ذکرشده در escape. نویسه‌های خنثی‌سازی معنای ویژه خود را فقط زمانی حفظ می‌کنند که پس از آن‌ها علامت نقل‌قول مورد استفاده یا خود نویسه خنثی‌سازی بیاید. در غیر این صورت، نویسه خنثی‌سازی یک نویسه معمولی در نظر گرفته می‌شود.

• پایان پرونده با مقدار None اعلام می‌شود؛

• رشته‌های خالی داخل علامت نقل‌قول ('') مجاز هستند.

بهبود سازگاری با پوسته‌ها¶

کلاس shlex سازگاری با تجزیه‌ای را فراهم می‌کند که پوسته‌های رایج یونیکس مانند bash، dash و sh انجام می‌دهند. برای بهره‌مندی از این سازگاری، آرگومان punctuation_chars را در سازنده مشخص کنید. مقدار پیش‌فرض آن False است که رفتار پیش از 3.6 را حفظ می‌کند. با این حال، اگر روی True تنظیم شود، تجزیه نویسه‌های ();<>|& تغییر می‌کند: هر دنباله‌ای از این نویسه‌ها به‌عنوان یک توکن واحد بازگردانده می‌شود. هرچند این قابلیت به‌اندازه یک پارسر کامل برای پوسته‌ها نیست (که با توجه به تعدد پوسته‌های موجود، خارج از حیطه کتابخانه استاندارد خواهد بود)، اما به شما امکان می‌دهد پردازش سطرهای فرمان را آسان‌تر از آنچه در غیر این صورت ممکن بود انجام دهید. برای نمایش، می‌توانید تفاوت را در قطعه کد زیر ببینید:

>>> import shlex
>>> text = "a && b; c && d || e; f >'abc'; (def \"ghi\")"
>>> s = shlex.shlex(text, posix=True)
>>> s.whitespace_split = True
>>> list(s)
['a', '&&', 'b;', 'c', '&&', 'd', '||', 'e;', 'f', '>abc;', '(def', 'ghi)']
>>> s = shlex.shlex(text, posix=True, punctuation_chars=True)
>>> s.whitespace_split = True
>>> list(s)
['a', '&&', 'b', ';', 'c', '&&', 'd', '||', 'e', ';', 'f', '>', 'abc', ';',
'(', 'def', 'ghi', ')']

البته، توکن‌هایی برگردانده خواهند شد که برای پوسته‌ها معتبر نیستند، و شما باید بررسی‌های خطای خودتان را روی توکن‌های برگردانده‌شده پیاده‌سازی کنید.

به‌جای ارسال True به‌عنوان مقدار پارامتر punctuation_chars، می‌توانید رشته‌ای با نویسه‌های مشخص را ارسال کنید که برای تعیین اینکه کدام نویسه‌ها نمادگذاری محسوب می‌شوند، استفاده خواهد شد. برای مثال:

>>> import shlex
>>> s = shlex.shlex("a && b || c", punctuation_chars="|")
>>> list(s)
['a', '&', '&', 'b', '||', 'c']

>>> import shlex
>>> s = shlex.shlex('~/a && b-c --color=auto || d *.py?',
...                 punctuation_chars=True)
>>> list(s)
['~/a', '&&', 'b-c', '--color=auto', '||', 'd', '*.py?']

برای بهترین نتیجه، punctuation_chars باید همراه با posix=True تنظیم شود. (توجه داشته باشید که posix=False برای shlex پیش‌فرض است.)