1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418
// Copyright 2017 Jeremy Wall <jeremy@marzhillstudios.com> // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #![feature(trace_macros,log_syntax)] //! # ucg, A universal configuration grammar. //! //! Ucg defines a common grammar for describing a collection of configuration values. //! ucg allows you to specify configuration values with a syntax that that is immutable, //! comoposable with copy-on-write semantics, and safe. //! //! ## Example //! //! ```ucg //! // named bindings //! let host = "mysql.internal.net"; //! let port = 8080 //! //! // format strings //! let connstr = "mysql://@:@" % (host, port); //! //! // tuples //! let dbconf = { //! connstr = connstr, //! database = "mydb", //! // lists //! tables = ["posts", "comments", "users"], //! }; //! ``` //! //! ## Syntax //! //! ucg is a safe language with type inference that tries to guarantee that it will halt. //! A valid ucg file is composesed of a series of statements. Statements are any valid //! ucg expression terminated by a semicolon. //! //! ### Reserved words //! //! The following words are reserved in ucg and can't be used as named bindings. //! //! * true //! * false //! * let //! * import //! * as //! * select //! * macro //! * env //! * map //! * filter //! * NULL //! //! ### Primitive types //! //! ucg has a relatively simple syntax with a few primitive types, Null, Boolean, Int, Float, and String. //! //! ### Boolean //! //! A Boolean is either `true` or `false`. //! //! ```uct //! true; //! false; //! ``` //! //! #### Int //! //! An Int is any integer number. //! //! ```ucg //! 1; // a single Integer //! ``` //! //! #### Float //! //! A Float is any number with a decimal point. //! //! ```ucg //! 1.0; // A typical float. //! 1. // You can leave off the 0 after the decimal point. //! .1 // the leading 0 is also optional. //! ``` //! //! #### String //! //! A String is any quoted text. Backslashes within a string escape the next preceding //! character. //! //! ``` ucg //! "foo"; // a simple string //! "I'm a \"fine\" looking string"; // escaped quotes in a string. //! ``` //! //! #### NULL or the Empty type. //! //! A NULL is an empty type. It represents no value. //! //! ```ucg //! let empty = NULL; //! ``` //! //! ### Complex types //! //! ucg has two complex data types, Lists and Tuples. //! //! #### Lists //! //! Lists are surrounded with square brackets `[ ]` and have comma separated elements. //! //! ```ucg //! [1, 2, 3]; // A simple list of numbers. //! //! [[1, 2], [3, 4]] // A deep list with embedded lists inside. //! ``` //! //! Lists are 0 indexed and you can index into them using the dotted selector syntax. //! //! ```ucg //! let mylist = [0, 1, 2, 3]; //! //! let zero = mylist.0; //! ``` //! //! ##### List macros //! //! ucg supports a couple of ways to use macros for mapping or filtering a list to a new list. //! //! A map expression starts with the map keyword followed by the name of a macro with exactly //! one argument, a `.`, and the name of the output field for the macro. ucg will apply the macro //! to each element of the list and then take the output field from the resulting tuple and add append //! it to the resulting list. If the output field does not exist in the macro it will be a compile //! error. //! //! ```ucg //! let list = [1, 2, 3, 4]; //! let mapper = macro(item) => { result = item + 1 }; //! //! // results in: [2, 3, 4, 5] //! let mapped = map mapper.result list; //! ``` //! // //! A filter expression starts with the filter keyword followed by the name of a macro with exactly //! one argument, a `.`, and the name of the output field for the macro. The filter will apply the //! macro to each element of the list and if the output field is a Value that is not NULL then the //! list element is appended to the output list. If the output field returns a NULL Value then the //! element is not appended to the output list. If the output field does not exist in the macro it //! will be a compile error. //! //! ```ucg //! let list = ["foo", "bar", "foo", "bar"]; //! let filtrator = macro(item) => { //! ok = select item NULL { //! foo = 1 //! } //! }; //! //! // results in: ["foo", "foo"] //! let filtered = filter filtrator.ok list; //! ``` //! //! #### Tuple //! //! Tuple's are an ordered collection of name, value pairs. They are bounded by curly braces `{ }` //! and contain name = value pairs separated by commas. Trailing commas are permitted. The name must //! be a bareword without quotes. //! //! ```ucg //! let mytuple = { //! field1 = "value1", //! field2 = "value2", //! }; //! ``` //! //! Tuples can be indexed using dotted selector syntax. //! //! ```ucg //! let field = mytuple.fields1; //! ``` //! //! ### Expressions //! //! #### Selectors //! //! Selectors are references to a bound value in ucg. They can index arbitrarily deep into either tuples or lists. //! The head of a selector can be any expression that resolves to a tuple or list. Optionally a selector can also be //! followed by either a bareword to index a tuple field or an integer to index a list position. //! //! The simplest selector is just a reference to a bound value by name. //! //! ```ucg //! let mytuple = { //! field1 = "a string", //! field2 = [{ //! subfield1 = 1, //! }]; //! }; //! //! mytuple.field2.0; // descend into a deeply nested tuple and array. //! ``` //! //! The `env` variable is a reserved variable that always contains a tuple with any environment //! variables in it. //! //! Attempting to reference an enviroment variable that does not exist is a compile error. //! //! #### Binary operators //! //! ##### Numeric operators //! //! ucg supports the following numeric operators, `+`, `-`, `*`, `/` Each one is type safe and infers the types //! from the values they operate on. The operators expect both the left and right operands to be of the same //! type. //! //! ```ucg //! 1 + 1; // result is 2 //! ``` //! //! ##### Concatenation //! //! ucg supports concatenation using the `+` operator. It is typesafe expecting both sides to be of the same type. //! You can concatenate strings or lists but not tuples. //! //! ```ucg //! "foo " + "bar" // result is "foo bar" //! [1,2] + [3,4]; // result is [1,2,3,4] //! ``` //! //! ##### Comparison //! //! ucg supports comparison using the `==`, `!=`, `>`, `<`, `>=`, `<=` operators. They are type safe and expect both //! sides to be of the same type. //! //! The `>`, `<`, `>=`, and `>=` operators are only supported on numeric types. //! //! ```ucg //! 1 > 2; // result is false //! 2 < 3; // result is true //! 10 > "9"; // This is a compile error. //! (1+2) == 3 //! ``` //! The comparison operators expect either a simple value or a grouped expression as their left operand. //! //! The equality operators `==` and `!=` are supported for all types and will perform deep equal comparisons on complex //! types. //! //! ```ucg //! let tpl1 = { //! foo = "bar", //! one = 1 //! }; //! let tpl2 = tpl1{}; // copy the tpl1 tuple //! tpl1 == tpl2; // returns true //! let tpl3 = tpl1{duck="quack"}; //! tpl1 == tpl3; // returns false //! ``` //! //! Note that tuple fields are ordered so a tuple will only be equal if the fields are both in the same order and //! have the same values in them. //! //! ##### Operator Precedence //! //! UCG binary operators follow the typical operator precedence for math. `*` and `/` are higher precendence than //! `+` and `-` which are higher precedence than any of the comparison operators. //! //! #### Copy expressions //! //! ucg Tuples support a form of reuse with copy on write semantics. You can copy a tuple and selectively overwrite fields or add new //! fields to it with the copy expression. To perform a copy first reference the tuple by a bound name and then use `{ field = value, ... }` //! syntax to copy with overridden fields or add completely new fields. When replacing a preexisting field with a new value you cannot //! change the type of the field. This allows you to define a typed shape for a tuple with default values and then provide new values for //! some or all of the fields while still enforcing the same types for those fields. Adding completely new fields has no such restriction. //! //! ```ucg //! let base = { //! field1 = "value1", //! field2 = 100, //! field3 = 5.6, //! }; //! //! let overridden = base{ //! field1 = "new value" //! }; //! //! let expanded = base{ //! field2 = 200, //! field3 = "look ma a new field", //! }; //! ``` //! //! The following will cause an error because the overriden field's value does not match the original. //! //! ```ucg //! let bad = base{ //! field1 = 300, // Error!!! must be a string. //! }; //! //! ``` //! //! #### Conditional data //! //! ucg supports a limited form of conditional data selection of using the select expression. A select expression starts with the `select` //! keyword and is followed by a an expression resolving to a string naming the field to select, an expression resolving to the default value, //! and a tuple to select the field from. If the field selected is not in the tuple then the default value will be used. //! //! ```ucg //! let want = "baz"; //! //! // field default //! select want, "quux", { //! baz = "foo", //! fuzz = "bang", //! }; // result will be "foo" //! //! // field default //! select "quack", "quux", { //! baz = "foo", //! fuzz = "bang", //! }; // result will be "quux" //! ``` //! //! #### Macros //! //! Macros look like functions but they are resolved at compile time and configurations don't execute so they never appear in output. //! They are useful for constructing tuples of a certain shape or otherwise promoting data reuse. You define a macro with the `macro` //! keyword followed by the arguments in parentheses, a `=>`, and then a tuple. //! //! ```ucg //! let myfunc = macro (arg1, arg2) => { //! host = arg1, //! port = arg2, //! connstr = "couchdb://@:@" % (arg1, arg2), //! } //! //! let my_dbconf = myfunc("couchdb.example.org", "9090"); //! //! let my_dbhost = dbconf.host; //! ``` //! //! macros always resolve to a tuple. If you want to get a single value out you can use selector syntax to retrieve it. //! //! ### Statements //! //! There are 3 kinds of statements in a ucg configuration file. expression statements, let statements, and import statements. //! All ucg statements must be terminated by a semicolon. //! //! * expression statements //! //! The simplest and least useful is the expression statement. It is any valid expression followed by a semicolon. //! //! ```ucg //! 1; //! 4 / 2; //! "foo"; //! "foo" + "bar"; //! ``` //! //! Despite the fact that these are valid the results are thrown away and can essentially be considered a noop. If we //! ever create a repl for ucg statements they may prove more useful. //! //! * Let statements //! //! The let expression binds the result of any valid expression to a name. It starts with the `let` keyword and is followed by //! the name of the binding, an `=`, and a valid ucg expression. //! //! ```ucg //! let name = "foo"; //! ``` //! //! * Import statement //! //! The import statement imports the contents of another ucg file into the current file with a name. The imported files bound //! values are exposed as a tuple in the referencing file. It starts with the `import` keyword and is followed by a quoted path //! to the ucg file, the keyword `as`, and a name for the imported values. //! //! ```ucg //! import "dbconfigs.ucg" as dbconfigs; //! //! let mysqlconf = dbconfigs.mysql; //! ``` // The following is necessary to allow the macros in tokenizer and parse modules // to succeed. #![recursion_limit = "128"] #[macro_use] extern crate nom; #[macro_use] extern crate nom_locate; extern crate serde_json; #[macro_use] pub mod ast; #[macro_use] pub mod tokenizer; pub mod build; pub mod convert; pub mod error; pub mod parse; mod format; pub use ast::Expression; pub use ast::Statement; pub use ast::Value; pub use build::Builder; pub use build::Val; pub use parse::parse;