API של אוריון - בנייה
Joe Schaefer
מערכת בנייה
מסמך זה מכסה את ממשקי API של מערכת הבנייה.
בעיקרון, מערכת הבנייה נשלטת על ידי שני מודולי Perl המסופקים על ידי המשתמש: lib/path.pm וגם lib/view.pm.
תפקידו של הראשון הוא לעשות שלושה דברים:
- טעינה
lib/facts.ymlוגםlib/acl.yml, - בנייה
@path::patterns, וגם - הליכה אופורטוניסטית
content/עץ לזרע%path::dependenciesוגם@path::aclsמטאדטה של כותרת קובץ markdown/yaml.
תפקידו של השני הוא לספק בלתי אפשרי. viewמבוסס $methods לרשומות תואמות ב- @path::patterns (כשם שיטה מחרוזת בחריץ השני של כל רשומת arrayref), הופעל על-ידי בניית תסריטים:
for my $p (@$patterns) {
my ($re, $method, $args) = @$p;
next unless $path =~ $re;
if ($args->{headers}) {
my Data::Dumper $d;
$d = $d->new([$args->{headers}], ['$args->{headers}']);
$d->Deepcopy(1);
$d->Purity(1);
eval $d->Dump;
}
my $s = $method_cache{$method} //= view->can($method) or die "Can't locate method: $method\n";
my $start_call = [gettimeofday];
no warnings 'once';
$view::path = $path;
my ($content, $ext, undef, @new_sources) = $s->(nonce => $nonce, website => $ENV{WEBSITE}, repos => $ENV{REPOS}, path => $path, lang => $lang, %$args);
my $elapsed = tv_interval($start_call);
if ($$args{compress}) {
$lang .= ".gz";
if (defined $content) {
utf8::encode($content) if utf8::is_utf8 $content;
gzip \($content, my $compressed);
$content = $compressed;
}
}
if (defined $content) {
my $dest = "$target_base/$target_file.$ext$lang";
my $encoding = $$args{encoding} // ($$args{compress} ? "raw" : "utf8");
my $mtime;
#$mtime = $_->mtime for map stat $_, "content/$path";
open my $fh, ">:$encoding", $dest
or die "Can't open $dest: $!\n";
print $fh $content;
close $fh;
#utime $mtime, $mtime, $dest if $mtime;
}
syswrite_all "Built to $target_base/$target_file.$ext$lang in ${elapsed}s.\n";
return @new_sources;
}
COPY:
my ($dest, $copied) = copy_if_newer $file, "$target_base/$file";
syswrite_all "Copied to $dest.\n" if $copied;
דעות רבות נועדו להיות מוערמות כמו “מסננים” להיבטי קדם-תהליך (או לאחר-תהליך) של הקובץ ב- $path זה רומן, כמו קוד חיצוני. snippets או asymptoteגושי סימון מגודרים. אתה יכול לראות דוגמה לכך. כאן.
SunStarSys::View — סיווג בסיס של lib/view.pm
הנוף הפופולרי ביותר (והמתוחכם)
תצוגה זו כוללת עיבוד אוטומטי של קבצים הנמצאים בתוך $path‘s ספריית מסמכים מצורפים’. במילים אחרות, אם $path = "/foo.md.en", לאחר מכן הקבצים המאוחסנים בתוך /foo.page/ הספרייה המקושרת עם “איפוס סיסמה” הרחבת השפה תשולב בארגומנטים המכתבים של התבנית עבור $path ללא קשר ל preprocess הגדרת הארגומנט — אשר, אם כן, יהפוך את החומר הזה לנגיש על ידי התוכן של הדף עצמו**.
Mandatory Arguments:
templatepathlang
Optional Argmuents:
deps— דריסה רגילהfetch_depsמעבדquick_deps— הגדרת אופטימיזציה של תהליך deps פנימי; שמאל מיטבי unsetpreprocess— מאפשר עיבוד תבנית בתוך$pathהתוכן עצמו,archive_root— קבצים ב- “הועבר לארכיב” הסטטוס הוא “הועתק” ומעקב לפי תיקיות משנה של שנה/חודש למיקום מבוסס תוכן זה באמצעותssi,category_root— פריטים ב- “קטגוריות” הכותרת היא “הועתק” מעבר לתיקיות קטגוריות בעלות שם מתאים במיקום מבוסס תוכן זה, דרךssi.
לבניית דפי index.html ו-sitemap.html
אינדקס יחסי תלות ספציפיים לאזור, ממוינים.
Mandatory Arguments:
pathlang
Optional Arguments:
quick_depsnestedpreprocess
בניות ומטמונים Asymptote בלוקים עם שלושה קודים במרכאות אחוריות עבור גרפיקה וקטורית התומכת ביריעה HTML5-WebGL
Mandatory Arguments:
viewlangpath
אל תבנו את זה בכלל.
במקום זאת, בנה את קובצי המקור המשויכים שנוצרו (למשל. .bib\$lang \$base.page/bibliography.yml\$lang) כדי לבנות על ריצת מערכת בנייה משנית.
המרת קובצי YAML, בדרך כלל ל-JSON.
Optional Arguments:
extברירת מחדל ל-jsonfilterברירת מחדל ל-json_rawtemplateדריסותfilterביטוי ברירת מחדל
המרת קובצי CSV, בדרך כלל ל־JSON.
Optional Arguments:
extברירת מחדל ל-jsonfilterברירת מחדל ל-json_rawtemplateדריסותfilterביטוי ברירת מחדל
פקטורים $data hashref של ארגומנט כ-rayref מסודר בחותמת זמן של arrayrefs של 2 רכיבים.
הרשומה הראשונה בכל arrayref של 2 רכיבים היא שם הנתיב של הקובץ, האלמנט השני הוא התוצאה. read_text_file Hashref לשם נתיב זה.
מחזיר רשימה של קובצי מקור חדשים שנוצרו אם $quick > 2.
Mandatory Arguments:
pathdata- קלט כ-hashref; מאחסן את ה-rayref המתקבל בתמורהquick- ברירת המחדל היא 2
מעבד קוד חיצוני שורות גזירבדרך כלל מייבאים את מיקומי המקור שלהם ב-GitHub לבלוקי markdown ספציפיים לשפת התכנות. דוגמה כאן.
מוסיף מחרוזת כותרת לקישורי סימון. בדרך כלל יש להשתמש תחת offline תצוגה כדי למנוע משיכה של כותרות מאתרים מרוחקים, מה שיכול לשים גרור משמעותי על זמני בניית הדף.
SunStarSys::Util — ספריית תוכניות שירות של lib/path.pm וגם lib/view.pm
מעבד קבצי הטקסט האוניברסלי של אוריון
מנתח כותרות + תוכן של קובץ מקודד UTF-8 $file מאחסן תוצאות ב-hashref $out. $content_lines הוא המספר המרבי (אופציונלי) של שורות תוכן לקריאה.
מחזיר את מספר השורות שנקראו בפועל (כולל כותרות).
$file עשויה להיות הפניה למחרוזת raw המייצגת את התוכן המלא של קובץ. התוצאות ב $out זה יהיה UTF-8 מקודד.
עותקים $src אל $dest אם חותמת הזמן של השינוי של הקודם היא חדשה יותר מזו של האחרון.
על עותק, בנוסף gzip-דחיסת $dest קובץ אם הוא קובץ טקסט, ומוסיף “.gz” הרחבה לשם. GZIP ניתן להשבית את הדחיסה על־ידי הגדרה $ENV{NO_COPY_COMPRESS}=1.
ממיין טבלאות Markdown ב- $content בהתאם למפרט העמודה של כל טבלה.
ניתן למיין בדיוק עמודה אחת לכל טבלה, כאופציה מספרית n, בסדר יורד v או בסדר עולה ^ פקודה
fixup_code($prefix, $type, @_)
רצועות $prefix מכל ויכוח ב @_.
המטרה של $type הארגומנט הוא ספציפי ליישום, אך משמש בעיקר לשתילתו editor.md "mode" לעיבוד תוכן זה ב- @_.
normalize_svn_path(@_)
מנרמל את כל הנתיבים ב- @_ לשימוש בטוח כארגומנטים גולמיים אל SVN::Client פקודות.
sanitize_relative_path(@_)
מאבטח נתיבים ב- @_ לשימוש כנתיבים יחסיים טהורים ב- Dotiac::DTL (תבנית Django) פקודות ספציפיות לנתיב.
Wrapper סביב File::Basename::fileparse. ללא טענות, שימושים $_ כמו שם הקובץ לפירוק.
על תנאי הולך ./content עץ הקופה של מערכת הבנייה; נרמול ראשון $_ כנתיב המשנה הרשמי המושרש בתוכן, ולאחר מכן בהפעלה $code->() על כל פריט בהליכת העץ.
עבור רוב המבנים, ההליכה לעולם לא מתרחשת. — במקום זאת, הבנייה מסתמכת על נתונים במטמון מבניות קודמות.
הדרך היחידה לכפות הליכה היא על ידי הגדרת $path::use_cache לערך false במודולים שסופקו על ידי המשתמש. אחרת התנהגות זו מנוהלת במומחיות על ידי טכנולוגיית בנייה מצטברת.
מחזיר 1 אם ההליכה אכן התקדמה, במקום להסתמך על נתונים במטמון. אחרת, מחזיר ערך false.
דגלים כל Status: archived $path (באופן טבעי) שימושים $_ אם לא הועברו ויכוחים.
העברה לארכיון של קובצי Markdown היא דרך טבעית לספר לאוריון “הפסק לשים לב למיקום המקושר לקובץ זה”, אלא אם כן יעודכן שוב, ובמקרה זה ירוענן מיקום הארכיב. בפרט, קבצים שהועברו לארכיב אינם מופיעים ברשימת הספריות בתוך מערכת ניהול התוכן של אוריון עצמה; עליך לנווט לדף החי עצמו כדי שתוכל לערוך אותו שוב באופן מקוון.
עדכונים מאובטחים %path::dependencies בשביל זה $pathמבוסס על שלה dependencies כותרת glob(s).
ברירות מחדל לשימוש $_ כמו הנתיב אם לא הועברו ארגומנטים.
עדכונים בטוחים @path::acl בשביל זה $pathמבוסס על שלה acl מפרט כותרת.
ברירות מחדל לשימוש $_ כמו הנתיב אם לא הועברו ארגומנטים.