1 /// This file is not technically part of the ChaiScript API. It is used solely for generating Doxygen docs 2 /// regarding the ChaiScript standard runtime library. 3 4 /// \brief Items in this namespace exist in the ChaiScript language runtime. They are not part of the C++ API 5 namespace ChaiScript_Language 6 { 7 8 /// \page LangStandardLibraryRef ChaiScript Language Standard Library Reference 9 /// 10 /// ChaiScript, at its core, has some very functional programming-inspired habits. Few places show this off as clearly 11 /// as the prelude, itself a name taken as a nod to the popular functional language Haskell. This prelude is available 12 /// to all standard ChaiScript applications, and provides a simple foundation for using numbers, strings, and ranges 13 /// (the general category of Range cs and their iteration). 14 /// 15 16 17 /// \brief Generic concept of a value in ChaiScript. 18 /// 19 /// The Object type exists merely as a concept. All objects in ChaiScript support this concept 20 /// and have the following methods available to them. All objects are stored internally as chaiscript::Boxed_Value types. 21 /// 22 /// \sa chaiscript::Boxed_Value 23 class Object 24 { 25 public: 26 /// \brief Returns the Type_Info value for this Object 27 Type_Info get_type_info() const; 28 29 /// \brief Returns true if the Object is of the named type 30 bool is_type(string) const; 31 32 /// \brief Returns true if the Object is of the Type_Info passed in 33 bool is_type(Type_Info) const; 34 35 /// \brief Returns true if the Object is immutable 36 bool is_var_const() const; 37 38 /// \brief Returns true if the Object is a pointer and the pointer is null 39 bool is_var_null() const; 40 41 /// \brief Returns true if the Object is stored as a pointer 42 bool is_var_pointer() const; 43 44 /// \brief Returns true if the Object is stored as a reference 45 bool is_var_reference() const; 46 47 /// \brief Returns true if the Object does not contain a value is is undefined. 48 bool is_var_undef() const; 49 50 /// \brief Returns the registered name of the type of the object. 51 /// 52 /// \sa Type_Info::name(); 53 string type_name() const; 54 }; 55 56 /// \brief Item returned from a Range object from a Map 57 class Map_Pair 58 { 59 public: 60 /// \brief Returns the key of the Map entry 61 const string first(); 62 63 /// \brief Returns the value Object of the Map entry 64 Object second(); 65 }; 66 67 68 /// \brief Maps strings to Objects 69 /// 70 /// ChaiScript has a built in shortcut for generating Map objects: 71 /// 72 /// Example: 73 /// \code 74 /// eval> var m = ["a":1, "b":2]; 75 /// [<a,1>, <b,2>] 76 /// eval> m.count("a"); 77 /// 1 78 /// eval> m.count("c"); 79 /// 0 80 /// eval> m.size(); 81 /// 2 82 /// \endcode 83 /// 84 /// Implemented as std::map<Boxed_Value> 85 /// 86 /// \sa Map_Pair 87 /// \sa chaiscript::bootstrap::standard_library::map_type 88 class Map 89 { 90 public: 91 /// \brief Returns an object that implements the Range concept for the Map_Pair's in this Map 92 Range range(); 93 94 /// \brief Returns an object that implements the Const_Range concept for the Map_Pair's in this Map 95 Const_Range range() const; 96 97 /// \brief Returns the number of elements in the Map 98 int size() const; 99 100 /// \brief Returns the item at the given key, creating an undefined Object if the key does not yet exist in the map 101 Object operator[](string); 102 103 /// \brief Clears the map of all items 104 void clear(); 105 106 /// \brief Returns the number of items in the Map with the given key. Returns 0 or 1 since this is not an std::multimap. 107 int count(string) const; 108 109 /// \brief Returns true if the map contains no items 110 bool empty() const; 111 112 }; 113 114 115 /// \brief A concept implemented by string, Vector and Map. It is convertible to Range, default constructable and back_insertable 116 class Container 117 { 118 public: 119 void push_back(Object); 120 Range range(); 121 Const_Range range() const; 122 }; 123 124 125 /// \brief Converts o into a string. 126 /// 127 /// \code 128 /// eval> to_string(3).is_type("string") <br> 129 /// true<br> 130 /// \endcode 131 string to_string(Object o); 132 133 134 /// \brief Prints o to the terminal, without a trailing carriage return. Applies conversions to string automatically. 135 /// \code 136 /// eval> puts("hi, "); puts("there") 137 /// hi, thereeval> 138 /// \endcode 139 /// \sa to_string 140 /// \sa print 141 void puts(Object o); 142 143 144 /// \brief Prints o to the terminal, with a trailing carriage return. Applies conversions to string automatically 145 /// \code 146 /// eval> print("hello") 147 /// hello 148 /// eval> 149 /// \endcode 150 /// \sa to_string 151 /// \sa puts 152 void print(Object o); 153 154 /// \brief ChaiScript representation of std::string. It is an std::string but only some member are exposed to ChaiScript. 155 /// 156 /// Because the ChaiScript string object is an std::string, it is directly convertible to and from std::string 157 /// using the chaiscript::boxed_cast and chaiscript::var functions. 158 /// 159 /// With the exception of string::trim, string::rtrim, string::ltrim, all members are direct pass-throughs to the 160 /// std::string of the same name. 161 /// 162 /// \note Object and function notations are equivalent in ChaiScript. This means that 163 /// \c "bob".find("b") and \c find("bob", "b") are exactly the same. Most examples below follow the 164 /// second formation of the function calls. 165 /// \sa \ref keyworddef for extending existing C++ classes in ChaiScript 166 /// \sa chaiscript::bootstrap::standard_library::string_type 167 class string 168 { 169 public: 170 /// \brief Finds the first instance of substr. 171 /// \code 172 /// eval> find("abab", "ab") 173 /// 0 174 /// \endcode 175 int find(string s) const; 176 177 178 /// \brief Finds the last instance of substr. 179 /// \code 180 /// eval> rfind("abab", "ab") 181 /// 2 182 /// \endcode 183 int rfind(string s) const; 184 185 /// \brief Finds the first of characters in list in the string. 186 /// 187 /// \code 188 /// eval> find_first_of("abab", "bec") 189 /// 1 190 /// \endcode 191 int find_first_of(string list) const; 192 193 /// \brief Finds the last of characters in list in the string. 194 /// 195 /// \code 196 /// eval> find_last_of("abab", "bec") 197 /// 3 198 /// \endcode 199 int find_last_of(string list) const; 200 201 /// \brief Finds the first non-matching character to list in the str string. 202 /// 203 /// \code 204 /// eval> find_first_not_of("abcd", "fec") 205 /// 0 206 /// \endcode 207 int find_first_not_of(string list) const; 208 209 /// \brief Finds the last non-matching character to list in the list string. 210 /// 211 /// \code 212 /// eval> find_last_not_of("abcd", "fec") 213 /// 3 214 /// \endcode 215 int find_last_not_of(string list) const; 216 217 /// \brief Removes whitespace from the front of the string, returning a new string 218 /// 219 /// \note This function is implemented as a ChaiScript function using the def member function notation. 220 /// 221 /// \code 222 /// eval> ltrim(" bob") 223 /// bob 224 /// \endcode 225 /// 226 /// \sa \ref keyworddef 227 string lstrim() const; 228 229 /// \brief Removes whitespace from the back of the string, returning a new string 230 /// 231 /// \note This function is implemented as a ChaiScript function using the def member function notation. 232 /// 233 /// \code 234 /// eval> rtrim("bob ") + "|" 235 /// bob| 236 /// \endcode 237 /// 238 /// \sa \ref keyworddef 239 string rtrim() const; 240 241 /// \brief Removes whitespace from the front and back of the string, returning a new string 242 /// 243 /// \note This function is implemented as a ChaiScript function using the def member function notation. 244 /// 245 /// \code 246 /// eval> trim(" bob ") + "|" 247 /// bob| 248 /// \endcode 249 /// 250 /// Equivalent to rtrim(ltrim(" bob ")); 251 /// 252 /// \sa \ref keyworddef 253 string trim() const; 254 255 /// \brief Returns the character at the given index in the string, const version 256 const char &operator[](int t_index) const; 257 258 /// \brief Returns the character at the given index in the string 259 char &operator[](int t_index); 260 261 /// \brief Returns underlying const char * for C api compatibility 262 const char *c_str() const; 263 264 /// \brief Returns a pointer to the raw data in the string 265 const char *data() const; 266 267 /// \brief Resets the string to empty 268 void clear(); 269 270 /// \brief Returns true if the string is empty 271 bool empty() const; 272 273 /// \brief Returns the size of the string in bytes. 274 /// 275 /// This function normally returns size_t in C++. In ChaiScript the return value is cast to int 276 /// for ease of use. 277 int size() const; 278 279 /// \brief Returns an object that implements the Range concept for the characters of this string 280 Range range(); 281 282 /// \brief Returns an object that implements the Const_Range concept for the characters of this string 283 Const_Range range() const; 284 }; 285 286 /// \brief A concept in ChaiScript that is implemented by \ref string, Vector and Map. It provides 287 /// easy iteration over the elements in a container. 288 /// 289 /// Implemented by the template chaiscript::bootstrap::standard_library::Bidir_Range 290 /// 291 /// \sa Const_Range 292 class Range 293 { 294 public: 295 /// \brief Returns the last item of the range 296 Object back(); 297 298 /// \brief Returns true if the front and back pointers have passed each other, if no items 299 /// are left in the Range 300 bool empty() const; 301 302 /// \brief Returns the first item of the range 303 Object front(); 304 305 /// \brief Moves the back pointer back one. 306 /// 307 /// \post back() returns the element at back() - 1; 308 void pop_back(); 309 310 /// \brief Moves the front pointer forward one 311 /// 312 /// \post front() returns the element at front() + 1; 313 void pop_front(); 314 315 }; 316 317 /// \brief A concept in ChaiScript that is implemented by \ref string, Vector and Map. It provides 318 /// easy iteration over the elements in a container. Contained values are const. 319 /// 320 /// Implemented by the template chaiscript::bootstrap::standard_library::Const_Bidir_Range 321 /// 322 /// \sa Range 323 class Const_Range 324 { 325 public: 326 /// \brief Returns the last item of the range 327 const Object back(); 328 329 /// \brief Returns true if the front and back pointers have passed each other, if no items 330 /// are left in the Range 331 bool empty() const; 332 333 /// \brief Returns the first item of the range 334 const Object front(); 335 336 /// \brief Moves the back pointer back one. 337 /// 338 /// \post back() returns the element at back() - 1; 339 void pop_back(); 340 341 /// \brief Moves the front pointer forward one 342 /// 343 /// \post front() returns the element at front() + 1; 344 void pop_front(); 345 346 }; 347 348 /// \brief A vector of Objects 349 /// 350 /// ChaiScript includes a shortcut for creating a Vector of Objects 351 /// 352 /// Example: 353 /// \code 354 /// eval> var v = [1,2,3,4] 355 /// [1, 2, 3, 4] 356 /// eval> v[0]; 357 /// 1 358 /// eval> v.size(); 359 /// 4 360 /// \endcode 361 /// 362 /// Implemented with std::vector<chaiscript::Boxed_Value> 363 /// 364 /// \sa chaiscript::bootstrap::standard_library::vector_type 365 class Vector 366 { 367 public: 368 /// \brief returns the Object at the given index. Throws an exception if the index does not exist 369 Object operator[](int t_index); 370 371 /// \brief returns a const Object at the given index. Throws an exception if the index does not exist. 372 const Object operator[](int t_index) const; 373 374 /// \brief returns the last item in the Vector 375 Object back(); 376 377 /// \brief Clears the Vector of all items 378 void clear(); 379 380 /// \brief Returns true if the Vector is contains 0 items 381 bool empty(); 382 383 /// \brief Erases the element at the given index 384 void erase_at(int t_index); 385 386 /// \brief Returns the first item in the Vector 387 Object front(); 388 389 /// \brief Inserts a new item in the Vector at the given index. The item is not cloned on insert 390 /// 391 /// \sa insert_ref 392 void insert_ref_at(int, Object); 393 394 /// \brief Inserts a new item in the Vector at the given index. The item is cloned on insert 395 /// 396 /// \sa insert_ref 397 void insert_at(int, Object); 398 399 /// \brief Removes the last item from the Vector 400 void pop_back(); 401 402 /// \brief Adds an item to the end of the Vector. The item is not cloned. 403 /// 404 /// \sa push_back 405 void push_back_ref(Object); 406 407 /// \brief Adds an item to the end of the Vector. The item is cloned. 408 /// 409 /// \sa push_back_ref 410 void push_back(Object); 411 412 /// \brief Returns a Range object for the entire vector 413 Range range(); 414 415 /// \brief Returns a Const_Range object for the entire vector 416 Const_Range range() const; 417 418 /// \brief Returns the number of elements in the Vector 419 int size() const; 420 421 }; 422 423 class Type_Info 424 { 425 public: 426 /// \brief Compares this Type_Info object with another one and returns true if the two types are the same 427 /// after const, pointer, reference are removed. 428 bool bare_equal(Type_Info t_ti) const; 429 430 /// \brief Returns the mangled C++ name for the type given by the compiler after const, pointer, reference is removed. 431 string cpp_bare_name() const; 432 433 /// \brief Returns the mangled C++ name for the type given by the compiler. 434 string cpp_name() const; 435 436 /// \brief Returns true if the type is const 437 bool is_type_const() const; 438 439 /// \brief Returns true if the type is a pointer 440 bool is_type_pointer() const; 441 442 /// \brief Returns true if the type is a reference 443 bool is_type_reference() const; 444 445 /// \brief Returns true if the type is undefined 446 bool is_type_undef() const; 447 448 /// \brief Returns true if the type is "void" 449 bool is_type_void() const; 450 451 /// \brief Returns the ChaiScript registered name for the type if one exists. 452 string name() const; 453 454 }; 455 456 457 /// \brief Represents a function object in ChaiScript 458 /// 459 /// A function object may be one function, such as: 460 /// \code 461 /// var f = fun(x) { return x; } 462 /// \endcode 463 /// 464 /// Or it may represent multiple functions 465 /// \code 466 /// var f2 = `-`; // represents the unary - as well as the set of binary - operators 467 /// \endcode 468 /// 469 /// Guarded function example 470 /// \code 471 /// def f3(x) : x > 2 { 472 /// return x; 473 /// } 474 /// \endcode 475 /// 476 /// Examples in the function definitions below will reference these examples 477 class Function 478 { 479 public: 480 /// \brief Returns the annotation description of the function 481 string get_annotation() const; 482 483 /// \brief Returns the arity of the function, -1 if the function takes a variable number of parameters 484 /// 485 /// Example: 486 /// \code 487 /// eval> f.get_arity() 488 /// 1 489 /// eval> f2.get_arity() 490 /// -1 491 /// \endcode 492 int get_arity() const; 493 494 /// \brief Returns a vector of the contained functions 495 /// 496 /// Example: 497 /// \code 498 /// eval> f.get_contained_functions().size() 499 /// 0 500 /// eval> f2.get_contained_functions().size() 501 /// 11 502 /// eval> var v = f2.get_contained_functions(); 503 /// v[0].get_arity() 504 /// 2 505 /// \endcode 506 Vector get_contained_functions() const; 507 508 /// \brief Returns a function guard as function 509 /// 510 /// Example: 511 /// \code 512 /// eval> f.get_guard() // Throws exception 513 /// Function does not have a guard 514 /// eval> f3.get_guard().get_arity() 515 /// 1 516 /// \endcode 517 Function get_guard() const; 518 519 /// \brief Returns a vector of Type_Info objects that represent the param types for this function. 520 /// The first value in the list is the return type. 521 /// 522 /// If this function is a conglomerate of several functions (get_contained_values().size() > 0) 523 /// then the function returns as many Type_Info objects as it can. If the functions contained all have 524 /// the same arity, then it represents the arity. If they have different arities, it returns only 525 /// one value - the return type. 526 /// 527 /// For each parameter that is the same type, the type is returned. If the types are different 528 /// then a Type_Info for Object is returned. 529 /// 530 /// Example: 531 /// \code 532 /// eval> f2.get_param_types().size(); // Returns a Type_Info for Object for the return type 533 /// 1 534 /// \endcode 535 Vector get_param_types() const; 536 537 /// \brief Returns true if the function has a guard to it. Always returns false for a conglomerate function 538 bool has_guard() const; 539 540 /// \brief Calls the function with the given set of parameters and returns the value; 541 /// 542 /// Example: 543 /// \code 544 /// eval> `-`.call([2,1]); 545 /// 1 546 /// \endcode 547 Object call(Vector t_params) const; 548 } 549 550 551 552 /// \brief Returns the max of a or b. Requires that operator>(a, b) exists 553 /// Equivalent to 554 /// \code 555 /// return a>b?a:b; 556 /// \endcode 557 /// 558 /// Example: 559 /// \code 560 /// eval> max(4, 10) 561 /// 10 562 /// \endcode 563 Object max(Object a, Object b); 564 565 /// \brief Returns the min of a or b. Requires that operator<(a, b) exists 566 /// 567 /// Equivalent to 568 /// \code 569 /// return a<b?a:b; 570 /// \endcode 571 /// 572 /// Example: 573 /// \code 574 /// eval> min(4, 10) 575 /// 4 576 /// \endcode 577 Object min(Object a, Object b); 578 579 /// \brief Returns true if x is an even integer. 580 /// 581 /// Will also work on any non-integer type for which an operator%(x, int) exists 582 /// 583 /// Example: 584 /// \code 585 /// eval> even(4) 586 /// true 587 /// \endcode 588 bool even(Object x); 589 590 /// \brief Returns true if x is an odd integer. 591 /// 592 /// Will also work on any non-integer type for which an operator%(x, int) exists 593 /// 594 /// Example: 595 /// \code 596 /// eval> odd(4) 597 /// false 598 /// \endcode 599 bool even(Object x); 600 601 602 /// \brief Applies the function f over each element in the Range c. 603 /// 604 /// Example: 605 /// \code 606 /// eval> for_each([1, 2, 3], print) 607 /// 1 608 /// 2 609 /// 3 610 /// \endcode 611 void for_each(Range c, Function f); 612 613 614 /// \brief Applies f over each element in the Range c, joining all the results. 615 /// 616 /// Example: 617 /// \code 618 /// eval> map([1, 2, 3], odd) 619 /// [true, false, true] 620 /// \endcode 621 Object map(Range c, Function f); 622 623 624 /// \brief Starts with the initial value and applies the function f to it and the first element of the Range c. 625 /// The result is then applied to the second element, and so on until the elements are exhausted. 626 /// 627 /// Example: 628 /// \code 629 /// eval> foldl([1, 2, 3, 4], `+`, 0) 630 /// 10 631 /// \endcode 632 Object foldl(Range c, Function f, Object initial); 633 634 635 /// \brief Returns the sum total of the values in the Range c. 636 /// 637 /// Example: 638 /// \code 639 /// eval> sum([1, 2, 3, 4]) 640 /// 10 641 /// \endcode 642 /// 643 /// Equivalent to: 644 /// \code 645 /// foldl(c, `+`, 0.0); 646 /// \endcode 647 Numeric sum(Range c); 648 649 650 /// \brief Returns the product of the value in the Range c. 651 /// 652 /// Example: 653 /// \code 654 /// eval> product([1, 2, 3, 4]) 655 /// 24 656 /// \endcode 657 /// 658 /// Equivalent to: 659 /// \code 660 /// foldl(c, `*`, 1.0); 661 /// \endcode 662 Numeric product(Range c); 663 664 665 /// \brief Takes num elements from the Range c, returning them. 666 /// 667 /// Example: 668 /// \code 669 /// eval> take([1, 2, 3, 4], 2) 670 /// [1, 2] 671 /// \endcode 672 /// 673 /// \returns A container of the same type that was passed in 674 Object take(Range c, int num); 675 676 677 /// \brief Takes elements from the Range c that match function f, stopping at the first non-match, returning them as a new Vector. 678 /// 679 /// Example: 680 /// \code 681 /// eval> take_while([1, 2, 3], odd) 682 /// [1] 683 /// \endcode 684 /// 685 /// \returns A container of the same type that was passed in 686 Object take_while(Range c, Function f); 687 688 689 /// \brief Drops num elements from the Range c, returning the remainder. 690 /// 691 /// Example: 692 /// \code 693 /// eval> drop([1, 2, 3, 4], 2) 694 /// [3, 4] 695 /// \endcode 696 /// 697 /// \returns A container of the same type that was passed in 698 Object drop(Range c, int num); 699 700 701 /// \brief Drops elements from the Range c that match f, stopping at the first non-match, returning the remainder. 702 /// 703 /// Example: 704 /// \code 705 /// eval> drop_while([1, 2, 3], odd) 706 /// [2, 3] 707 /// \endcode 708 Object drop_while(Range c, Function f); 709 710 711 /// \brief Similar to foldl, this takes the first two elements as its starting values for f. This assumes Range c has at least 2 elements. 712 /// 713 /// Example: 714 /// \code 715 /// eval> reduce([1, 2, 3, 4], `+`) 716 /// 10 717 /// \endcode 718 Object reduce(Range c, Function f); 719 720 721 /// \brief Takes elements from Container c that match function f, return them. 722 /// 723 /// Example: 724 /// \code 725 /// eval> filter([1, 2, 3, 4], odd) 726 /// [1, 3] 727 /// \endcode 728 Object filter(Container c, Function f); 729 730 731 /// \brief Joins the elements of the Range c into a string, delimiting each with the delim string. 732 /// 733 /// Example: 734 /// \code 735 /// eval> join([1, 2, 3], "*") 736 /// 1*2*3 737 /// \endcode 738 string join(Range c, string delim); 739 740 741 /// \brief Returns the contents of the Container c in reversed order. 742 /// 743 /// Example: 744 /// \code 745 /// eval> reverse([1, 2, 3, 4, 5, 6, 7]) 746 /// [7, 6, 5, 4, 3, 2, 1] 747 /// \endcode 748 Container reverse(Container c); 749 750 751 /// \brief Generates a new Vector filled with values starting at x and ending with y. 752 /// 753 /// Works on types supporting operator<=(x, y) and operator++(x) 754 /// 755 /// Example: 756 /// \code 757 /// eval> generate_range(1, 10) 758 /// [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] 759 /// \endcode 760 Vector generate_range(Object x, Object y); 761 762 763 /// \brief Returns a new Range with x and y concatenated. 764 /// 765 /// Example: 766 /// \code 767 /// eval> concat([1, 2, 3], [4, 5, 6]) 768 /// [1, 2, 3, 4, 5, 6] 769 /// \endcode 770 Object concat(Range x, Range y); 771 772 773 /// \brief Returns a new Vector with x and y as its values. 774 /// 775 /// Example: 776 /// \code 777 /// eval> collate(1, 2) 778 /// [1, 2] 779 /// \endcode 780 Vector collate(Object x, Object y); 781 782 783 /// \brief Applies f to elements of x and y, returning a new Vector with the result of each application. 784 /// 785 /// Example: 786 /// \code 787 /// eval> zip_with(`+`, [1, 2, 3], [4, 5, 6]) 788 /// [5, 7, 9] 789 /// \endcode 790 Vector zip_with(Function f, Range x, Range y); 791 792 793 /// \brief Collates elements of x and y, returning a new Vector with the result. 794 /// 795 /// Example: 796 /// \code 797 /// eval> zip([1, 2, 3], [4, 5, 6]) 798 /// [[1, 4], [2, 5], [3, 6]] 799 /// \endcode 800 Vector zip(Range x, Range y); 801 802 803 /// \brief returns true if there exists a call to the Function f that takes the given parameters 804 /// 805 /// Example: 806 /// \code 807 /// eval> call_exists(`+`, 1, 2) 808 /// true 809 /// \endcode 810 bool call_exists(Function f, ...); 811 812 /// \brief Reverses a Range object so that the elements are accessed in reverse 813 Range retro(Range); 814 815 /// \brief Reverses a Const_Range object so that the elements are accessed in reverse 816 Const_Range retro(Const_Range); 817 818 819 /// \brief Raises the given object as an exception. Any type of object can be thrown. 820 /// 821 /// Example: 822 /// \code 823 /// eval> try { throw(1); } catch (e) { print("Exception caught: " + to_string(e)); } 824 /// Exception caught: 1 825 /// \endcode 826 /// 827 /// \sa \ref keywordtry 828 void throw(Object); 829 } 830 831