קלט/פלט

format

מצהיר על תבנית דו״ח מבוססת תמונה לשימוש על ידי write.

format היא הצהרה, לא משפט בר־ביצוע. היא כובלת תמונה בשם - בלוק של שורות פלט בעמודות קבועות עם סמני שדה משובצים - לטבלת הסמלים, שם write מאוחר יותר מאתר אותה בשמה. תמונות אינן מבצעות אינטרפולציה של משתנים; אחרי כל שורת תמונה באה שורת ארגומנטים שביטוייה ממלאים את השדות לפי הסדר. format היא תכונה ישנה של Perl; המקור מציין ששימושה מוגבל ומפנה אל perlform לדקדוק השדה המלא.

תקציר

format NAME =
FORMLIST
.

format =          # declares the "STDOUT" format
FORMLIST
.

FORMLIST היא רצף של שורות, כל אחת משלושה סוגים: הערה (# בעמודה 1), שורת תמונה, או שורת ארגומנטים המספקת ערכים לשורת התמונה שמעליה מיד. . יחיד בעמודה 1 מסיים את ההצהרה.

מה מקבלים בחזרה

format היא הצהרה ואין לה ערך זמן ריצה. היא מתקינה את התמונה המהודרת לטבלת ה־format של החבילה הנוכחית תחת NAME (או STDOUT אם NAME מושמט). היא אינה נקראת; היא מופעלת בעקיפין על ידי write.

חלקיה של תמונה

כל שורת תמונה מערבבת טקסט מילולי עם סמני שדה. שדה מתחיל ב־@ (שדה רגיל) או ב־^ (שדה מיוחד, בשימוש עבור מצב מילוי ועבור שדות מספריים ניתנים לריקון) ומשתרע דרך תווי מרווח הקובעים גם את הרוחב וגם את היישור:

• < - טקסט מיושר לשמאל

• > - טקסט מיושר לימין

• | - טקסט ממורכז

• # - מספרי מיושר לימין; 0 מוביל ממלא באפסים; . ממקם את הנקודה העשרונית

• ... - בסוף של שדה טקסט, מציג שלוש נקודות כאשר הערך נקטם

• @* - שדה ברוחב משתנה המנפיק סקלר מרובה שורות מילולית

• ^* - שדה ברוחב משתנה המנפיק את השורה הבאה של סקלר וצורך את אותו חלק של משתנה המקור

שני אסימוני דיכוי עשויים להופיע בכל מקום בשורת תמונה ואינם חלק משדה כלשהו:

• ~ - אם כל שדה בשורה הזאת ריק, השורה מדוכאת לחלוטין; ה־~ עצמו מוצג כרווח אחרת

• ~~ - כמו ~, ובנוסף חוזר על השורה עד שכל שדה בה מוצה (כל סקלר מקור ריק או כל ביטוי בסגנון shift מחזיר undef)

perlform.pod נותן את הדקדוק המלא של שורות תמונה כולל מצב מילוי, שדות מרובי שורות, גלישה (####), ונקודות עשרוניות תלויות locale.

שורת הארגומנטים

השורה שמיד מתחת לשורת תמונה היא שורת הארגומנטים: רשימה מופרדת בפסיקים של ביטויים, אחד לכל שדה, מוערכת בהקשר רשימה לפני שהתמונה מוצגת. ביטוי יחיד המחזיר רשימה עשוי למלא שדות מרובים. רשימת הארגומנטים יכולה להיות מפוצלת על פני שורות אם ורק אם האסימון הראשון בשורה הראשונה הוא סוגר מסולסל פתיחה:

format Report =
@<<<<<<<< @>>>>>>
{ $name,
  $score }
.

גלובלים השולטים על write

פלט דרך format מונע לחלוטין על ידי גלובלים לכל מטפל קובץ. כל אחד מצורף ל־מטפל הקובץ הנבחר הנוכחי; שינוים עבור מטפל אחר דורש ריקוד select (ראו להלן):

• $~ - שם ה־format הנוכחי בשימוש עבור כל רשומה (ברירת מחדל היא שם מטפל הקובץ עצמו)

• $^ - שם ה־format הנוכחי של ראש העמוד (ברירת מחדל היא שם מטפל הקובץ עם _TOP מצורף)

• $= - אורך העמוד בשורות (ברירת מחדל 60)

• $- - שורות שנותרו בעמוד הנוכחי; write מקטין אותו ומפעיל את format ראש העמוד כשהוא מגיע לאפס

• $% - מספר העמוד הנוכחי, מוגדל אוטומטית

• $: - תווים שמצב מילוי (^) רשאי לשבור עליהם (ברירת מחדל " \n-")

• $^L - מחרוזת המונפקת לפני כל ראש עמוד למעט הראשון (ברירת מחדל "\f")

תחת use English אלה הם $FORMAT_NAME, $FORMAT_TOP_NAME, $FORMAT_LINES_PER_PAGE, $FORMAT_LINES_LEFT, $FORMAT_PAGE_NUMBER, $FORMAT_LINE_BREAK_CHARACTERS, ו־$FORMAT_FORMFEED.

מכיוון שאלה לכל מטפל, הגדרתם עבור מטפל אחר מהנבחר הנוכחי דורשת select:

my $ofh = select $fh;
$~ = 'Report';
$^ = 'Report_TOP';
select $ofh;

ראש־טופס

כש־write מקטין את $- לאפס, הוא מנפיק את $^L (למעט בעמוד הראשון ממש), מאפס את $- ל־$=, מגדיל את $%, ומפעיל את ה־format ששמו ב־$^. שם format ראש העמוד בברירת מחדל הוא שם מטפל הקובץ עם _TOP מצורף, כך שהצהרה על STDOUT_TOP מספיקה לכתיבות דרך STDOUT.

דוגמאות

דו״ח מינימלי עם כותרת:

format STDOUT_TOP =
        Inventory
Name            Qty   Price
----------------------------
.
format STDOUT =
@<<<<<<<<<<<<<  @>>  @##.##
$name,          $qty, $price
.

for my $row (@rows) {
    ($name, $qty, $price) = @$row;
    write;
}

החלפת formats עבור מטפל שאינו נבחר:

open my $fh, '>', 'report.txt' or die $!;
my $ofh = select $fh;
$~ = 'Report';
$^ = 'Report_TOP';
select $ofh;
write $fh;

מצב מילוי עם ~~ לריקון סקלר מרובה שורות שורה בכל פעם:

format STDOUT =
Note: ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
      $note
~~    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
      $note
.

השדות ^ צורכים את $note תוך כדי הצגתם; שורת ה־~~ חוזרת עד ש־$note ריק.

מקרי קצה

• נראות לקסיקלית: format רואה משתנה my רק כאשר היא מוצהרת בתוך התיחום של אותו משתנה. format ברמת על אינה יכולה לראות משתני my שהוצהרו בתוך תת־שגרה; יש להשתמש בגלובלי חבילה או להצהיר על ה־format בתוך התת־שגרה.

• תמונות מצוטטות: אם בונים תמונה עם eval ממחרוזת בגרשיים כפולים, @name נראה כאינטרפולציית מערך. יש לבצע escape או להשתמש בגרשיים יחידים סביב התבנית.

• . בודד הוא הסיומת: תמונה שטקסטה המילולי יתחיל ב־. בעמודה 1 חייבת להזיח את אותה שורה. זה גם נושך קוד format הנשלח דרך תעבורות דואר נאיביות החותכות ב־. בשורה משלו.

• גלישה מספרית: שדה # צר יותר מהמספר המעוצב מוצג כ־#### במקום קטימה שקטה.

• נקודה עשרונית של locale: אם use locale היה בתוקף כש־format הוצהר, LC_NUMERIC בוחר את התו העשרוני. החלפת use locale בזמן write אינה משנה את התמונה.

• תווי בקרה בתוך שדה טקסט ברוחב קבוע מוחלפים ברווחים כדי לשמר יישור עמודות.

• ערבוב print ו־write: חוקי על אותו מטפל, אך $- עוקב רק אחר שורות שהונפקו על ידי write. יש להתאים את $- ידנית אם פלט print משולב צורך שורות עמוד שחשוב לכם.

• אין מנגנון כותרת תחתונה: אין $FORMAT_BOTTOM_NAME. כותרות תחתונות נעשות ביד - יש לבדוק את $- לפני כל write ולהנפיק את הכותרת התחתונה בעצמכם כשהוא מגיע לסף.

הבדלים מהמקור

תואם במלואו ל־Perl 5.42 במקור.

ראו גם

• write - מציג רשומה אחת דרך ה־format הנוכחי לתוך מטפל הקובץ הנבחר; הדרך היחידה ש־format מוצהר מייצרת פלט

• select - משנה איזה מטפל קובץ הוא הנוכחי, נדרש בעת הגדרת $~, $^, $=, $-, $%, $:, או $^L עבור מטפל שאינו STDOUT

• $~ - שם ה־format הנוכחי

• $^ - שם ה־format הנוכחי של ראש העמוד

• $= - אורך עמוד

• $- - שורות שנותרו בעמוד הנוכחי

• $% - מספר העמוד הנוכחי

• $: - תווי שבירה של מצב מילוי

• perlform.pod - דקדוק מלא של שורות תמונה, כללי מצב מילוי, formline / $^A פנימיים, ודוגמאות דו״ח מפורטות