1 /* libpoke.h - Public header for libpoke. */ 2 3 /* Copyright (C) 2020, 2021 Jose E. Marchesi */ 4 5 /* This program is free software: you can redistribute it and/or modify 6 * it under the terms of the GNU General Public License as published by 7 * the Free Software Foundation, either version 3 of the License, or 8 * (at your option) any later version. 9 * 10 * This program is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU General Public License for more details. 14 * 15 * You should have received a copy of the GNU General Public License 16 * along with this program. If not, see <http://www.gnu.org/licenses/>. 17 */ 18 19 #ifndef LIBPOKE_H 20 #define LIBPOKE_H 21 22 #include <stdint.h> 23 #include <stdarg.h> 24 25 #if defined BUILDING_LIBPOKE && HAVE_VISIBILITY 26 #define LIBPOKE_API __attribute__ ((visibility ("default"))) 27 #else 28 #define LIBPOKE_API 29 #endif 30 31 typedef struct pk_compiler *pk_compiler; 32 typedef struct pk_ios *pk_ios; 33 typedef uint64_t pk_val; 34 35 /* The following status codes are returned by pk_errno function. */ 36 37 #define PK_OK 0 38 #define PK_ERROR 1 39 #define PK_ENOMEM 2 40 #define PK_EEOF 3 41 #define PK_EINVAL 4 42 43 struct pk_color 44 { 45 int red; 46 int green; 47 int blue; 48 }; 49 50 /* Terminal output callbacks. */ 51 52 struct pk_term_if 53 { 54 /* Flush the output in the terminal. */ 55 void (*flush_fn) (void); 56 57 /* Output a NULL-terminated C string. */ 58 void (*puts_fn) (const char *str); 59 60 /* Output a formatted string. */ 61 void (*printf_fn) (const char *format, ...); 62 63 /* Output LVL levels of indentation, using STEP white chars in each 64 indentation level. */ 65 void (*indent_fn) (unsigned int lvl, unsigned int step); 66 67 /* Mark the beginning of a styling class with name CLASS. */ 68 void (*class_fn) (const char *class); 69 70 /* Mark the end of a styling class with name CLASS. This function 71 returns 0 if the given class is not active and therefore can't be 72 ended. 1 otherwise. */ 73 int (*end_class_fn) (const char *class); 74 75 /* Mark the beginning of an hyperlink with url URL and identifier 76 ID. The identifier can be NULL. */ 77 void (*hyperlink_fn) (const char *url, const char *id); 78 79 /* Mark the end of the current hyperlink. This function returns 0 80 if there is no currently an hyperlink open to close. 1 81 otherwise. */ 82 int (*end_hyperlink_fn) (void); 83 84 /* Get the current foreground color. */ 85 struct pk_color (*get_color_fn) (void); 86 87 /* Get the current background color. */ 88 struct pk_color (*get_bgcolor_fn) (void); 89 90 /* Set the foreground color. */ 91 void (*set_color_fn) (struct pk_color color); 92 93 /* Set the background color. */ 94 void (*set_bgcolor_fn) (struct pk_color color); 95 }; 96 97 /* Create and return a new Poke incremental compiler. 98 99 RTPATH should contain the name of a directory where the compiler 100 can find its run-time support files. 101 102 TERM_IF is a pointer to a struct pk_term_if containing pointers to 103 functions providing the output routines to be used by the 104 incremental compiler. 105 106 If there is an error creating the compiler this function returns 107 NULL. */ 108 109 pk_compiler pk_compiler_new (struct pk_term_if *term_if) LIBPOKE_API; 110 111 /* Destroy an instance of a Poke incremental compiler. 112 113 PKC is a previously created incremental compiler. */ 114 115 void pk_compiler_free (pk_compiler pkc) LIBPOKE_API; 116 117 /* Error code of last operation. 118 119 This function returns the status corresponding to the given PK 120 compiler. This status is updated by every call performed in 121 the API, and is one of the PK_* status codes defined above. 122 If PKC is NULL returns PK_ERROR. */ 123 124 int pk_errno (pk_compiler pkc) LIBPOKE_API; 125 126 /* Compile a Poke program from the given file FILENAME. 127 128 If not NULL, *EXIT_STATUS is set to the status resulting from the 129 execution of the program. 130 131 Return PK_ERROR in case of a compilation error. Otherwise, 132 return PK_OK. */ 133 134 int pk_compile_file (pk_compiler pkc, const char *filename, 135 int *exit_status) LIBPOKE_API; 136 137 /* Compile a Poke program from a memory buffer. 138 139 BUFFER is a NULL-terminated string. 140 141 If not NULL, *END is set to the first character in BUFFER that is 142 not part of the compiled entity. 143 144 Return PK_ERROR in case of a compilation error. Otherwise, 145 return PK_OK. */ 146 147 int pk_compile_buffer (pk_compiler pkc, const char *buffer, 148 const char **end) LIBPOKE_API; 149 150 /* Like pk_compile_buffer but compile and execute a single Poke 151 statement, which may evaluate to a value if it is an "expression 152 statement". 153 154 VAL, if given, is a pointer to a pk_val variable that is set to the 155 result value of an expression-statement, or to PK_NULL. */ 156 157 int pk_compile_statement (pk_compiler pkc, const char *buffer, 158 const char **end, pk_val *val) LIBPOKE_API; 159 160 /* Like pk_compile_buffer but compile and execute a single Poke 161 expression, which evaluates to a value. 162 163 VAL, if given, is a pointer to a pk_val variable that is set to the 164 result value of executing the expression. */ 165 166 int pk_compile_expression (pk_compiler pkc, const char *buffer, 167 const char **end, pk_val *val) LIBPOKE_API; 168 169 /* Load a module using the given compiler. 170 171 If the module cannot be loaded, return PK_ERROR. Otherwise, 172 return PK_OK. */ 173 174 int pk_load (pk_compiler pkc, const char *module) LIBPOKE_API; 175 176 /* Print a disassembly of a named function. 177 178 FNAME is the name of the function to disassemble. It should be 179 defined in the global environment of the incremental compiler. 180 181 NATIVE_P is a flag determining whether to emit a native disassembly 182 or a PVM disassembly. 183 184 If there is no function named FNAME, return PK_ERROR. Otherwise, 185 return PK_OK. */ 186 187 int pk_disassemble_function (pk_compiler pkc, const char *fname, 188 int native_p) LIBPOKE_API; 189 190 /* Print a disassembly of the body of the given function value. 191 192 VAL is a function value. 193 194 NATIVE_P is a flag determining whether to emit a native disassembly 195 or a PVM disassembly. 196 197 If VAL is not a valid function value, return PK_ERROR. Otherwise 198 return PK_OK. */ 199 200 int pk_disassemble_function_val (pk_compiler pkc, pk_val val, 201 int native_p) LIBPOKE_API; 202 203 /* Print a disassembly of an expression. 204 205 STR is a NULL-terminated string containing a Poke expression. 206 207 NATIVE_P is a flag determining whether to emit a native disassembly 208 or a PVM disassembly. 209 210 If STR is not a valid Poke expression, return PK_ERROR. Otherwise 211 return PK_OK. */ 212 213 int pk_disassemble_expression (pk_compiler pkc, const char *str, 214 int native_p) LIBPOKE_API; 215 216 /* Print a profiling summary corresponding to the current state of the 217 PVM. */ 218 219 void pk_print_profile (pk_compiler pkc) LIBPOKE_API; 220 221 /* Reset the profiling counters. If the PVM hasn't been compiled with 222 profiling support this is a no-operation. */ 223 224 void pk_reset_profile (pk_compiler pkc) LIBPOKE_API; 225 226 /* Set the QUIET_P flag in the compiler. If this flag is set, the 227 incremental compiler emits as few output as possible. */ 228 229 void pk_set_quiet_p (pk_compiler pkc, int quiet_p) LIBPOKE_API; 230 231 /* Install a handler for alien tokens in the incremental compiler. 232 The handler gets a string with the token identifier (for $foo it 233 would get `foo') and should return a string containing the 234 resolving identifier. If the handler returns NULL, then the alien 235 token is not recognized as such in the compiler and ERRMSG points 236 to an explicative error message. */ 237 238 typedef char *(*pk_alien_token_handler_fn) (const char *id, 239 char **errmsg); 240 void pk_set_alien_token_fn (pk_compiler pkc, 241 pk_alien_token_handler_fn cb) LIBPOKE_API; 242 243 /* Set the LEXICAL_CUCKOLDING_P flag in the compiler. If this flag is 244 set, alien tokens are recognized and processed by calling the 245 handler installed by pk_set_alien_token_fn. 246 247 Note that the flag will be honored only if the user has installed a 248 handler for alien tokens. */ 249 250 void pk_set_lexical_cuckolding_p (pk_compiler pkc, 251 int lexical_cuckolding_p) LIBPOKE_API; 252 253 /* Complete the name of a variable, function or type declared in the 254 global environment of the given incremental compiler. 255 256 This function is to be called repeatedly when generating potential 257 command line completions. It returns command line completion based 258 upon the current state of PKC. 259 260 TEXT is the partial word to be completed. STATE is zero the first 261 time the function is called and non-zero for each subsequent call. 262 263 On each call, the function returns a potential completion. It 264 returns NULL to indicate that there are no more possibilities 265 left. */ 266 267 char *pk_completion_function (pk_compiler pkc, 268 const char *text, int state) LIBPOKE_API; 269 270 /* Complete the tag of an IOS. 271 272 TEXT is the partial word to be completed. STATE is zero the first 273 time the function is called and non-zero for each subsequent call. 274 275 On each call, the function returns the tag of an IOS for which 276 that tag and TEXT share a common substring. It returns NULL to 277 indicate that there are no more such tags. */ 278 279 char *pk_ios_completion_function (pk_compiler pkc, 280 const char *x, int state) LIBPOKE_API; 281 282 /* Return the handler operated by the given IO space. */ 283 284 const char *pk_ios_handler (pk_ios ios) LIBPOKE_API; 285 286 /* Return the current IO space, or NULL if there are open spaces in 287 the given Poke compiler. */ 288 289 pk_ios pk_ios_cur (pk_compiler pkc) LIBPOKE_API; 290 291 /* Set the current IO space in the given incremental compiler. */ 292 293 void pk_ios_set_cur (pk_compiler pkc, pk_ios ios) LIBPOKE_API; 294 295 /* Return the IO space operating the given HANDLER. Return NULL if no 296 such space exist in the given Poke incremental compiler. */ 297 298 pk_ios pk_ios_search (pk_compiler pkc, const char *handler) LIBPOKE_API; 299 300 /* Return the IO space having the given ID. Return NULL if no such 301 space exist in the given Poke incremental compiler. */ 302 303 pk_ios pk_ios_search_by_id (pk_compiler pkc, int id) LIBPOKE_API; 304 305 /* Return the ID of the given IO space. */ 306 307 int pk_ios_get_id (pk_ios ios) LIBPOKE_API; 308 309 /* Return the name of the device interface. */ 310 311 char *pk_ios_get_dev_if_name (pk_ios ios) LIBPOKE_API; 312 313 /* Return the size of the given IO space, in bits. */ 314 315 uint64_t pk_ios_size (pk_ios ios) LIBPOKE_API; 316 317 /* Return the flags which are active in a given IOS. */ 318 319 #define PK_IOS_F_READ 1 320 #define PK_IOS_F_WRITE 2 321 #define PK_IOS_F_TRUNCATE 8 322 #define PK_IOS_F_CREATE 16 323 324 uint64_t pk_ios_flags (pk_ios ios) LIBPOKE_API; 325 326 /* Open an IO space using a handler and if set_cur is set to 1, make 327 the newly opened IO space the current space. Return PK_IOS_NOID 328 if there is an error opening the space (such as an unrecognized 329 handler). Otherwise, the ID of the new IOS. 330 The error code can be retrieved by pk_errno function. 331 332 FLAGS is a bitmask. The least significant 32 bits are reserved for 333 common flags (the PK_IOS_F_* above). The most significant 32 bits 334 are reserved for IOD specific flags. 335 336 If no PK_IOS_F_READ or PK_IOS_F_WRITE flags are specified, then the 337 IOS will be opened in whatever mode makes more sense. */ 338 339 #define PK_IOS_NOID (-1) /* Represents an invalid IO space identifier */ 340 341 int pk_ios_open (pk_compiler pkc, 342 const char *handler, uint64_t flags, int set_cur_p) LIBPOKE_API; 343 344 /* Close the given IO space, freing all used resources and flushing 345 the space cache associated with the space. */ 346 347 void pk_ios_close (pk_compiler pkc, pk_ios ios) LIBPOKE_API; 348 349 /* Map over all the IO spaces in a given incremental compiler, 350 executing a handler. */ 351 352 typedef void (*pk_ios_map_fn) (pk_ios ios, void *data); 353 void pk_ios_map (pk_compiler pkc, pk_ios_map_fn cb, void *data) LIBPOKE_API; 354 355 /* Map over the declarations defined in the given incremental 356 compiler, executing a handler. 357 358 PKC is a Poke incremental compiler. 359 360 KIND is one of the PK_DECL_KIND_* values defined below. It 361 determines what subset of declarations will be processed by the 362 handler. 363 364 HANDLER is a function of type pk_map_decl_fn. */ 365 366 #define PK_DECL_KIND_VAR 0 367 #define PK_DECL_KIND_FUNC 1 368 #define PK_DECL_KIND_TYPE 2 369 370 typedef void (*pk_map_decl_fn) (int kind, 371 const char *source, 372 const char *name, 373 const char *type, 374 int first_line, int last_line, 375 int first_column, int last_column, 376 void *data); 377 void pk_decl_map (pk_compiler pkc, int kind, 378 pk_map_decl_fn handler, void *data) LIBPOKE_API; 379 380 /* Determine whether there is a declaration with the given name, of 381 the given type. */ 382 383 int pk_decl_p (pk_compiler pkc, const char *name, int kind) LIBPOKE_API; 384 385 /* Given the name of a variable declared in the compiler, return its 386 value. 387 388 If there is no variable defined with name NAME, return PK_NULL. */ 389 390 pk_val pk_decl_val (pk_compiler pkc, const char *name) LIBPOKE_API; 391 392 /* Given the name of a variable declared in the compiler, set a new 393 value to it. 394 395 If there is no varaible defined with NAME, then this is a 396 no-operation. */ 397 398 void pk_decl_set_val (pk_compiler pkc, const char *name, pk_val val) 399 LIBPOKE_API; 400 401 /* Declare a variable in the global environment of the given 402 incremental compiler. 403 404 If the operation is successful, return PK_OK. If a variable with name 405 VARNAME already exists in the environment, return PK_ERROR. */ 406 407 int pk_defvar (pk_compiler pkc, const char *varname, pk_val val) LIBPOKE_API; 408 409 /* Call a Poke function. 410 411 CLS is the closure for the function to call. 412 413 RET is set to the value returned by the function, or to PK_NULL if 414 it is a void function. 415 416 A variable number of function arguments follow, terminated by 417 PK_NULL. 418 419 Return PK_ERROR if there is a problem performing the operation, or if the 420 execution of the function results in an unhandled exception. 421 Return PK_OK otherwise. */ 422 423 int pk_call (pk_compiler pkc, pk_val cls, pk_val *ret, ...) LIBPOKE_API; 424 425 /* Get and set properties of the incremental compiler. */ 426 427 int pk_obase (pk_compiler pkc) LIBPOKE_API; 428 void pk_set_obase (pk_compiler pkc, int obase) LIBPOKE_API; 429 430 unsigned int pk_oacutoff (pk_compiler pkc) LIBPOKE_API; 431 void pk_set_oacutoff (pk_compiler pkc, unsigned int oacutoff) LIBPOKE_API; 432 433 unsigned int pk_odepth (pk_compiler pkc) LIBPOKE_API; 434 void pk_set_odepth (pk_compiler pkc, unsigned int odepth) LIBPOKE_API; 435 436 unsigned int pk_oindent (pk_compiler pkc) LIBPOKE_API; 437 void pk_set_oindent (pk_compiler pkc, unsigned int oindent) LIBPOKE_API; 438 439 int pk_omaps (pk_compiler pkc) LIBPOKE_API; 440 void pk_set_omaps (pk_compiler pkc, int omaps_p) LIBPOKE_API; 441 442 enum pk_omode 443 { 444 PK_PRINT_FLAT, 445 PK_PRINT_TREE 446 }; 447 448 enum pk_omode pk_omode (pk_compiler pkc) LIBPOKE_API; 449 void pk_set_omode (pk_compiler pkc, enum pk_omode omode) LIBPOKE_API; 450 451 int pk_error_on_warning (pk_compiler pkc) LIBPOKE_API; 452 void pk_set_error_on_warning (pk_compiler pkc, 453 int error_on_warning_p) LIBPOKE_API; 454 455 enum pk_endian 456 { 457 PK_ENDIAN_LSB, 458 PK_ENDIAN_MSB 459 }; 460 461 enum pk_endian pk_endian (pk_compiler pkc) LIBPOKE_API; 462 void pk_set_endian (pk_compiler pkc, enum pk_endian endian) LIBPOKE_API; 463 464 enum pk_nenc 465 { 466 PK_NENC_1, 467 PK_NENC_2 468 }; 469 470 enum pk_nenc pk_nenc (pk_compiler pkc) LIBPOKE_API; 471 void pk_set_nenc (pk_compiler pkc, enum pk_nenc nenc) LIBPOKE_API; 472 473 int pk_pretty_print (pk_compiler pkc) LIBPOKE_API; 474 void pk_set_pretty_print (pk_compiler pkc, int pretty_print_p) LIBPOKE_API; 475 476 /*** API for manipulating Poke values. ***/ 477 478 /* PK_NULL is an invalid pk_val. 479 This value should be the same than PVM_NULL in pvm.h. */ 480 481 #define PK_NULL 0x7ULL 482 483 /* Signed integers. */ 484 485 /* Build and return a Poke integer. 486 487 VALUE is the numerical value for the new integer. 488 SIZE is the number of bits composing the integer. 489 490 Return PK_NULL if SIZE exceeds the maximum number of bits supported 491 in Poke integers. */ 492 493 pk_val pk_make_int (int64_t value, int size) LIBPOKE_API; 494 495 /* Return the numerical value stored in the given Poke integer. 496 VAL should be a Poke value of the right type. */ 497 498 int64_t pk_int_value (pk_val val) LIBPOKE_API; 499 500 /* Return the size (in bits) of the given Poke integer. 501 VAL should be a Poke value of the right type. */ 502 503 int pk_int_size (pk_val val) LIBPOKE_API; 504 505 /* Unsigned integers. */ 506 507 /* Build and return a Poke unsigned integer. 508 509 VALUE is the numerical value for the new integer. 510 SIZE is the number of bits composing the integer. 511 512 Return NULL if SIZE exceeds the maximum number of bits supported in 513 Poke integers. */ 514 515 pk_val pk_make_uint (uint64_t value, int size) LIBPOKE_API; 516 517 /* Return the numerical value stored in the given Poke unsigned 518 integer. 519 520 VAL should be a Poke value of the right type. */ 521 522 uint64_t pk_uint_value (pk_val val) LIBPOKE_API; 523 524 /* Return the size (in bits) of the given Poke unsigned integer. 525 VAL should be a Poke value of the right type. */ 526 527 int pk_uint_size (pk_val val) LIBPOKE_API; 528 529 /* Strings. */ 530 531 /* Build and return a Poke string. 532 533 STR is a NULL-terminated string, a copy of which will become the 534 value of the Poke string. */ 535 536 pk_val pk_make_string (const char *str) LIBPOKE_API; 537 538 /* Return a NULL-terminated string with the value of the given Poke 539 string. */ 540 541 const char *pk_string_str (pk_val val) LIBPOKE_API; 542 543 /* Offsets. */ 544 545 /* Build and return a Poke offset. 546 547 MAGNITUDE is either a Poke integer or a Poke unsigned integer, with 548 the magnitude of the offset. 549 550 UNIT is an unsigned 64-bit Poke integer specifying the unit of the 551 offset, i.e. the multiple of the base unit, which is the bit. 552 553 If any of the arguments is not of the right type return PK_NULL. 554 Otherwise return the created offset. */ 555 556 pk_val pk_make_offset (pk_val magnitude, pk_val unit) LIBPOKE_API; 557 558 /* Return the magnitude of the given Poke offset. */ 559 560 pk_val pk_offset_magnitude (pk_val val) LIBPOKE_API; 561 562 /* Return the unit of the given Poke offset. */ 563 564 pk_val pk_offset_unit (pk_val val) LIBPOKE_API; 565 566 /* Structs. */ 567 568 /* Build and return a Poke struct. 569 570 NFIELDS is an uint<64> Poke value specifying the number of fields 571 in the struct. This can be uint<64>0 for an empty struct. 572 573 TYPE is a type Poke value specifying the type of the struct. 574 575 The fields and methods in the created struct are initialized to 576 PK_NULL. */ 577 578 pk_val pk_make_struct (pk_val nfields, pk_val type) LIBPOKE_API; 579 580 /* Get the number of fields of a struct. */ 581 582 pk_val pk_struct_nfields (pk_val sct) LIBPOKE_API; 583 584 /* Get the bit-offset of the field of a struct, relative to the 585 beginning of the struct. 586 587 SCT is the struct value. 588 IDX is the index of the field in the struct. 589 590 The returned bit-offset is an uint<64>. 591 592 If IDX is invalid, PK_NULL is returned. */ 593 594 pk_val pk_struct_field_boffset (pk_val sct, uint64_t idx) LIBPOKE_API; 595 596 /* Set the bit-offset of the field of an struct, relative to the 597 beginning of the struct. 598 599 ARRAY is the struct value. 600 601 IDX is the index of the field in the struct. 602 603 BOFFSET is an uint<64> value with the bit-offset of the field. 604 605 If IDX is invalid, struct remains unchanged. */ 606 607 void pk_struct_set_field_boffset (pk_val sct, uint64_t idx, 608 pk_val boffset) LIBPOKE_API; 609 610 /* Get the NAME of the struct field. 611 612 SCT is the struct value. 613 614 IDX is the index of the field in the struct. 615 616 If IDX is invalid, PK_NULL is returned. */ 617 618 pk_val pk_struct_field_name (pk_val sct, uint64_t idx) LIBPOKE_API; 619 620 /* Set the NAME of the struct field. 621 622 SCT is the struct value. 623 624 IDX is the index of the field in the struct. 625 626 NAME is the string name for this field. 627 628 If IDX is invalid, struct remains unchanged. */ 629 630 void pk_struct_set_field_name (pk_val sct, uint64_t idx, 631 pk_val name) LIBPOKE_API; 632 633 /* Get the VALUE of the struct field. 634 635 SCT is the struct value. 636 637 IDX is the index of the field in the struct. 638 639 If IDX is invalid, PK_NULL is returned. */ 640 641 pk_val pk_struct_field_value (pk_val sct, uint64_t idx) LIBPOKE_API; 642 643 /* Set the VALUE of the struct field. 644 645 SCT is the struct value. 646 647 IDX is the index of the field in the struct. 648 649 VALUE is the new value for this field. 650 651 If IDX is invalid, struct remains unchanged. */ 652 653 void pk_struct_set_field_value (pk_val sct, uint64_t idx, 654 pk_val value) LIBPOKE_API; 655 656 /* Arrays. */ 657 658 /* Build and return an empty Poke array. 659 660 NELEM is a hint on the number of the elements that the array will 661 hold. If it is not clear how many elements the array will hold, 662 pass zero here. 663 664 ARRAY_TYPE is the type of the array. Note, this is an array type, 665 not the type of the elements. */ 666 667 pk_val pk_make_array (pk_val nelem, pk_val array_type) LIBPOKE_API; 668 669 /* Get the number of elements in the given array value, as an 670 uint<64>. */ 671 672 pk_val pk_array_nelem (pk_val array) LIBPOKE_API; 673 674 /* Get the value of the element of an array. 675 676 ARRAY is the array value. 677 IDX is the index of the element in the array. 678 679 If IDX is invalid, PK_NULL is returned. */ 680 681 pk_val pk_array_elem_val (pk_val array, uint64_t idx) LIBPOKE_API; 682 683 /* Insert a new element into an array. 684 685 More than one element may be created, depending on the provided 686 index. In that case, all the new elements contain a copy of VAL. 687 688 If the index corresponds to an existing element, the array remains 689 unchanged. 690 691 This function sets the bit-offset of the inserted elements. */ 692 693 void pk_array_insert_elem (pk_val array, uint64_t idx, pk_val val) 694 LIBPOKE_API; 695 696 /* Set the value of the element of an array. 697 698 ARRAY is the array value. 699 IDX is the index of the element whose value is set. 700 VAL is the new value for the array element. 701 702 This function may change the bit-offsets of the elements following 703 the element just inserted. 704 705 If IDX is invalid, array remains unchanged. */ 706 707 void pk_array_set_elem (pk_val array, uint64_t idx, pk_val val) LIBPOKE_API; 708 709 /* Get the bit-offset of the element of an array, relative to the 710 beginning of the array. 711 712 ARRAY is the array value. 713 IDX is the index of the element in the array. 714 715 The returned bit-offset is an uint<64>. 716 717 If IDX is invalid, PK_NULL is returned. */ 718 719 pk_val pk_array_elem_boffset (pk_val array, uint64_t idx) LIBPOKE_API; 720 721 /* Integral types. */ 722 723 /* Build and return an integral type. 724 725 SIZE is an uint<64> with the size, in bits, of the integral type. 726 SIGNED_P is an int<32> with a boolean specifying whether the type 727 is signed or not. */ 728 729 pk_val pk_make_integral_type (pk_val size, pk_val signed_p) LIBPOKE_API; 730 731 /* Return an uint<64> containing the size, in bits, of the given 732 integral type. */ 733 734 pk_val pk_integral_type_size (pk_val type) LIBPOKE_API; 735 736 /* Return an int<32> with a boolean specifying whether the given 737 integral type is signed or not. */ 738 739 pk_val pk_integral_type_signed_p (pk_val type) LIBPOKE_API; 740 741 /* The string type. */ 742 743 /* Build and return the string type. */ 744 745 pk_val pk_make_string_type (void) LIBPOKE_API; 746 747 /* The `any' type. */ 748 749 /* Build and return the `any' type. */ 750 751 pk_val pk_make_any_type (void) LIBPOKE_API; 752 753 /* Offset types. */ 754 755 /* Build and return an offset type. 756 757 BASE_TYPE is an integral type denoting the type of the base value 758 of the offset. 759 760 UNIT is an uint<64> with the unit of the offset type. The unit is 761 a multiple of the base unit, which is the bit. */ 762 763 pk_val pk_make_offset_type (pk_val base_type, pk_val unit) LIBPOKE_API; 764 765 /* Get the base type of a given offset type. */ 766 767 pk_val pk_offset_type_base_type (pk_val type) LIBPOKE_API; 768 769 /* Get the unit of a given offset type. */ 770 771 pk_val pk_offset_type_unit (pk_val type) LIBPOKE_API; 772 773 /* Struct types. */ 774 775 /* Build and return a struct type. 776 777 NFIELDS is the number of struct fields on this struct. 778 779 NAME is a string containing the name of a struct type. 780 781 FNAMES is a C array containing the name of each struct field. 782 783 FTYPES is a C array containing the types of each struct field. */ 784 785 pk_val pk_make_struct_type (pk_val nfields, pk_val name, pk_val *fnames, 786 pk_val *ftypes) LIBPOKE_API; 787 788 /* Get the type of a struct. */ 789 790 pk_val pk_struct_type (pk_val sct) LIBPOKE_API; 791 792 /* Allocate space for struct fields names and field types. */ 793 794 void pk_allocate_struct_attrs (pk_val nfields, 795 pk_val **fnames, pk_val **ftypes) LIBPOKE_API; 796 797 /* Get the name of a struct type. 798 799 If the struct type is anonymous, PK_NULL is returned. */ 800 801 pk_val pk_struct_type_name (pk_val type) LIBPOKE_API; 802 803 /* Get the number of fields of a struct type. 804 805 The returned value is an uint<64> */ 806 807 pk_val pk_struct_type_nfields (pk_val type) LIBPOKE_API; 808 809 /* Get the name of a field in a struct type. 810 811 TYPE is a struct type. 812 813 IDX is the index of the field in a struct type. 814 815 If IDX is invalid, PK_NULL is returned. 816 817 If the struct field is anonymous, PK_NULL is returned. */ 818 819 pk_val pk_struct_type_fname (pk_val type, uint64_t idx) LIBPOKE_API; 820 821 /* Set the name of a field of a struct type. 822 823 TYPE is a struct type. 824 825 IDX is the index of the field in a struct type. 826 827 NAME is a string containing the name of the field in a struct type. 828 829 If IDX is invalid, type remains unchanged. */ 830 831 void pk_struct_type_set_fname (pk_val type, uint64_t idx, 832 pk_val field_name) LIBPOKE_API; 833 834 /* Get type of a field in the struct. 835 836 TYPE is a struct type. 837 838 IDX is the index of the struct field. 839 840 If IDX is invalid, PK_NULL is returned. */ 841 842 pk_val pk_struct_type_ftype (pk_val type, uint64_t idx) LIBPOKE_API; 843 844 /* Set the type of a field of a struct type. 845 846 TYPE is a struct type. 847 848 IDX is the index of the field in a struct type. 849 850 TYPE is the type of the field in a struct type. 851 852 If IDX is invalid, type remains unchanged. */ 853 854 void pk_struct_type_set_ftype (pk_val type, uint64_t idx, 855 pk_val field_type) LIBPOKE_API; 856 857 /* Array types. */ 858 859 /* Build and return an array type. 860 861 ETYPE is the type of the elements of the array. 862 863 BOUND is an uint<64> with the number of elements of the 864 array... XXX or a closure?? cant remember. At the moment the PKL 865 compiler generates PVM_NULL for this... */ 866 867 pk_val pk_make_array_type (pk_val etype, pk_val bound) LIBPOKE_API; 868 869 /* Get the type of the elements of the given array type. */ 870 871 pk_val pk_array_type_etype (pk_val type) LIBPOKE_API; 872 873 /* Get the bound of the given array type. */ 874 875 pk_val pk_array_type_bound (pk_val type) LIBPOKE_API; 876 877 /* Mapped values. */ 878 879 /* Return a boolean indicating whether the given value is mapped or 880 not. */ 881 882 int pk_val_mapped_p (pk_val val) LIBPOKE_API; 883 884 /* Return the IOS identifier, an int<32>, in which the given value is 885 mapped. If the value is not mapped, return PK_NULL. */ 886 887 pk_val pk_val_ios (pk_val val) LIBPOKE_API; 888 889 /* Return the offset in which the given value is mapped. 890 If the value is not mapped, return PK_NULL. */ 891 892 pk_val pk_val_offset (pk_val val) LIBPOKE_API; 893 894 /* Other operations on values. */ 895 896 /* Return the type of the given value. */ 897 898 pk_val pk_typeof (pk_val val) LIBPOKE_API; 899 900 /* Given a type value, return its code. */ 901 902 #define PK_UNKNOWN 0 903 #define PK_INT 1 904 #define PK_UINT 2 905 #define PK_STRING 3 906 #define PK_OFFSET 4 907 #define PK_ARRAY 5 908 #define PK_STRUCT 6 909 #define PK_CLOSURE 7 910 #define PK_ANY 8 911 912 int pk_type_code (pk_val val) LIBPOKE_API; 913 914 /* Compare two Poke values. 915 916 Returns 1 if they match, 0 otherwise. */ 917 918 int pk_val_equal_p (pk_val val1, pk_val val2) LIBPOKE_API; 919 920 /* Print the given value using the current PKC settings. */ 921 922 void pk_print_val (pk_compiler pkc, pk_val val) LIBPOKE_API; 923 924 /* Print the given value using the given settings. */ 925 926 #define PK_PRINT_F_MAPS 1 /* Output value and element offsets. */ 927 #define PK_PRINT_F_PPRINT 2 /* Use pretty-printers. */ 928 929 void pk_print_val_with_params (pk_compiler pkc, pk_val val, 930 int depth, int mode, int base, 931 int indent, int acutoff, 932 uint32_t flags) LIBPOKE_API; 933 934 #endif /* ! LIBPOKE_H */ 935