[{"data":1,"prerenderedAt":662},["ShallowReactive",2],{"doc:\u002Fguides\u002Fexternal-readers":3,"nav:guides":613},{"doc":4,"source":612},{"id":5,"title":6,"body":7,"description":17,"extension":605,"meta":606,"navigation":607,"path":608,"seo":609,"stem":610,"__hash__":611},"guides\u002Fguides\u002Fexternal-readers.md","External readers",{"type":8,"value":9,"toc":601},"minimark",[10,14,18,21,26,47,383,388,403,407,569,584,597],[11,12,6],"h1",{"id":13},"external-readers",[15,16,17],"p",{},"An external reader is a separate program that Pkl starts to serve a URI scheme. Pkl is the server and the reader is the client: Pkl writes requests to the reader's standard input and reads answers from its standard output. External readers need Pkl 0.27 or newer.",[15,19,20],{},"zig-pkl covers both sides.",[22,23,25],"h2",{"id":24},"write-a-reader-program","Write a reader program",[15,27,28,32,33,36,37,40,41,46],{},[29,30,31],"code",{},"ExternalClient"," runs the reader side of the protocol with the same ",[29,34,35],{},"ModuleReader"," and ",[29,38,39],{},"ResourceReader"," interfaces as ",[42,43,45],"a",{"href":44},"readers","in-process readers",":",[48,49,54],"pre",{"className":50,"code":51,"language":52,"meta":53,"style":53},"language-zig shiki shiki-themes github-light github-dark","pub fn main(init: std.process.Init) !void {\n    var vault = Vault{};\n    const client = zig_pkl.ExternalClient{ .resource_readers = &.{vault.resourceReader()} };\n    var input_buffer: [64 * 1024]u8 = undefined;\n    var output_buffer: [64 * 1024]u8 = undefined;\n    var input = std.Io.File.stdin().readerStreaming(init.io, &input_buffer);\n    var output = std.Io.File.stdout().writerStreaming(init.io, &output_buffer);\n    try client.run(init.gpa, &input.interface, &output.interface);\n}\n","zig","",[29,55,56,106,124,167,202,228,283,330,377],{"__ignoreMap":53},[57,58,61,65,68,72,76,80,83,86,89,92,94,97,100,103],"span",{"class":59,"line":60},"line",1,[57,62,64],{"class":63},"szBVR","pub",[57,66,67],{"class":63}," fn",[57,69,71],{"class":70},"sScJk"," main",[57,73,75],{"class":74},"sVt8B","(",[57,77,79],{"class":78},"s4XuR","init",[57,81,82],{"class":74},": ",[57,84,85],{"class":78},"std",[57,87,88],{"class":74},".",[57,90,91],{"class":78},"process",[57,93,88],{"class":74},[57,95,96],{"class":78},"Init",[57,98,99],{"class":74},") ",[57,101,102],{"class":63},"!void",[57,104,105],{"class":74}," {\n",[57,107,109,112,115,118,121],{"class":59,"line":108},2,[57,110,111],{"class":63},"    var",[57,113,114],{"class":78}," vault",[57,116,117],{"class":63}," =",[57,119,120],{"class":78}," Vault",[57,122,123],{"class":74},"{};\n",[57,125,127,130,133,135,138,140,142,145,148,150,153,156,159,161,164],{"class":59,"line":126},3,[57,128,129],{"class":63},"    const",[57,131,132],{"class":78}," client",[57,134,117],{"class":63},[57,136,137],{"class":78}," zig_pkl",[57,139,88],{"class":74},[57,141,31],{"class":78},[57,143,144],{"class":74},"{ .",[57,146,147],{"class":78},"resource_readers",[57,149,117],{"class":63},[57,151,152],{"class":63}," &",[57,154,155],{"class":74},".{",[57,157,158],{"class":78},"vault",[57,160,88],{"class":74},[57,162,163],{"class":70},"resourceReader",[57,165,166],{"class":74},"()} };\n",[57,168,170,172,175,178,182,185,188,191,194,196,199],{"class":59,"line":169},4,[57,171,111],{"class":63},[57,173,174],{"class":78}," input_buffer",[57,176,177],{"class":74},": [",[57,179,181],{"class":180},"sj4cs","64",[57,183,184],{"class":63}," *",[57,186,187],{"class":180}," 1024",[57,189,190],{"class":74},"]",[57,192,193],{"class":63},"u8",[57,195,117],{"class":63},[57,197,198],{"class":63}," undefined",[57,200,201],{"class":74},";\n",[57,203,205,207,210,212,214,216,218,220,222,224,226],{"class":59,"line":204},5,[57,206,111],{"class":63},[57,208,209],{"class":78}," output_buffer",[57,211,177],{"class":74},[57,213,181],{"class":180},[57,215,184],{"class":63},[57,217,187],{"class":180},[57,219,190],{"class":74},[57,221,193],{"class":63},[57,223,117],{"class":63},[57,225,198],{"class":63},[57,227,201],{"class":74},[57,229,231,233,236,238,241,243,246,248,251,253,256,259,262,264,266,268,271,274,277,280],{"class":59,"line":230},6,[57,232,111],{"class":63},[57,234,235],{"class":78}," input",[57,237,117],{"class":63},[57,239,240],{"class":78}," std",[57,242,88],{"class":74},[57,244,245],{"class":78},"Io",[57,247,88],{"class":74},[57,249,250],{"class":78},"File",[57,252,88],{"class":74},[57,254,255],{"class":70},"stdin",[57,257,258],{"class":74},"().",[57,260,261],{"class":70},"readerStreaming",[57,263,75],{"class":74},[57,265,79],{"class":78},[57,267,88],{"class":74},[57,269,270],{"class":78},"io",[57,272,273],{"class":74},", ",[57,275,276],{"class":63},"&",[57,278,279],{"class":78},"input_buffer",[57,281,282],{"class":74},");\n",[57,284,286,288,291,293,295,297,299,301,303,305,308,310,313,315,317,319,321,323,325,328],{"class":59,"line":285},7,[57,287,111],{"class":63},[57,289,290],{"class":78}," output",[57,292,117],{"class":63},[57,294,240],{"class":78},[57,296,88],{"class":74},[57,298,245],{"class":78},[57,300,88],{"class":74},[57,302,250],{"class":78},[57,304,88],{"class":74},[57,306,307],{"class":70},"stdout",[57,309,258],{"class":74},[57,311,312],{"class":70},"writerStreaming",[57,314,75],{"class":74},[57,316,79],{"class":78},[57,318,88],{"class":74},[57,320,270],{"class":78},[57,322,273],{"class":74},[57,324,276],{"class":63},[57,326,327],{"class":78},"output_buffer",[57,329,282],{"class":74},[57,331,333,336,338,340,343,345,347,349,352,354,356,359,361,364,366,368,371,373,375],{"class":59,"line":332},8,[57,334,335],{"class":63},"    try",[57,337,132],{"class":78},[57,339,88],{"class":74},[57,341,342],{"class":70},"run",[57,344,75],{"class":74},[57,346,79],{"class":78},[57,348,88],{"class":74},[57,350,351],{"class":78},"gpa",[57,353,273],{"class":74},[57,355,276],{"class":63},[57,357,358],{"class":78},"input",[57,360,88],{"class":74},[57,362,363],{"class":78},"interface",[57,365,273],{"class":74},[57,367,276],{"class":63},[57,369,370],{"class":78},"output",[57,372,88],{"class":74},[57,374,363],{"class":78},[57,376,282],{"class":74},[57,378,380],{"class":59,"line":379},9,[57,381,382],{"class":74},"}\n",[15,384,385,387],{},[29,386,342],{}," returns when Pkl sends its close message or closes standard input. Standard output carries protocol frames only, so write diagnostics to standard error.",[15,389,390,391,394,395,398,399,402],{},"The resulting executable works with any Pkl host, not only zig-pkl: the ",[29,392,393],{},"pkl"," CLI (",[29,396,397],{},"--external-resource-reader vault=.\u002Fvault-reader","), ",[29,400,401],{},"PklProject"," settings, and other language bindings.",[22,404,406],{"id":405},"use-a-reader-from-zig-pkl","Use a reader from zig-pkl",[48,408,410],{"className":50,"code":409,"language":52,"meta":53,"style":53},"var options = zig_pkl.Options.restricted();\noptions.allowed_resources = &.{\"vault:\"};\noptions.external_resource_readers = &.{.{\n    .scheme = \"vault\",\n    .executable = \"\u002Fusr\u002Flocal\u002Fbin\u002Fvault-reader\",\n    .arguments = &.{\"--region\", \"eu-west-1\"},\n}};\nconst evaluator = try manager.createEvaluator(options, &rejected);\n",[29,411,412,437,460,476,492,506,530,535],{"__ignoreMap":53},[57,413,414,417,420,422,424,426,429,431,434],{"class":59,"line":60},[57,415,416],{"class":63},"var",[57,418,419],{"class":78}," options",[57,421,117],{"class":63},[57,423,137],{"class":78},[57,425,88],{"class":74},[57,427,428],{"class":78},"Options",[57,430,88],{"class":74},[57,432,433],{"class":70},"restricted",[57,435,436],{"class":74},"();\n",[57,438,439,442,444,447,449,451,453,457],{"class":59,"line":108},[57,440,441],{"class":78},"options",[57,443,88],{"class":74},[57,445,446],{"class":78},"allowed_resources",[57,448,117],{"class":63},[57,450,152],{"class":63},[57,452,155],{"class":74},[57,454,456],{"class":455},"sZZnC","\"vault:\"",[57,458,459],{"class":74},"};\n",[57,461,462,464,466,469,471,473],{"class":59,"line":126},[57,463,441],{"class":78},[57,465,88],{"class":74},[57,467,468],{"class":78},"external_resource_readers",[57,470,117],{"class":63},[57,472,152],{"class":63},[57,474,475],{"class":74},".{.{\n",[57,477,478,481,484,486,489],{"class":59,"line":169},[57,479,480],{"class":74},"    .",[57,482,483],{"class":78},"scheme",[57,485,117],{"class":63},[57,487,488],{"class":455}," \"vault\"",[57,490,491],{"class":74},",\n",[57,493,494,496,499,501,504],{"class":59,"line":204},[57,495,480],{"class":74},[57,497,498],{"class":78},"executable",[57,500,117],{"class":63},[57,502,503],{"class":455}," \"\u002Fusr\u002Flocal\u002Fbin\u002Fvault-reader\"",[57,505,491],{"class":74},[57,507,508,510,513,515,517,519,522,524,527],{"class":59,"line":230},[57,509,480],{"class":74},[57,511,512],{"class":78},"arguments",[57,514,117],{"class":63},[57,516,152],{"class":63},[57,518,155],{"class":74},[57,520,521],{"class":455},"\"--region\"",[57,523,273],{"class":74},[57,525,526],{"class":455},"\"eu-west-1\"",[57,528,529],{"class":74},"},\n",[57,531,532],{"class":59,"line":285},[57,533,534],{"class":74},"}};\n",[57,536,537,540,543,545,548,551,553,556,558,560,562,564,567],{"class":59,"line":332},[57,538,539],{"class":63},"const",[57,541,542],{"class":78}," evaluator",[57,544,117],{"class":63},[57,546,547],{"class":63}," try",[57,549,550],{"class":78}," manager",[57,552,88],{"class":74},[57,554,555],{"class":70},"createEvaluator",[57,557,75],{"class":74},[57,559,441],{"class":78},[57,561,273],{"class":74},[57,563,276],{"class":63},[57,565,566],{"class":78},"rejected",[57,568,282],{"class":74},[15,570,571,572,574,575,578,579,583],{},"Pkl owns the reader process: it starts the executable when it needs the scheme and stops it when the evaluator closes. External readers can also be declared in ",[29,573,401],{}," under ",[29,576,577],{},"evaluatorSettings","; see ",[42,580,582],{"href":581},"projects","Projects"," for how their paths resolve.",[15,585,586,592,593,596],{},[42,587,589],{"href":588},"..\u002F..\u002Fexamples\u002Fexternal-reader\u002Fmain.zig",[29,590,591],{},"examples\u002Fexternal-reader"," is a single program that plays both roles: run without arguments it evaluates Pkl, and Pkl starts it again with ",[29,594,595],{},"--serve"," as the reader.",[598,599,600],"style",{},"html pre.shiki code .szBVR, html code.shiki .szBVR{--shiki-default:#D73A49;--shiki-dark:#F97583}html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .s4XuR, html code.shiki .s4XuR{--shiki-default:#E36209;--shiki-dark:#FFAB70}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}",{"title":53,"searchDepth":108,"depth":108,"links":602},[603,604],{"id":24,"depth":108,"text":25},{"id":405,"depth":108,"text":406},"md",{},true,"\u002Fguides\u002Fexternal-readers",{"title":6,"description":17},"guides\u002Fexternal-readers","mzMuHosGAilpz4QAEfCamFtEn3qoNwqavDvCDboXmYI","docs\u002Fguides\u002Fexternal-readers.md",[614,618,622,626,630,631,635,639,643,647,650,654,658],{"title":615,"path":616,"stem":617},"Version compatibility","\u002Fguides\u002Fcompatibility","guides\u002Fcompatibility",{"title":619,"path":620,"stem":621},"Concurrency","\u002Fguides\u002Fconcurrency","guides\u002Fconcurrency",{"title":623,"path":624,"stem":625},"Errors","\u002Fguides\u002Ferrors","guides\u002Ferrors",{"title":627,"path":628,"stem":629},"Evaluation","\u002Fguides\u002Fevaluation","guides\u002Fevaluation",{"title":6,"path":608,"stem":610},{"title":632,"path":633,"stem":634},"Installation","\u002Fguides\u002Finstallation","guides\u002Finstallation",{"title":636,"path":637,"stem":638},"Logging","\u002Fguides\u002Flogging","guides\u002Flogging",{"title":640,"path":641,"stem":642},"Migrating from pkl-zig","\u002Fguides\u002Fmigration","guides\u002Fmigration",{"title":644,"path":645,"stem":646},"Ownership","\u002Fguides\u002Fownership","guides\u002Fownership",{"title":582,"path":648,"stem":649},"\u002Fguides\u002Fprojects","guides\u002Fprojects",{"title":651,"path":652,"stem":653},"Quick start","\u002Fguides\u002Fquickstart","guides\u002Fquickstart",{"title":655,"path":656,"stem":657},"Readers","\u002Fguides\u002Freaders","guides\u002Freaders",{"title":659,"path":660,"stem":661},"Security","\u002Fguides\u002Fsecurity","guides\u002Fsecurity",1792908673508]