[{"data":1,"prerenderedAt":1993},["ShallowReactive",2],{"doc:\u002Fcodegen":3,"nav:guides":1941},{"doc":4,"source":1940},{"id":5,"title":6,"body":7,"description":1934,"extension":1935,"meta":1936,"navigation":118,"path":1937,"seo":1938,"stem":1635,"__hash__":1939},"reference\u002Fcodegen.md","Code generation",{"type":8,"value":9,"toc":1919},"minimark",[10,14,41,63,68,219,230,456,480,498,505,527,574,584,673,680,684,1023,1026,1181,1185,1213,1272,1297,1306,1318,1322,1329,1340,1344,1370,1374,1399,1427,1441,1445,1452,1459,1480,1484,1490,1496,1500,1541,1545,1548,1807,1814,1817,1845,1849,1915],[11,12,6],"h1",{"id":13},"code-generation",[15,16,17,21,22,25,26,29,30,33,34,37,38,40],"p",{},[18,19,20],"code",{},"zig-pkl-gen"," turns Pkl modules into Zig types that decode with ",[18,23,24],{},"zig_pkl.convert",". Each module becomes one Zig file. The generated ",[18,27,28],{},"decode",", ",[18,31,32],{},"deinit",", and ",[18,35,36],{},"load"," helpers use the same ownership rules as the typed core: the caller owns every decoded value and releases it with ",[18,39,32],{}," and the allocator it decoded with.",[15,42,43,44,47,48,29,51,54,55,58,59,62],{},"Generation needs Pkl 0.32.2. The generator runs ",[18,45,46],{},"pkl server"," from ",[18,49,50],{},"--pkl",[18,52,53],{},"PKL_EXEC",", or ",[18,56,57],{},"pkl"," on ",[18,60,61],{},"PATH",", in that order.",[64,65,67],"h2",{"id":66},"quick-start","Quick start",[69,70,74],"pre",{"className":71,"code":72,"language":57,"meta":73,"style":73},"language-pkl shiki shiki-themes github-light github-dark","\u002F\u002F pkl\u002FService.pkl\n@zig.Package { name = \"service\" }\nmodule example.Service\n\nimport \"@zig\u002Fzig.pkl\"\n\nhost: String = \"127.0.0.1\"\n\n@zig.Name { value = \"listen_port\" }\nport: UInt16 = 8080\n\nroutes: Listing\u003CRoute>\n\nclass Route {\n  path: String\n}\n","",[18,75,76,85,103,113,120,130,135,150,155,168,182,187,196,201,207,213],{"__ignoreMap":73},[77,78,81],"span",{"class":79,"line":80},"line",1,[77,82,84],{"class":83},"sJ8bj","\u002F\u002F pkl\u002FService.pkl\n",[77,86,88,92,96,100],{"class":79,"line":87},2,[77,89,91],{"class":90},"sScJk","@zig",[77,93,95],{"class":94},"sVt8B",".Package { name = ",[77,97,99],{"class":98},"sZZnC","\"service\"",[77,101,102],{"class":94}," }\n",[77,104,106,110],{"class":79,"line":105},3,[77,107,109],{"class":108},"sj4cs","module",[77,111,112],{"class":94}," example.Service\n",[77,114,116],{"class":79,"line":115},4,[77,117,119],{"emptyLinePlaceholder":118},true,"\n",[77,121,123,127],{"class":79,"line":122},5,[77,124,126],{"class":125},"szBVR","import",[77,128,129],{"class":98}," \"@zig\u002Fzig.pkl\"\n",[77,131,133],{"class":79,"line":132},6,[77,134,119],{"emptyLinePlaceholder":118},[77,136,138,141,144,147],{"class":79,"line":137},7,[77,139,140],{"class":94},"host: ",[77,142,143],{"class":90},"String ",[77,145,146],{"class":94},"= ",[77,148,149],{"class":98},"\"127.0.0.1\"\n",[77,151,153],{"class":79,"line":152},8,[77,154,119],{"emptyLinePlaceholder":118},[77,156,158,160,163,166],{"class":79,"line":157},9,[77,159,91],{"class":90},[77,161,162],{"class":94},".Name { value = ",[77,164,165],{"class":98},"\"listen_port\"",[77,167,102],{"class":94},[77,169,171,174,177,179],{"class":79,"line":170},10,[77,172,173],{"class":94},"port: ",[77,175,176],{"class":90},"UInt16 ",[77,178,146],{"class":94},[77,180,181],{"class":108},"8080\n",[77,183,185],{"class":79,"line":184},11,[77,186,119],{"emptyLinePlaceholder":118},[77,188,190,193],{"class":79,"line":189},12,[77,191,192],{"class":94},"routes: ",[77,194,195],{"class":90},"Listing\u003CRoute>\n",[77,197,199],{"class":79,"line":198},13,[77,200,119],{"emptyLinePlaceholder":118},[77,202,204],{"class":79,"line":203},14,[77,205,206],{"class":94},"class Route {\n",[77,208,210],{"class":79,"line":209},15,[77,211,212],{"class":94},"  path: String\n",[77,214,216],{"class":79,"line":215},16,[77,217,218],{"class":94},"}\n",[69,220,224],{"className":221,"code":222,"language":223,"meta":73,"style":73},"language-sh shiki shiki-themes github-light github-dark","zig-pkl-gen --library path\u002Fto\u002Fzig-pkl --project-dir . -o src\u002Fbindings pkl\u002FService.pkl\n","sh",[18,225,226],{"__ignoreMap":73},[77,227,228],{"class":79,"line":80},[77,229,222],{},[69,231,235],{"className":232,"code":233,"language":234,"meta":73,"style":73},"language-zig shiki shiki-themes github-light github-dark","const Service = @import(\"bindings\").service;\n\nvar failure: ?[]u8 = null;\ndefer if (failure) |text| manager.allocator.free(text);\nvar service = try Service.load(allocator, evaluator, .uri(module_uri), &failure);\ndefer service.deinit(allocator);\nstd.debug.print(\"{s}:{d}\\n\", .{ service.host, service.listen_port });\n","zig",[18,236,237,267,271,298,344,392,408],{"__ignoreMap":73},[77,238,239,242,246,249,252,255,258,261,264],{"class":79,"line":80},[77,240,241],{"class":125},"const",[77,243,245],{"class":244},"s4XuR"," Service",[77,247,248],{"class":125}," =",[77,250,251],{"class":108}," @import",[77,253,254],{"class":94},"(",[77,256,257],{"class":98},"\"bindings\"",[77,259,260],{"class":94},").",[77,262,263],{"class":244},"service",[77,265,266],{"class":94},";\n",[77,268,269],{"class":79,"line":87},[77,270,119],{"emptyLinePlaceholder":118},[77,272,273,276,279,282,285,288,291,293,296],{"class":79,"line":105},[77,274,275],{"class":125},"var",[77,277,278],{"class":244}," failure",[77,280,281],{"class":94},": ",[77,283,284],{"class":125},"?",[77,286,287],{"class":94},"[]",[77,289,290],{"class":125},"u8",[77,292,248],{"class":125},[77,294,295],{"class":125}," null",[77,297,266],{"class":94},[77,299,300,303,306,309,312,315,318,321,323,326,329,332,334,337,339,341],{"class":79,"line":115},[77,301,302],{"class":125},"defer",[77,304,305],{"class":125}," if",[77,307,308],{"class":94}," (",[77,310,311],{"class":244},"failure",[77,313,314],{"class":94},") ",[77,316,317],{"class":125},"|",[77,319,320],{"class":244},"text",[77,322,317],{"class":125},[77,324,325],{"class":244}," manager",[77,327,328],{"class":94},".",[77,330,331],{"class":244},"allocator",[77,333,328],{"class":94},[77,335,336],{"class":90},"free",[77,338,254],{"class":94},[77,340,320],{"class":244},[77,342,343],{"class":94},");\n",[77,345,346,348,351,353,356,358,360,362,364,366,368,371,374,377,379,382,385,388,390],{"class":79,"line":122},[77,347,275],{"class":125},[77,349,350],{"class":244}," service",[77,352,248],{"class":125},[77,354,355],{"class":125}," try",[77,357,245],{"class":244},[77,359,328],{"class":94},[77,361,36],{"class":90},[77,363,254],{"class":94},[77,365,331],{"class":244},[77,367,29],{"class":94},[77,369,370],{"class":244},"evaluator",[77,372,373],{"class":94},", .",[77,375,376],{"class":90},"uri",[77,378,254],{"class":94},[77,380,381],{"class":244},"module_uri",[77,383,384],{"class":94},"), ",[77,386,387],{"class":125},"&",[77,389,311],{"class":244},[77,391,343],{"class":94},[77,393,394,396,398,400,402,404,406],{"class":79,"line":132},[77,395,302],{"class":125},[77,397,350],{"class":244},[77,399,328],{"class":94},[77,401,32],{"class":90},[77,403,254],{"class":94},[77,405,331],{"class":244},[77,407,343],{"class":94},[77,409,410,413,415,418,420,423,425,428,431,434,437,439,441,444,446,448,450,453],{"class":79,"line":137},[77,411,412],{"class":244},"std",[77,414,328],{"class":94},[77,416,417],{"class":244},"debug",[77,419,328],{"class":94},[77,421,422],{"class":90},"print",[77,424,254],{"class":94},[77,426,427],{"class":98},"\"{s}:{d}",[77,429,430],{"class":108},"\\n",[77,432,433],{"class":98},"\"",[77,435,436],{"class":94},", .{ ",[77,438,263],{"class":244},[77,440,328],{"class":94},[77,442,443],{"class":244},"host",[77,445,29],{"class":94},[77,447,263],{"class":244},[77,449,328],{"class":94},[77,451,452],{"class":244},"listen_port",[77,454,455],{"class":94}," });\n",[15,457,458,460,461,463,464,467,468,471,472,475,476,479],{},[18,459,36],{}," evaluates a module that amends or matches the schema. ",[18,462,28],{}," converts an already evaluated ",[18,465,466],{},"zig_pkl.Value",". Both return ",[18,469,470],{},"zig_pkl.convert.Error"," values such as ",[18,473,474],{},"error.TypeMismatch"," and ",[18,477,478],{},"error.MissingField"," when the data does not fit the bindings.",[15,481,482,489,490,493,494,497],{},[483,484,486],"a",{"href":485},"..\u002Fexamples\u002Fcodegen",[18,487,488],{},"examples\u002Fcodegen"," is a complete consumer: a separate Zig package that depends on ",[18,491,492],{},"zig_pkl"," by path, checks in its bindings, and regenerates them with its own ",[18,495,496],{},"zig build codegen"," step.",[64,499,501,502,504],{"id":500},"the-zig-annotations","The ",[18,503,91],{}," annotations",[15,506,507,508,514,515,518,519,522,523,526],{},"The annotations live in ",[483,509,511],{"href":510},"..\u002Fcodegen\u002Fzig.pkl",[18,512,513],{},"codegen\u002Fzig.pkl",", published as the Pkl package ",[18,516,517],{},"package:\u002F\u002Fpkg.pkl-lang.org\u002Fgithub.com\u002Fguanchzhou\u002Fzig-pkl\u002Fzig",". Its version matches the zig-pkl release. Depend on it from a ",[18,520,521],{},"PklProject"," and run ",[18,524,525],{},"pkl project resolve",":",[69,528,530],{"className":71,"code":529,"language":57,"meta":73,"style":73},"\u002F\u002F PklProject\namends \"pkl:Project\"\n\ndependencies {\n  [\"zig\"] { uri = \"package:\u002F\u002Fpkg.pkl-lang.org\u002Fgithub.com\u002Fguanchzhou\u002Fzig-pkl\u002Fzig@0.1.1\" }\n}\n",[18,531,532,537,545,549,554,570],{"__ignoreMap":73},[77,533,534],{"class":79,"line":80},[77,535,536],{"class":83},"\u002F\u002F PklProject\n",[77,538,539,542],{"class":79,"line":87},[77,540,541],{"class":125},"amends",[77,543,544],{"class":98}," \"pkl:Project\"\n",[77,546,547],{"class":79,"line":105},[77,548,119],{"emptyLinePlaceholder":118},[77,550,551],{"class":79,"line":115},[77,552,553],{"class":94},"dependencies {\n",[77,555,556,559,562,565,568],{"class":79,"line":122},[77,557,558],{"class":94},"  [",[77,560,561],{"class":98},"\"zig\"",[77,563,564],{"class":94},"] { uri = ",[77,566,567],{"class":98},"\"package:\u002F\u002Fpkg.pkl-lang.org\u002Fgithub.com\u002Fguanchzhou\u002Fzig-pkl\u002Fzig@0.1.1\"",[77,569,102],{"class":94},[77,571,572],{"class":79,"line":132},[77,573,218],{"class":94},[15,575,576,577,580,581,328],{},"A project can also depend on a checkout directly with ",[18,578,579],{},"[\"zig\"] = import(\"path\u002Fto\u002Fzig-pkl\u002Fcodegen\u002FPklProject\")",". Modules then import the annotations as ",[18,582,583],{},"import \"@zig\u002Fzig.pkl\"",[585,586,587,603],"table",{},[588,589,590],"thead",{},[591,592,593,597,600],"tr",{},[594,595,596],"th",{},"Annotation",[594,598,599],{},"Applies to",[594,601,602],{},"Effect",[604,605,606,626,643,659],"tbody",{},[591,607,608,614,616],{},[609,610,611],"td",{},[18,612,613],{},"@zig.Package { name = \"a.b\" }",[609,615,109],{},[609,617,618,619,622,623,328],{},"Writes the module to ",[18,620,621],{},"a\u002Fb.zig",", reachable from the index as ",[18,624,625],{},"a.b",[591,627,628,633,636],{},[609,629,630],{},[18,631,632],{},"@zig.Name { value = \"id\" }",[609,634,635],{},"class, type alias, property",[609,637,638,639,642],{},"Uses ",[18,640,641],{},"id"," as the Zig name.",[591,644,645,650,653],{},[609,646,647],{},[18,648,649],{},"@zig.Field { boxed = true }",[609,651,652],{},"property",[609,654,655,656,328],{},"Stores the value behind ",[18,657,658],{},"*const",[591,660,661,666,668],{},[609,662,663],{},[18,664,665],{},"@zig.Field { type = \"...\" }",[609,667,652],{},[609,669,670,671,328],{},"Uses the Zig type expression verbatim. It must be a single type expression without comments, blocks, or declarations, and decode with ",[18,672,24],{},[15,674,675,676,679],{},"The annotations validate their arguments, so an invalid ",[18,677,678],{},"@zig.Name"," fails during Pkl evaluation with the constraint that it violates.",[64,681,683],{"id":682},"type-mapping","Type mapping",[585,685,686,696],{},[588,687,688],{},[591,689,690,693],{},[594,691,692],{},"Pkl",[594,694,695],{},"Zig",[604,697,698,710,722,769,784,802,814,835,851,863,881,905,927,943,955,967,979,993,1004,1011],{},[591,699,700,705],{},[609,701,702],{},[18,703,704],{},"Boolean",[609,706,707],{},[18,708,709],{},"bool",[591,711,712,717],{},[609,713,714],{},[18,715,716],{},"Int",[609,718,719],{},[18,720,721],{},"i64",[591,723,724,747],{},[609,725,726,29,729,29,732,29,735,29,738,29,741,29,744],{},[18,727,728],{},"Int8",[18,730,731],{},"Int16",[18,733,734],{},"Int32",[18,736,737],{},"UInt8",[18,739,740],{},"UInt16",[18,742,743],{},"UInt32",[18,745,746],{},"UInt",[609,748,749,29,752,29,755,29,758,29,760,29,763,29,766],{},[18,750,751],{},"i8",[18,753,754],{},"i16",[18,756,757],{},"i32",[18,759,290],{},[18,761,762],{},"u16",[18,764,765],{},"u32",[18,767,768],{},"u64",[591,770,771,779],{},[609,772,773,29,776],{},[18,774,775],{},"Float",[18,777,778],{},"Number",[609,780,781],{},[18,782,783],{},"f64",[591,785,786,797],{},[609,787,788,29,791,29,794],{},[18,789,790],{},"String",[18,792,793],{},"Char",[18,795,796],{},"Uri",[609,798,799],{},[18,800,801],{},"[]const u8",[591,803,804,809],{},[609,805,806],{},[18,807,808],{},"T?",[609,810,811],{},[18,812,813],{},"?T",[591,815,816,830],{},[609,817,818,29,821,29,824,29,827],{},[18,819,820],{},"List\u003CT>",[18,822,823],{},"Listing\u003CT>",[18,825,826],{},"Set\u003CT>",[18,828,829],{},"Collection\u003CT>",[609,831,832],{},[18,833,834],{},"[]const T",[591,836,837,845],{},[609,838,839,29,842],{},[18,840,841],{},"Map\u003CK, V>",[18,843,844],{},"Mapping\u003CK, V>",[609,846,847,850],{},[18,848,849],{},"zig_pkl.convert.Map(K, V)",", in evaluation order",[591,852,853,858],{},[609,854,855],{},[18,856,857],{},"Pair\u003CA, B>",[609,859,860],{},[18,861,862],{},"zig_pkl.convert.Pair(A, B)",[591,864,865,873],{},[609,866,867,29,870],{},[18,868,869],{},"Duration",[18,871,872],{},"DataSize",[609,874,875,29,878],{},[18,876,877],{},"zig_pkl.convert.Duration",[18,879,880],{},"zig_pkl.convert.DataSize",[591,882,883,894],{},[609,884,885,29,888,29,891],{},[18,886,887],{},"Regex",[18,889,890],{},"Bytes",[18,892,893],{},"IntSeq",[609,895,896,29,899,29,902],{},[18,897,898],{},"zig_pkl.convert.Regex",[18,900,901],{},"zig_pkl.convert.Bytes",[18,903,904],{},"zig_pkl.convert.IntSeq",[591,906,907,921],{},[609,908,909,29,912,29,915,29,918],{},[18,910,911],{},"Dynamic",[18,913,914],{},"Any",[18,916,917],{},"Typed",[18,919,920],{},"Object",[609,922,923,926],{},[18,924,925],{},"zig_pkl.convert.Dynamic",", an owned deep copy of the value",[591,928,929,937],{},[609,930,931,47,934],{},[18,932,933],{},"ref.Reference\u003CD, T>",[18,935,936],{},"pkl:ref",[609,938,939,942],{},[18,940,941],{},"zig_pkl.convert.Reference(D, T)",": the domain, the access path, and the raw value",[591,944,945,950],{},[609,946,947],{},[18,948,949],{},"ref.Access",[609,951,952],{},[18,953,954],{},"zig_pkl.convert.Access",[591,956,957,962],{},[609,958,959],{},[18,960,961],{},"\"a\" | \"b\"",[609,963,964],{},[18,965,966],{},"enum { a, b }",[591,968,969,974],{},[609,970,971],{},[18,972,973],{},"A | B",[609,975,976],{},[18,977,978],{},"union(enum) { a: A, b: B }",[591,980,981,988],{},[609,982,983,984,987],{},"class, including a ",[18,985,986],{},"local"," class",[609,989,990],{},[18,991,992],{},"struct",[591,994,995,998],{},[609,996,997],{},"abstract class with subclasses",[609,999,1000,1003],{},[18,1001,1002],{},"union(enum)"," with one member per concrete subclass",[591,1005,1006,1008],{},[609,1007,109],{},[609,1009,1010],{},"the generated file's own struct",[591,1012,1013,1018],{},[609,1014,1015],{},[18,1016,1017],{},"typealias X = T",[609,1019,1020],{},[18,1021,1022],{},"pub const X = T;",[15,1024,1025],{},"Details:",[1027,1028,1029,1045,1073,1086,1097,1136,1154,1157,1171,1174],"ul",{},[1030,1031,1032,1033,1036,1037,1040,1041,1044],"li",{},"Properties become ",[18,1034,1035],{},"snake_case"," fields; classes and type aliases keep their names. A field whose Pkl name differs is listed in ",[18,1038,1039],{},"pkl_names",", which ",[18,1042,1043],{},"convert"," uses to find the property.",[1030,1046,1047,1048,1051,1052,29,1054,1057,1058,1061,1062,1064,1065,1068,1069,1072],{},"Inherited properties are copied into each subclass. A subclass property redeclared without a type, such as ",[18,1049,1050],{},"port = 8443",", keeps the parent's type, ",[18,1053,678],{},[18,1055,1056],{},"@zig.Field",", and documentation, and takes the new default. A ",[18,1059,1060],{},"hidden"," property, and an override that does not repeat ",[18,1063,1060],{},", stays out of the struct. Each struct records its Pkl class in ",[18,1066,1067],{},"pkl_class"," and its known subclasses in ",[18,1070,1071],{},"pkl_subclasses",", so a field of an open class type also decodes instances of its subclasses.",[1030,1074,1075,1076,1078,1079,1081,1082,1085],{},"A property must declare a type. An untyped property that does not override one is an error; declare ",[18,1077,914],{}," or ",[18,1080,911],{}," to keep the value dynamic. Unsupported ",[18,1083,1084],{},"pkl:base"," classes and aliases, and unbound type variables, are errors too.",[1030,1087,1088,1089,1092,1093,1096],{},"A union of string literals with other types becomes a tagged union whose literal members are ",[18,1090,1091],{},"void",". ",[18,1094,1095],{},"Null"," in a union makes the result optional.",[1030,1098,1099,1100,1102,1103,1105,1106,1108,1109,1111,1112,1114,1115,475,1118,1121,1122,475,1125,1128,1129,1078,1132,1135],{},"A union value decodes into, in order: a literal member; the member whose ",[18,1101,1067],{}," is the value's class; a member listing it in ",[18,1104,1071],{},"; a member of exactly the value's kind (an ",[18,1107,716],{}," only into an integer, a ",[18,1110,775],{}," only into a float); any member that accepts the value's shape; a ",[18,1113,911],{}," member. ",[18,1116,1117],{},"Float | Int",[18,1119,1120],{},"Int | Float"," therefore decode ",[18,1123,1124],{},"1",[18,1126,1127],{},"1.5"," the same way. Members that accept the same values, such as ",[18,1130,1131],{},"List\u003CInt> | Set\u003CInt>",[18,1133,1134],{},"Int8 | Int16",", are rejected.",[1030,1137,1138,1139,1142,1143,1146,1147,1142,1150,1153],{},"Unions, enums, and classes declared inline get a name derived from their owner: ",[18,1140,1141],{},"Route.method"," becomes ",[18,1144,1145],{},"RouteMethod","; a module property ",[18,1148,1149],{},"mode",[18,1151,1152],{},"Mode",". Names that are taken gain a numeric suffix.",[1030,1155,1156],{},"Generic type aliases are expanded where they are used.",[1030,1158,1159,1160,1163,1164,308,1167,1170],{},"A type that contains itself by value, directly, through other modules, or through a nullable alias such as ",[18,1161,1162],{},"typealias MaybeNode = Node?",", has those fields stored as ",[18,1165,1166],{},"*const T",[18,1168,1169],{},"?*const T"," for optionals). Fields reached through slices or maps stay by value.",[1030,1172,1173],{},"Modules are ordered by URI, and the members of a subclass union are ordered by qualified class name. Properties, classes, and the members of an inline union keep their Pkl declaration order. Either way, the order of the modules on the command line does not change the output.",[1030,1175,1176,1177,1180],{},"Defaults are emitted for booleans, integers that fit the field type, floats, strings, enum members, literal union members, ",[18,1178,1179],{},"null",", durations, data sizes, and listings, lists, sets, maps, and mappings of those. Defaults that are objects stay with Pkl, and the field has no Zig default. Any other default that cannot be represented, or that fails to evaluate, is reported as a warning and leaves the field without a Zig default.",[64,1182,1184],{"id":1183},"output-layout","Output layout",[15,1186,1187,1188,1191,1192,1195,1196,1199,1200,1203,1204,29,1207,1209,1210,1212],{},"One file is written per described module, plus the index file (",[18,1189,1190],{},"root.zig"," by default). ",[18,1193,1194],{},"--index-file"," takes a normalized relative ",[18,1197,1198],{},".zig"," path inside the output directory, such as ",[18,1201,1202],{},"gen\u002Fall.zig","; the module files are placed in its directory. Absolute paths, ",[18,1205,1206],{},"..",[18,1208,328],{},", empty segments, backslashes, and names without ",[18,1211,1198],{}," are usage errors.",[69,1214,1216],{"className":232,"code":1215,"language":234,"meta":73,"style":73},"\u002F\u002F! Bindings for every generated Pkl module. Regenerate this file instead of editing it.\n\npub const fixture = struct {\n    pub const app = @import(\"fixture\u002Fapp.zig\");\n};\n",[18,1217,1218,1223,1227,1246,1267],{"__ignoreMap":73},[77,1219,1220],{"class":79,"line":80},[77,1221,1222],{"class":83},"\u002F\u002F! Bindings for every generated Pkl module. Regenerate this file instead of editing it.\n",[77,1224,1225],{"class":79,"line":87},[77,1226,119],{"emptyLinePlaceholder":118},[77,1228,1229,1232,1235,1238,1240,1243],{"class":79,"line":105},[77,1230,1231],{"class":125},"pub",[77,1233,1234],{"class":125}," const",[77,1236,1237],{"class":244}," fixture",[77,1239,248],{"class":125},[77,1241,1242],{"class":125}," struct",[77,1244,1245],{"class":94}," {\n",[77,1247,1248,1251,1253,1256,1258,1260,1262,1265],{"class":79,"line":115},[77,1249,1250],{"class":125},"    pub",[77,1252,1234],{"class":125},[77,1254,1255],{"class":244}," app",[77,1257,248],{"class":125},[77,1259,251],{"class":108},[77,1261,254],{"class":94},[77,1263,1264],{"class":98},"\"fixture\u002Fapp.zig\"",[77,1266,343],{"class":94},[77,1268,1269],{"class":79,"line":122},[77,1270,1271],{"class":94},"};\n",[15,1273,1274,1275,1278,1279,1282,1283,1285,1286,1289,1290,1293,1294,1296],{},"The path comes from, in order: the longest matching ",[18,1276,1277],{},"--package"," mapping, ",[18,1280,1281],{},"@zig.Package",", and finally the module name, with each segment converted to ",[18,1284,1035],{},". A mapping matches a module name (",[18,1287,1288],{},"app.config","), a name prefix (",[18,1291,1292],{},"app","), or, when it contains ",[18,1295,526],{},", a module URI or URI prefix. The unmatched part of the name or URI is appended:",[69,1298,1300],{"className":221,"code":1299,"language":223,"meta":73,"style":73},"zig-pkl-gen --package 'projectpackage:\u002F\u002Fexample.com\u002Fshared@1.0.0#\u002F=vendor.shared' ...\n",[18,1301,1302],{"__ignoreMap":73},[77,1303,1304],{"class":79,"line":80},[77,1305,1299],{},[15,1307,1308,1309,1311,1312,1314,1315,1317],{},"Generated files import ",[18,1310,412],{}," and the module ",[18,1313,492],{},", so the consuming module must provide ",[18,1316,492],{}," under that name.",[64,1319,1321],{"id":1320},"incremental-regeneration","Incremental regeneration",[15,1323,1324,1325,1328],{},"The generator records every file it writes, with its SHA-256, in ",[18,1326,1327],{},".zig-pkl-gen-manifest"," in the output directory. On the next run it writes only files that differ and deletes files that are listed in the manifest but no longer planned.",[15,1330,1331,1332,1335,1336,1339],{},"It never replaces or deletes a file that it did not write or that changed since: a planned path occupied by a handwritten file, a listed file that was edited, a malformed manifest, or a manifest entry outside the output directory fails the run before anything is written. ",[18,1333,1334],{},"--force"," overrides this and adopts the files. ",[18,1337,1338],{},"--check"," writes nothing and exits with status 1 when any file, including the manifest, would change, which suits CI.",[64,1341,1343],{"id":1342},"type-checking","Type checking",[15,1345,1346,1347,1350,1351,1354,1355,1358,1359,1354,1362,1365,1366,1369],{},"Before writing, the generator compiles the bindings with ",[18,1348,1349],{},"zig test -fno-emit-bin"," against the zig-pkl sources, staging them in a temporary directory that it removes afterwards. Bindings that do not type-check fail the run with the compiler's errors and leave the output directory unchanged. ",[18,1352,1353],{},"--library"," (or ",[18,1356,1357],{},"ZIG_PKL_LIBRARY",") names the zig-pkl source directory, ",[18,1360,1361],{},"--zig",[18,1363,1364],{},"ZIG",") the compiler, and ",[18,1367,1368],{},"--no-verify"," skips the check.",[64,1371,1373],{"id":1372},"sandbox","Sandbox",[15,1375,1376,1377,29,1380,29,1383,29,1386,1389,1390,1393,1394,1078,1396,1398],{},"Pkl evaluates the defaults while describing the modules. Resource reads (",[18,1378,1379],{},"file:",[18,1381,1382],{},"env:",[18,1384,1385],{},"prop:",[18,1387,1388],{},"https:",", and every other resource scheme) are denied, environment variables and external properties are empty, and no resource readers run. A default that reads a resource fails to evaluate, is reported as a warning, and is left out of the bindings. ",[18,1391,1392],{},"--allow-resource \u003Cregex>"," allows reads of matching URIs; allowing ",[18,1395,1382],{},[18,1397,1385],{}," also exposes the environment or the properties.",[15,1400,1401,1404,1405,29,1408,29,1410,29,1413,29,1416,1419,1420,1423,1424,1426],{},[18,1402,1403],{},"pkl:platform"," is part of the standard library, and the module allowlist cannot exclude it. In a described module that imports it, or whose source mentions it, a default is copied only when the declaration is a literal scalar (",[18,1406,1407],{},"\"stable\"",[18,1409,1124],{},[18,1411,1412],{},"true",[18,1414,1415],{},"1.s",[18,1417,1418],{},"4.mb","). Every other default in that module is reported as a warning and left out, so a local or another property cannot carry the host operating system or architecture into the bindings. The generator reads the source of every described module, including the file behind a local project dependency, and nothing else. An ",[18,1421,1422],{},"import(...)"," expression whose argument is not a plain string, or contains an escape, is treated the same way. When a module's source cannot be read, none of its defaults are copied. A default in a module that does not mention ",[18,1425,1403],{}," can still copy a host value by reading a property of some other module. Other module imports are evaluated. An import of a local file can therefore copy that file's values into a default; those values are part of the module being described.",[15,1428,1429,1430,1432,1433,1354,1435,1437,1438,1440],{},"The same modules, options, and Pkl version produce the same files on every platform, aside from a default that copies a host value from a module the declaration does not identify as ",[18,1431,1403],{},". Every file is canonicalized with the Zig formatter. ",[18,1434,1353],{},[18,1436,1357],{},") is required for the default type-check; ",[18,1439,1368],{}," writes the files without it.",[64,1442,1444],{"id":1443},"diagnostics","Diagnostics",[15,1446,1447,1448,1451],{},"The generator reports every problem it finds in one run, each with the ",[18,1449,1450],{},"uri:line:column"," of the Pkl declaration:",[69,1453,1457],{"className":1454,"code":1456,"language":320,"meta":73},[1455],"language-text","file:\u002F\u002F\u002F...\u002Fcollision.pkl:4:1: error: properties `fooBar` and `foo_bar` both map to field `foo_bar`; rename one with `@zig.Name`\n",[18,1458,1456],{"__ignoreMap":73},[15,1460,1461,1462,475,1464,1466,1467,1469,1470,1472,1473,1475,1476,1479],{},"Rejected inputs include name collisions between fields, declarations, files, and index namespaces; invalid ",[18,1463,678],{},[18,1465,1281],{}," values; ",[18,1468,678],{}," on a module, which ",[18,1471,1281],{}," replaces; ",[18,1474,91],{}," annotations imported from a module other than the zig-pkl annotations package; function, ",[18,1477,1478],{},"nothing",", undeclared, and unsupported types; and unions whose members accept the same values. Each problem is reported once. Pkl evaluation errors, including annotation constraint failures, are reported verbatim. Warnings, such as defaults that cannot be represented, are printed without failing the run.",[64,1481,1483],{"id":1482},"cli","CLI",[69,1485,1488],{"className":1486,"code":1487,"language":320,"meta":73},[1455],"Usage: zig-pkl-gen [options] \u003Cmodule>...\n\n  -o, --output-dir \u003Cdir>    Directory for generated files (required)\n  --project-dir \u003Cdir>       Directory with the PklProject that resolves @dependency imports\n  --package \u003Cmatch>=\u003Cpath>  Place modules whose name or URI starts with \u003Cmatch> under \u003Cpath>\n  --index-file \u003Cpath>       Index file, a relative .zig path inside the output\n                            directory; modules go in its directory (default: root.zig)\n  --pkl \u003Cpath>              Pkl executable (default: $PKL_EXEC, then pkl on PATH)\n  --allow-resource \u003Cregex>  Let defaults read resources whose URI matches this Pkl\n                            pattern, such as file: or env:HOME (repeatable; default: none)\n  --library \u003Cdir>           zig-pkl source directory used to type-check the bindings\n                            (default: $ZIG_PKL_LIBRARY)\n  --zig \u003Cpath>              Zig executable for type-checking (default: $ZIG, then zig)\n  --no-verify               Write the bindings without type-checking them\n  --check                   Exit with status 1 when any generated file is out of date\n  --force                   Overwrite or delete files the generator did not write\n  -h, --help                Show this help\n  --version                 Print the zig-pkl version\n",[18,1489,1487],{"__ignoreMap":73},[15,1491,1492,1493,1495],{},"Exit status is 0 on success, 1 when generation fails, type-checking fails, a file is not owned by the generator, or ",[18,1494,1338],{}," finds stale files, and 2 for usage errors.",[64,1497,1499],{"id":1498},"library-api","Library API",[15,1501,1502,1505,1506,1509,1510,1513,1514,1078,1517,1520,1521,1524,1525,1528,1529,1532,1533,1536,1537,1540],{},[18,1503,1504],{},"zig_pkl.codegen.generate(allocator, io, manager, options, &diagnostics)"," runs the same pipeline on an existing ",[18,1507,1508],{},"Manager","; ",[18,1511,1512],{},"options.verify"," is either ",[18,1515,1516],{},".skip",[18,1518,1519],{},".{ .check = ... }"," with the toolchain to type-check with. ",[18,1522,1523],{},"generateWithExecutable"," starts and stops its own server. ",[18,1526,1527],{},"zig_pkl.codegen.plan.plan"," is the pure planning stage: it maps a ",[18,1530,1531],{},"schema.Description"," to files without Pkl or the file system. ",[18,1534,1535],{},"zig_pkl.codegen.verify.check"," type-checks a plan, and ",[18,1538,1539],{},"writeFiles"," applies one to a directory under the manifest rules above.",[64,1542,1544],{"id":1543},"build-integration","Build integration",[15,1546,1547],{},"From a dependent package:",[69,1549,1551],{"className":232,"code":1550,"language":234,"meta":73,"style":73},"const zig_pkl = b.dependency(\"zig_pkl\", .{ .target = target, .optimize = optimize });\nconst codegen = b.addRunArtifact(zig_pkl.artifact(\"zig-pkl-gen\"));\ncodegen.setCwd(b.path(\".\"));\ncodegen.addArgs(&.{ \"--zig\", b.graph.zig_exe, \"--library\" });\ncodegen.addDirectoryArg(zig_pkl.path(\".\"));\ncodegen.addArgs(&.{ \"--project-dir\", \".\", \"-o\", \"src\u002Fbindings\", \"pkl\u002FService.pkl\" });\ncodegen.addPassthruArgs();\nb.step(\"codegen\", \"Regenerate the Pkl bindings\").dependOn(&codegen.step);\n",[18,1552,1553,1598,1631,1658,1698,1721,1759,1771],{"__ignoreMap":73},[77,1554,1555,1557,1560,1562,1565,1567,1570,1572,1575,1578,1581,1583,1586,1588,1591,1593,1596],{"class":79,"line":80},[77,1556,241],{"class":125},[77,1558,1559],{"class":244}," zig_pkl",[77,1561,248],{"class":125},[77,1563,1564],{"class":244}," b",[77,1566,328],{"class":94},[77,1568,1569],{"class":90},"dependency",[77,1571,254],{"class":94},[77,1573,1574],{"class":98},"\"zig_pkl\"",[77,1576,1577],{"class":94},", .{ .",[77,1579,1580],{"class":244},"target",[77,1582,248],{"class":125},[77,1584,1585],{"class":244}," target",[77,1587,373],{"class":94},[77,1589,1590],{"class":244},"optimize",[77,1592,248],{"class":125},[77,1594,1595],{"class":244}," optimize",[77,1597,455],{"class":94},[77,1599,1600,1602,1605,1607,1609,1611,1614,1616,1618,1620,1623,1625,1628],{"class":79,"line":87},[77,1601,241],{"class":125},[77,1603,1604],{"class":244}," codegen",[77,1606,248],{"class":125},[77,1608,1564],{"class":244},[77,1610,328],{"class":94},[77,1612,1613],{"class":90},"addRunArtifact",[77,1615,254],{"class":94},[77,1617,492],{"class":244},[77,1619,328],{"class":94},[77,1621,1622],{"class":90},"artifact",[77,1624,254],{"class":94},[77,1626,1627],{"class":98},"\"zig-pkl-gen\"",[77,1629,1630],{"class":94},"));\n",[77,1632,1633,1636,1638,1641,1643,1646,1648,1651,1653,1656],{"class":79,"line":105},[77,1634,1635],{"class":244},"codegen",[77,1637,328],{"class":94},[77,1639,1640],{"class":90},"setCwd",[77,1642,254],{"class":94},[77,1644,1645],{"class":244},"b",[77,1647,328],{"class":94},[77,1649,1650],{"class":90},"path",[77,1652,254],{"class":94},[77,1654,1655],{"class":98},"\".\"",[77,1657,1630],{"class":94},[77,1659,1660,1662,1664,1667,1669,1671,1674,1677,1679,1681,1683,1686,1688,1691,1693,1696],{"class":79,"line":115},[77,1661,1635],{"class":244},[77,1663,328],{"class":94},[77,1665,1666],{"class":90},"addArgs",[77,1668,254],{"class":94},[77,1670,387],{"class":125},[77,1672,1673],{"class":94},".{ ",[77,1675,1676],{"class":98},"\"--zig\"",[77,1678,29],{"class":94},[77,1680,1645],{"class":244},[77,1682,328],{"class":94},[77,1684,1685],{"class":244},"graph",[77,1687,328],{"class":94},[77,1689,1690],{"class":244},"zig_exe",[77,1692,29],{"class":94},[77,1694,1695],{"class":98},"\"--library\"",[77,1697,455],{"class":94},[77,1699,1700,1702,1704,1707,1709,1711,1713,1715,1717,1719],{"class":79,"line":122},[77,1701,1635],{"class":244},[77,1703,328],{"class":94},[77,1705,1706],{"class":90},"addDirectoryArg",[77,1708,254],{"class":94},[77,1710,492],{"class":244},[77,1712,328],{"class":94},[77,1714,1650],{"class":90},[77,1716,254],{"class":94},[77,1718,1655],{"class":98},[77,1720,1630],{"class":94},[77,1722,1723,1725,1727,1729,1731,1733,1735,1738,1740,1742,1744,1747,1749,1752,1754,1757],{"class":79,"line":132},[77,1724,1635],{"class":244},[77,1726,328],{"class":94},[77,1728,1666],{"class":90},[77,1730,254],{"class":94},[77,1732,387],{"class":125},[77,1734,1673],{"class":94},[77,1736,1737],{"class":98},"\"--project-dir\"",[77,1739,29],{"class":94},[77,1741,1655],{"class":98},[77,1743,29],{"class":94},[77,1745,1746],{"class":98},"\"-o\"",[77,1748,29],{"class":94},[77,1750,1751],{"class":98},"\"src\u002Fbindings\"",[77,1753,29],{"class":94},[77,1755,1756],{"class":98},"\"pkl\u002FService.pkl\"",[77,1758,455],{"class":94},[77,1760,1761,1763,1765,1768],{"class":79,"line":137},[77,1762,1635],{"class":244},[77,1764,328],{"class":94},[77,1766,1767],{"class":90},"addPassthruArgs",[77,1769,1770],{"class":94},"();\n",[77,1772,1773,1775,1777,1780,1782,1785,1787,1790,1792,1795,1797,1799,1801,1803,1805],{"class":79,"line":152},[77,1774,1645],{"class":244},[77,1776,328],{"class":94},[77,1778,1779],{"class":90},"step",[77,1781,254],{"class":94},[77,1783,1784],{"class":98},"\"codegen\"",[77,1786,29],{"class":94},[77,1788,1789],{"class":98},"\"Regenerate the Pkl bindings\"",[77,1791,260],{"class":94},[77,1793,1794],{"class":90},"dependOn",[77,1796,254],{"class":94},[77,1798,387],{"class":125},[77,1800,1635],{"class":244},[77,1802,328],{"class":94},[77,1804,1779],{"class":244},[77,1806,343],{"class":94},[15,1808,1809,1810,1813],{},"Checking the bindings in keeps ordinary builds free of a Pkl dependency. ",[18,1811,1812],{},"zig build codegen -- --check"," verifies them.",[15,1815,1816],{},"In this repository:",[1027,1818,1819,1835],{},[1030,1820,1821,1823,1824,475,1827,1830,1831,1834],{},[18,1822,496],{}," regenerates ",[18,1825,1826],{},"tests\u002Fcodegen\u002Fsnapshots",[18,1828,1829],{},"examples\u002Fcodegen\u002Fsrc\u002Fbindings",". Arguments after ",[18,1832,1833],{},"--"," are passed to every run.",[1030,1836,1837,1840,1841,1844],{},[18,1838,1839],{},"zig build codegen-test"," runs the planner tests, which type-check every planned fixture; the live tests against Pkl, which skip when Pkl is absent unless ",[18,1842,1843],{},"ZIG_PKL_REQUIRE_PKL=1","; decoding of an evaluated configuration through the generated loaders; compilation of the snapshot bindings for x86_64 and aarch64 Linux, x86_64 and aarch64 macOS, x86_64 Windows, riscv64 Linux, and x86 Linux; and the example package's tests.",[64,1846,1848],{"id":1847},"limitations","Limitations",[1027,1850,1851,1854,1857,1862,1877,1884,1887,1892,1895,1904,1909],{},[1030,1852,1853],{},"An abstract class becomes a union of the concrete subclasses found in the described modules. A subclass declared in a module that the targets never reference is not a member, and its values fail to decode.",[1030,1855,1856],{},"A value of an open class decodes into the declared struct and loses fields that only a subclass declares.",[1030,1858,1859,1861],{},[18,1860,826],{}," decodes to a slice; Zig does not check uniqueness.",[1030,1863,1864,1866,1867,1092,1869,1866,1871,1873,1874,1876],{},[18,1865,716],{}," maps to ",[18,1868,721],{},[18,1870,746],{},[18,1872,768],{}," even though Pkl limits it to the ",[18,1875,716],{}," range.",[1030,1878,1879,1880,1883],{},"Constraints on types, such as ",[18,1881,1882],{},"Int(isPositive)",", are not represented in Zig; Pkl enforces them during evaluation.",[1030,1885,1886],{},"Recursive type aliases are rejected by Pkl, so recursion is only supported through classes.",[1030,1888,1889,1891],{},[18,1890,1084],{}," type aliases are mapped from a fixed table for Pkl 0.32.2. Aliases from other standard library modules are expanded through reflection.",[1030,1893,1894],{},"Object defaults are not copied into Zig, and regex, bytes, reference, and pair defaults are reported as unrepresentable; Pkl still applies all of them when it evaluates a configuration.",[1030,1896,1897,1900,1901,1903],{},[18,1898,1899],{},"ref.Domain"," and its subclasses decode as ",[18,1902,911],{},", because the domain object is only described by its class.",[1030,1905,1906,1907,328],{},"Type-checking needs the zig-pkl sources on disk and a Zig compiler; without them, pass ",[18,1908,1368],{},[1030,1910,1911,1912,1914],{},"A default that does not mention ",[18,1913,1403],{},", in a module that does not import it, can still copy a host value from another module. That value is the machine where generation ran.",[1916,1917,1918],"style",{},"html pre.shiki code .sJ8bj, html code.shiki .sJ8bj{--shiki-default:#6A737D;--shiki-dark:#6A737D}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 .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .szBVR, html code.shiki .szBVR{--shiki-default:#D73A49;--shiki-dark:#F97583}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 .s4XuR, html code.shiki .s4XuR{--shiki-default:#E36209;--shiki-dark:#FFAB70}",{"title":73,"searchDepth":87,"depth":87,"links":1920},[1921,1922,1924,1925,1926,1927,1928,1929,1930,1931,1932,1933],{"id":66,"depth":87,"text":67},{"id":500,"depth":87,"text":1923},"The @zig annotations",{"id":682,"depth":87,"text":683},{"id":1183,"depth":87,"text":1184},{"id":1320,"depth":87,"text":1321},{"id":1342,"depth":87,"text":1343},{"id":1372,"depth":87,"text":1373},{"id":1443,"depth":87,"text":1444},{"id":1482,"depth":87,"text":1483},{"id":1498,"depth":87,"text":1499},{"id":1543,"depth":87,"text":1544},{"id":1847,"depth":87,"text":1848},"zig-pkl-gen turns Pkl modules into Zig types that decode with zig_pkl.convert. Each module becomes one Zig file. The generated decode, deinit, and load helpers use the same ownership rules as the typed core: the caller owns every decoded value and releases it with deinit and the allocator it decoded with.","md",{},"\u002Fcodegen",{"title":6,"description":1934},"MSca8xP2wq2fdotcduzuVlw2tQCuxSsyduWREzL338g","docs\u002Fcodegen.md",[1942,1946,1950,1954,1958,1962,1966,1970,1974,1978,1982,1985,1989],{"title":1943,"path":1944,"stem":1945},"Version compatibility","\u002Fguides\u002Fcompatibility","guides\u002Fcompatibility",{"title":1947,"path":1948,"stem":1949},"Concurrency","\u002Fguides\u002Fconcurrency","guides\u002Fconcurrency",{"title":1951,"path":1952,"stem":1953},"Errors","\u002Fguides\u002Ferrors","guides\u002Ferrors",{"title":1955,"path":1956,"stem":1957},"Evaluation","\u002Fguides\u002Fevaluation","guides\u002Fevaluation",{"title":1959,"path":1960,"stem":1961},"External readers","\u002Fguides\u002Fexternal-readers","guides\u002Fexternal-readers",{"title":1963,"path":1964,"stem":1965},"Installation","\u002Fguides\u002Finstallation","guides\u002Finstallation",{"title":1967,"path":1968,"stem":1969},"Logging","\u002Fguides\u002Flogging","guides\u002Flogging",{"title":1971,"path":1972,"stem":1973},"Migrating from pkl-zig","\u002Fguides\u002Fmigration","guides\u002Fmigration",{"title":1975,"path":1976,"stem":1977},"Ownership","\u002Fguides\u002Fownership","guides\u002Fownership",{"title":1979,"path":1980,"stem":1981},"Projects","\u002Fguides\u002Fprojects","guides\u002Fprojects",{"title":67,"path":1983,"stem":1984},"\u002Fguides\u002Fquickstart","guides\u002Fquickstart",{"title":1986,"path":1987,"stem":1988},"Readers","\u002Fguides\u002Freaders","guides\u002Freaders",{"title":1990,"path":1991,"stem":1992},"Security","\u002Fguides\u002Fsecurity","guides\u002Fsecurity",1792908673087]