Orion API - bygge
Joe Schaefer
Byggsystem
Det här dokumentet täcker API:erna Bygg system.
I grund och botten styrs byggsystemet av två Perl-moduler som tillhandahålls av användaren: lib/path.pm och lib/view.pm.
Det första är att göra tre saker:
- ladda
lib/facts.ymlochlib/acl.yml, - konstruera
@path::patternsoch - opportunistiskt gå den
content/träd att fördefiniera%path::dependenciesoch@path::aclsfrån metadata för filhuvud för nedsättning/yaml.
Den senares jobb är att tillhandahålla bokningsbara view-baserad $methods för matchande poster i @path::patterns (som ett strängifierat metodnamn i den andra rutan för varje arrayref-post), anropat av skapa skript:
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;
Många åsikter är avsedda att staplas som “filter” Förbearbeta (eller efterbearbeta) aspekter av filen i $path som är nya, som extern kod snippets eller asymptote-hindrade nedsättningsblock. Du kan se ett exempel på detta här.
SunStarSys::View — basklass för lib/view.pm
Den mest populära (och sofistikerade) vyn
Den här vyn innehåller automatisk bearbetning av filer som finns i $pathbilagekatalog. Med andra ord, om $path = "/foo.md.en", sedan de filer som lagras i /foo.page/ katalog associerad med “och” språktillägg kommer att införlivas i mallens adresserbara argument för att $path Oavsett om preprocess argumentinställning — som, om det är sant, också skulle göra det materialet tillgängligt för själva sidans innehåll.
Mandatory Arguments:
templatepathlang
Optional Argmuents:
deps— åsidosätter normaltfetch_depsbearbetningquick_deps— intern optimeringsinställning för deps-processing; bäst lämnad ej inställdpreprocess— aktiverar mallbearbetning inom$pathSjälva innehållet,archive_root— filer i “arkiverad” status är “kopierad” och spåras per år/månad undermappar till denna innehållsrotade plats viassi,category_root— artiklar i “kategorier” Huvudet är “kopierad” över till lämpligt namngivna kategorimappar på den här innehållsbaserade platsen viassi.
För att skapa sidorna index.html och sitemap.html
Språkspecifikt, sorterat index för beroenden.
Mandatory Arguments:
pathlang
Optional Arguments:
quick_depsnestedpreprocess
Byggen och cachar Asymptote triple-backquoted-code block för HTML5-WebGL-canvas-aktiverad vektorgrafik
Mandatory Arguments:
viewlangpath
Bygg inte dessa alls.
Bygg i stället de associerade genererade källfilerna (t.ex. .bib\$lang \$base.page/bibliography.yml\$lang) som ska byggas på en sekundär byggsystemkörning.
Konvertera YAML-filer, vanligtvis till JSON.
Optional Arguments:
extstandardvärdet ärjsonfilterstandardvärdet ärjson_rawtemplateåsidosättningarfilterstandarduttryck
Konvertera CSV-filer, vanligtvis till JSON.
Optional Arguments:
extstandardvärdet ärjsonfilterstandardvärdet ärjson_rawtemplateåsidosättningarfilterstandarduttryck
Refaktorer $data argument hashref som en tidsstämpel ordnad arrayref av 2-element arrayrefs.
Den första posten i varje 2-element arrayref är filsökvägens namn, det andra elementet är resultatet read_text_file hashref för det sökvägsnamnet.
Returnerar en lista över resulterande nya källfiler om $quick > 2.
Mandatory Arguments:
pathdata- indata som hashref; lagrar resulterande arrayref av deps vid returquick- standardvärdet är 2
Bearbetar extern kod utdragslinjer, importerar vanligtvis sina källplatser på GitHub till programmeringsspråkiga avgränsade nedsättningsblock. Exempel här.
Lägger till en rubriksträng i nedsättningslänkar. Normalt bör användas under offline för att undvika att dra in titlar från fjärrplatser, vilket kan sätta en betydande dra på sidan byggtider.
SunStarSys::Util — verktygsbibliotek för lib/path.pm och lib/view.pm
Orions universella textfilprocessor
Parsar rubriker+innehåll i den UTF-8-kodade filen $file och lagrar resultat i hashref $out. $content_lines är det (valfritt) högsta antalet innehållsrader att läsa.
Returnerar faktiskt antal lästa rader (inklusive huvuden).
$file kan vara en referens till en rå sträng som representerar hela innehållet i en fil. Resultaten i $out Kommer fortfarande att vara UTF-8 kodad.
Kopior $src till $dest om den tidigare ändringens tidsstämpel är nyare än den senare.
På kopia, dessutom gzip-komprimerar $dest fil om det är en textfil och lägger till “.gz” Tillägg till namnet. GZIP komprimering kan inaktiveras genom inställning $ENV{NO_COPY_COMPRESS}=1.
Sorterar nedsättningstabeller i $content enligt varje tabells kolumnspecifikation.
Exakt en kolumn kan sorteras per tabell, alternativt numeriskt ni antingen fallande v eller stigande ^ beställning.
fixup_code($prefix, $type, @_)
Remsor $prefix från varje arg i @_.
Syftet med $type argumentet är implementeringsspecifikt, men används huvudsakligen för att fördefiniera editor.md "mode" för bearbetning av innehållet i @_.
normalize_svn_path(@_)
Normaliserar alla sökvägar i @_ för säker användning som råa argument till SVN::Client kommandon.
sanitize_relative_path(@_)
Säkrar sökvägar i @_ för användning som rena relativa sökvägar i Dotiac::DTL (Django Template) sökvägsspecifika kommandon.
Wrapper runt File::Basename::fileparse. Utan argument används $_ som filnamnet som ska tolkas.
Villkorligt vandrar ./content träd för utcheckning av byggsystemet; första normalisering $_ som formell innehållsbaserad undersökväg, och sedan anropa $code->() på varje föremål i trädgången.
För de flesta byggen händer aldrig promenaden — i stället bygger bygget på cachelagrade data från tidigare byggen.
Det enda sättet att tvinga en promenad är genom att ställa $path::use_cache till ett falskt värde i de moduler som användaren tillhandahåller. I annat fall hanteras detta beteende sakkunnigt av inkrementell byggteknik.
Returnerar 1 om vandringen faktiskt fortsatte, i stället för att förlita sig på cachelagrade data. Annars returneras ett falskt värde.
Flaggor varje Status: archived $path (på ett naturligt språkligt sätt). Användningar $_ om inga argument överförs.
Arkivering Markdown-filer är ett naturligt sätt att berätta för Orion att “sluta uppmärksamma den här filens permalänkade plats”, om den inte uppdateras igen, i vilket fall arkivplatsen kommer att uppdateras. I synnerhet visas inte arkiverade filer i kataloglistor inom själva Orion CMS; du måste navigera till själva den aktiva sidan för att kunna redigera den igen online.
Säker uppdatering %path::dependencies för detta $pathbaserat på dess dependencies sidhuvud glob(s).
Används som standard $_ som sökvägen om inga argument överförs.
Säkra uppdateringar @path::acl för detta $pathbaserat på dess acl huvudspec.
Används som standard $_ som sökvägen om inga argument överförs.