ChaiScript / ChaiScript
1
// This file is distributed under the BSD License.
2
// See "license.txt" for details.
3
// Copyright 2009-2012, Jonathan Turner (jonathan@emptycrate.com)
4
// Copyright 2009-2018, Jason Turner (jason@emptycrate.com)
5
// http://www.chaiscript.com
6

7
// This is an open source non-commercial project. Dear PVS-Studio, please check it.
8
// PVS-Studio Static Code Analyzer for C, C++ and C#: http://www.viva64.com
9

10
#ifndef CHAISCRIPT_HPP_
11
#define CHAISCRIPT_HPP_
12

13
/// @mainpage
14
/// [ChaiScript](http://www.chaiscript.com") is a scripting language designed specifically for integration with C++. It provides
15
/// seamless integration with C++ on all levels, including shared_ptr objects, functors and exceptions.
16
///
17
/// The parts of the ChaiScript API that the average user will be concerned with are contained in the
18
/// chaiscript namespace and the chaiscript::ChaiScript class.
19
///
20
/// The end user parts of the API are extremely simple both in size and ease of use.
21
///
22
/// Currently, all source control and project management aspects of ChaiScript occur on
23
/// [github](http://www.github.com/ChaiScript/ChaiScript").
24
///
25
/// ------------------------------------------------------------
26
///
27
/// @sa chaiscript
28
/// @sa chaiscript::ChaiScript
29
/// @sa ChaiScript_Language for Built in Functions
30
/// @sa @ref LangGettingStarted
31
/// @sa @ref LangKeywordRef
32
/// @sa @ref LangInPlaceRef
33
/// @sa @ref LangObjectSystemRef
34
/// @sa http://www.chaiscript.com
35
/// @sa http://www.github.com/ChaiScript/ChaiScript
36
///
37
/// -----------------------------------------------------------
38
///
39
/// @section gettingstarted API Getting Started
40
///
41
/// - @ref basics
42
/// - @ref compiling
43
/// - @ref eval
44
/// - @ref adding_items
45
/// - @ref operatoroverloading
46
/// - @ref add_class
47
/// - @ref pointer_conversions
48
/// - @ref baseclasses
49
/// - @ref functionobjects
50
/// - @ref threading
51
/// - @ref exceptions
52
///
53
///
54
/// @subsection basics Basics
55
///
56
/// Basic simple example:
57
///
58
/// ~~~~~~~{.cpp}
59
/// //main.cpp
60
/// #include <chaiscript/chaiscript.hpp>
61
///
62
/// double function(int i, double j)
63
/// {
64
///   return i * j;
65
/// }
66
///
67
/// int main()
68
/// {
69
///   chaiscript::ChaiScript chai;
70
///   chai.add(chaiscript::fun(&function), "function");
71
///
72
///   double d = chai.eval<double>("function(3, 4.75);");
73
/// }
74
/// ~~~~~~~
75
///
76
/// ------------------------------------------------------
77
///
78
/// @subsection compiling Compiling ChaiScript Applications
79
///
80
/// ChaiScript is a header only library with only one dependency: The
81
/// operating system provided dynamic library loader, which has to be specified on some platforms.
82
///
83
/// @subsubsection compilinggcc Compiling with GCC
84
///
85
/// To compile the above application on a Unix like operating system (MacOS, Linux) with GCC you need to link
86
/// the dynamic loader. For example:
87
///
88
/// ~~~~~~~~
89
/// gcc main.cpp -I/path/to/chaiscript/headers -ldl
90
/// ~~~~~~~~
91
///
92
/// Alternatively, you may compile without threading support.
93
///
94
/// ~~~~~~~~
95
/// gcc main.cpp -I/path/to/chaiscript/headers -ldl -DCHAISCRIPT_NO_THREADS
96
/// ~~~~~~~~
97
///
98
/// ------------------------------------------
99
///
100
/// @subsection eval Evaluating Scripts
101
///
102
/// Scripts can be evaluated with the () operator, eval method or eval_file method.
103
///
104
/// @subsubsection parenoperator () Operator
105
///
106
/// operator() can be used as a handy shortcut for evaluating ChaiScript snippets.
107
///
108
/// ~~~~~~~~{.cpp}
109
/// chaiscript::ChaiScript chai;
110
/// chai("print(@"hello world@")");
111
/// ~~~~~~~~
112
///
113
/// @sa chaiscript::ChaiScript::operator()(const std::string &)
114
///
115
/// @subsubsection evalmethod Method 'eval'
116
///
117
/// The eval method is somewhat more verbose and can be used to get type safely return values
118
/// from the script.
119
///
120
/// ~~~~~~~~{.cpp}
121
/// chaiscript::ChaiScript chai;
122
/// chai.eval("callsomefunc()");
123
/// int result = chai.eval<int>("1 + 3");
124
/// // result now equals 4
125
/// ~~~~~~~~
126
///
127
/// @sa chaiscript::ChaiScript::eval
128
///
129
/// @subsubsection evalfilemethod Method 'eval_file'
130
///
131
/// The 'eval_file' method loads a file from disk and executes the script in it
132
///
133
/// ~~~~~~~~{.cpp}
134
/// chaiscript::ChaiScript chai;
135
/// chai.eval_file("myfile.chai");
136
/// std::string result = chai.eval_file<std::string>("myfile.chai") // extract the last value returned from the file
137
/// ~~~~~~~~
138
///
139
/// @sa chaiscript::ChaiScript::eval_file
140
///
141
/// --------------------------------------------------
142
///
143
/// @subsection adding_items Adding Items to ChaiScript
144
///
145
/// ChaiScript supports 4 basic things that can be added: objects, functions, type infos and Modules
146
///
147
/// @subsubsection adding_objects Adding Objects
148
///
149
/// Named objects can be created with the chaiscript::var function. Note: adding a object
150
/// adds it to the current thread scope, not to a global scope. If you have multiple
151
/// threads that need to access the same variables you will need to add them
152
/// separately for each thread, from the thread itself.
153
///
154
/// ~~~~~~~~~{.cpp}
155
/// using namespace chaiscript;
156
/// ChaiScript chai;
157
/// int i = 5;
158
/// chai.add(var(i), "i");
159
/// chai("print(i)");
160
/// ~~~~~~~~~
161
///
162
/// Immutable objects can be created with the chaiscript::const_var function.
163
///
164
/// ~~~~~~~~~{.cpp}
165
/// chai.add(const_var(i), "i");
166
/// chai("i = 5"); // exception throw, cannot assign const var
167
/// ~~~~~~~~~
168
///
169
/// Named variables can only be accessed from the context they are created in.
170
/// If you want a global variable, it must be const, and created with the
171
/// chaiscript::ChaiScript::add_global_const function.
172
///
173
/// ~~~~~~~~~{.cpp}
174
/// chai.add_global_const(const_var(i), "i");
175
/// chai("def somefun() { print(i); }; somefun();");
176
/// ~~~~~~~~~
177
///
178
/// @subsubsection adding_functions Adding Functions
179
///
180
/// Functions, methods and members are all added using the same function: chaiscript::fun.
181
///
182
/// ~~~~~~~~~{.cpp}
183
/// using namespace chaiscript;
184
///
185
/// class MyClass {
186
///   public:
187
///     int memberdata;
188
///     void method();
189
///     void method2(int);
190
///     static void staticmethod();
191
///     void overloadedmethod();
192
///     void overloadedmethod(const std::string &);
193
/// };
194
///
195
/// ChaiScript chai;
196
/// chai.add(fun(&MyClass::memberdata), "memberdata");
197
/// chai.add(fun(&MyClass::method), "method");
198
/// chai.add(fun(&MyClass::staticmethod), "staticmethod");
199
/// ~~~~~~~~~
200
///
201
/// Overloaded methods will need some help, to hint the compiler as to which overload you want:
202
///
203
/// ~~~~~~~~~{.cpp}
204
/// chai.add(fun<void (MyClass::*)()>(&MyClass::overloadedmethod), "overloadedmethod");
205
/// chai.add(fun<void (MyClass::*)(const std::string &)>(&MyClass::overloadedmethod), "overloadedmethod");
206
/// ~~~~~~~~~
207
///
208
/// There are also shortcuts built into chaiscript::fun for binding up to the first two parameters of the function.
209
///
210
/// ~~~~~~~~~{.cpp}
211
/// MyClass obj;
212
/// chai.add(fun(&MyClass::method, &obj), "method");
213
/// chai("method()"); // equiv to obj.method()
214
/// chai.add(fun(&MyClass::method2, &obj, 3), "method2");
215
/// chai("method2()"); // equiv to obj.method2(3)
216
/// ~~~~~~~~~
217
///
218
/// @subsubsection addingtypeinfo Adding Type Info
219
///
220
/// ChaiScript will automatically support any type implicitly provided to it in the form
221
/// of objects and function parameters / return types. However, it can be nice to let ChaiScript
222
/// know more details about the types you are giving it. For instance, the "clone" functionality
223
/// cannot work unless there is a copy constructor registered and the name of the type is known
224
/// (so that ChaiScript can look up the copy constructor).
225
///
226
/// Continuing with the example "MyClass" from above:
227
///
228
/// ~~~~~~~~{.cpp}
229
/// chai.add(user_type<MyClass>(), "MyClass");
230
/// ~~~~~~~~
231
///
232
/// @subsubsection adding_modules Adding Modules
233
///
234
/// Modules are holders for collections of ChaiScript registrations.
235
///
236
/// ~~~~~~~~{.cpp}
237
/// ModulePtr module = get_sum_module();
238
/// chai.add(module);
239
/// ~~~~~~~~
240
///
241
/// @sa chaiscript::Module
242
///
243
/// -----------------------------------------------------------------------
244
///
245
/// @subsection operatoroverloading Operator Overloading
246
///
247
/// Operators are just like any other function in ChaiScript, to overload an operator, simply register it.
248
///
249
/// ~~~~~~~~{.cpp}
250
/// class MyClass {
251
///   MyClass operator+(const MyClass &) const;
252
/// };
253
///
254
/// chai.add(fun(&MyClass::operator+), "+");
255
///
256
/// std::string append_string_int(const std::string &t_lhs, int t_rhs)
257
/// {
258
///   std::stringstream ss;
259
///   ss << t_lhs << t_rhs;
260
///   return ss.str();
261
/// }
262
///
263
/// chai.add(fun(append_string_int), "+");
264
/// ~~~~~~~~
265
///
266
/// @sa @ref adding_functions
267
///
268
/// -----------------------------------------------------------------------
269
///
270
/// @subsection add_class Class Helper Utility
271
///
272
/// Much of the work of adding new classes to ChaiScript can be reduced with the help
273
/// of the add_class helper utility.
274
///
275
/// ~~~~~~~~{.cpp}
276
/// class Test
277
/// {
278
///   public:
279
///     void function() {}
280
///     std::string function2() { return "Function2"; }
281
///     void function3() {}
282
///     std::string functionOverload(double) { return "double"; }
283
///     std::string functionOverload(int) { return "int"; }
284
/// };
285
///
286
/// int main()
287
/// {
288
///   chaiscript::ModulePtr m = chaiscript::ModulePtr(new chaiscript::Module());
289
///
290
///   chaiscript::utility::add_class<chaiscript::Test>(*m,
291
///      "Test",
292
///      { constructor<Test()>(),
293
///        constructor<Test(const Test &)>() },
294
///      { {fun(&Test::function), "function"},
295
///        {fun(&Test::function2), "function2"},
296
///        {fun(&Test::function2), "function3"}
297
///        {fun(static_cast<std::string Test::*(double)>(&Test::functionOverload)), "functionOverload"}
298
///        {fun(static_cast<std::string Test::*(int)>(&Test::functionOverload)), "functionOverload"} }
299
///      );
300
///
301
///
302
///   chaiscript::ChaiScript chai;
303
///   chai.add(m);
304
/// }
305
/// ~~~~~~~~
306
///
307
/// @sa @ref adding_modules
308
///
309
/// -----------------------------------------------------------------------
310
///
311
/// @subsection pointer_conversions Pointer / Object Conversions
312
///
313
/// As much as possible, ChaiScript attempts to convert between &, *, const &, const *, std::shared_ptr<T>,
314
/// std::shared_ptr<const T>, std::reference_wrapper<T>, std::reference_wrapper<const T> and value types automatically.
315
///
316
/// If a chaiscript::var object was created in C++ from a pointer, it cannot be converted to a shared_ptr (this would add invalid reference
317
/// counting). Const may be added, but never removed.
318
///
319
/// The take away is that you can pretty much expect function calls to Just Work when you need them to.
320
///
321
/// ~~~~~~~~{.cpp}
322
/// void fun1(const int *);
323
/// void fun2(int *);
324
/// void fun3(int);
325
/// void fun4(int &);
326
/// void fun5(const int &);
327
/// void fun5(std::shared_ptr<int>);
328
/// void fun6(std::shared_ptr<const int>);
329
/// void fun7(const std::shared_ptr<int> &);
330
/// void fun8(const std::shared_ptr<const int> &);
331
/// void fun9(std::reference_wrapper<int>);
332
/// void fun10(std::reference_wrapper<const int>);
333
///
334
/// int main()
335
/// {
336
///   using namespace chaiscript
337
///   chaiscript::ChaiScript chai;
338
///   chai.add(fun(fun1), "fun1");
339
///   chai.add(fun(fun2), "fun2");
340
///   chai.add(fun(fun3), "fun3");
341
///   chai.add(fun(fun4), "fun4");
342
///   chai.add(fun(fun5), "fun5");
343
///   chai.add(fun(fun6), "fun6");
344
///   chai.add(fun(fun7), "fun7");
345
///   chai.add(fun(fun8), "fun8");
346
///   chai.add(fun(fun9), "fun9");
347
///   chai.add(fun(fun10), "fun10");
348
///
349
///   chai("var i = 10;");
350
///   chai("fun1(i)");
351
///   chai("fun2(i)");
352
///   chai("fun3(i)");
353
///   chai("fun4(i)");
354
///   chai("fun5(i)");
355
///   chai("fun6(i)");
356
///   chai("fun7(i)");
357
///   chai("fun8(i)");
358
///   chai("fun9(i)");
359
///   chai("fun10(i)");
360
/// }
361
/// ~~~~~~~~
362
///
363
/// See the unit test unittests/boxed_cast_test.cpp for a complete breakdown of the automatic casts that
364
/// available and tested.
365
///
366
/// -----------------------------------------------------------------------
367
///
368
/// @subsection baseclasses Base Classes
369
///
370
/// ChaiScript supports handling of passing a derived class object to a function expecting a base class object.
371
/// For the process to work, the base/derived relationship must be registered with the engine.
372
///
373
/// ~~~~~~~~{.cpp}
374
/// class Base {};
375
/// class Derived : public Base {};
376
/// void myfunction(Base *b);
377
///
378
/// int main()
379
/// {
380
///   chaiscript::ChaiScript chai;
381
///   chai.add(chaiscript::base_class<Base, Derived>());
382
///   Derived d;
383
///   chai.add(chaiscript::var(&d), "d");
384
///   chai.add(chaiscript::fun(&myfunction), "myfunction");
385
///   chai("myfunction(d)");
386
/// }
387
/// ~~~~~~~~
388
///
389
/// -----------------------------------------------------------------------
390
///
391
///
392
/// @subsection functionobjects Function Objects
393
///
394
/// Functions are first class objects in ChaiScript and ChaiScript supports automatic conversion
395
/// between ChaiScript functions and std::function objects.
396
///
397
/// ~~~~~~~~{.cpp}
398
/// void callafunc(const std::function<void (const std::string &)> &t_func)
399
/// {
400
///   t_func("bob");
401
/// }
402
///
403
/// int main()
404
/// {
405
///   chaiscript::ChaiScript chai;
406
///   chai.add(chaiscript::fun(&callafunc), "callafunc");
407
///   chai("callafunc(fun(x) { print(x); })"); // pass a lambda function to the registered function
408
///                                            // which expects a typed std::function
409
///
410
///   std::function<void ()> f = chai.eval<std::function<void ()> >("dump_system");
411
///   f(); // call the ChaiScript function dump_system, from C++
412
/// }
413
/// ~~~~~~~~
414
///
415
/// -----------------------------------------------------------------------
416
///
417
///
418
/// @subsection threading Threading
419
///
420
/// Thread safety is automatically handled within the ChaiScript system. Objects can be added
421
/// and scripts executed from multiple threads. For each thread that executes scripts, a new
422
/// context is created and managed by the engine.
423
///
424
/// Thread safety can be disabled by defining CHAISCRIPT_NO_THREADS when using the library.
425
///
426
/// Disabling thread safety increases performance in many cases.
427
///
428
/// -----------------------------------------------------------------------
429
///
430
///
431
/// @subsection exceptions Exception Handling
432
///
433
/// @subsubsection exceptionsbasics Exception Handling Basics
434
///
435
/// Exceptions can be thrown in ChaiScript and caught in C++ or thrown in C++ and caught in
436
/// ChaiScript.
437
///
438
/// ~~~~~~~~{.cpp}
439
/// void throwexception()
440
/// {
441
///   throw std::runtime_error("err");
442
/// }
443
///
444
/// int main()
445
/// {
446
///   // Throw in C++, catch in ChaiScript
447
///   chaiscript::ChaiScript chai;
448
///   chai.add(chaiscript::fun(&throwexception), "throwexception");
449
///   chai("try { throwexception(); } catch (e) { print(e.what()); }"); // prints "err"
450
///
451
///   // Throw in ChaiScript, catch in C++
452
///   try {
453
///     chai("throw(1)");
454
///   } catch (chaiscript::Boxed_Value bv) {
455
///     int i = chaiscript::boxed_cast<int>(bv);
456
///     // i == 1
457
///   }
458
/// }
459
/// ~~~~~~~~
460
///
461
/// @subsubsection exceptionsautomatic Exception Handling Automatic Unboxing
462
///
463
/// As an alternative to the manual unboxing of exceptions shown above, exception specifications allow the user to tell
464
/// ChaiScript what possible exceptions are expected from the script being executed.
465
///
466
/// Example:
467
/// ~~~~~~~~{.cpp}
468
/// chaiscript::ChaiScript chai;
469
///
470
/// try {
471
///   chai.eval("throw(runtime_error(@"error@"))", chaiscript::exception_specification<int, double, float, const std::string &, const
472
///   std::exception &>());
473
/// } catch (const double e) {
474
/// } catch (int) {
475
/// } catch (float) {
476
/// } catch (const std::string &) {
477
/// } catch (const std::exception &e) {
478
///   // This is the one what will be called in the specific throw() above
479
/// }
480
/// ~~~~~~~~
481
///
482
/// @sa chaiscript::Exception_Handler for details on automatic exception unboxing
483
/// @sa chaiscript::exception_specification
484

485
/// @page LangObjectSystemRef ChaiScript Language Object Model Reference
486
///
487
///
488
/// ChaiScript has an object system built in, for types defined within the ChaiScript system.
489
///
490
/// ~~~~~~~~~
491
/// attr Rectangle::height
492
/// attr Rectangle::width
493
/// def Rectangle::Rectangle() { this.height = 10; this.width = 20 }
494
/// def Rectangle::area() { this.height * this.width }
495
///
496
/// var rect = Rectangle()
497
/// rect.height = 30
498
/// print(rect.area())
499
/// ~~~~~~~~~
500
///
501
/// Since ChaiScript 5.4.0 it has been possible to use the "class" keyword to simplify this code.
502
///
503
/// ~~~~~~~~~
504
/// class Rectangle {
505
///   attr height
506
///   attr width
507
///   def Rectangle() { this.height = 10; this.width = 20 }
508
///   def area() { this.height * this.width }
509
/// }
510
///
511
/// var rect = Rectangle()
512
/// rect.height = 30
513
/// print(rect.area())
514
/// ~~~~~~~~~
515
///
516
/// @sa @ref keywordattr
517
/// @sa @ref keyworddef
518

519
/// @page LangInPlaceRef ChaiScript Language In-Place Creation Reference
520
/// @section inplacevector Vector
521
///
522
/// ~~~~~~~~~
523
/// In-place Vector ::= "[" [expression ("," expression)*]  "]"
524
/// ~~~~~~~~~
525
///
526
/// @section inplacerangedvector Ranged Vector
527
///
528
/// ~~~~~~~~~
529
/// In-place Ranged Vector ::= "[" value ".." value "]"
530
/// ~~~~~~~~~
531
///
532
/// Creates a vector over a range (eg. 1..10)
533
///
534
/// @section inplacemap Map
535
///
536
/// ~~~~~~~~
537
/// In-place Map ::= "[" (string ":" expression)+ "]"
538
/// ~~~~~~~~
539

540
/// @page LangGettingStarted ChaiScript Language Getting Started
541
///
542
/// ChaiScript is a simple language that should feel familiar to anyone who knows
543
/// C++ or ECMAScript (JavaScript).
544
///
545
/// -----------------------------------------------------------------------
546
///
547
/// @section chaiscriptloops Loops
548
///
549
/// Common looping constructs exist in ChaiScript
550
///
551
/// ~~~~~~~~
552
/// var i = 0;
553
/// while (i < 10)
554
/// {
555
///   // do something
556
///   ++i;
557
/// }
558
/// ~~~~~~~~
559
///
560
/// ~~~~~~~~
561
/// for (var i = 0; i < 10; ++i)
562
/// {
563
///   // do something
564
/// }
565
/// ~~~~~~~~
566
///
567
/// @sa @ref keywordfor
568
/// @sa @ref keywordwhile
569
///
570
/// -----------------------------------------------------------------------
571
///
572
/// @section chaiscriptifs Conditionals
573
///
574
/// If statements work as expected
575
///
576
/// ~~~~~~~~
577
/// var b = true;
578
///
579
/// if (b) {
580
///   // do something
581
/// } else if (c < 10) {
582
///   // do something else
583
/// } else {
584
///   // or do this
585
/// }
586
/// ~~~~~~~~
587
///
588
/// @sa @ref keywordif
589
///
590
/// -----------------------------------------------------------------------
591
///
592
/// @section chaiscriptfunctions Functions
593
///
594
/// Functions are defined with the def keyword
595
///
596
/// ~~~~~~~~
597
/// def myfun(x) { print(x); }
598
///
599
/// myfun(10);
600
/// ~~~~~~~~
601
///
602
/// Functions may have "guards" which determine if which is called.
603
///
604
/// ~~~~~~~~
605
/// eval> def myfun2(x) : x < 10 { print("less than 10"); }
606
/// eval> def myfun2(x) : x >= 10 { print("10 or greater"); }
607
/// eval> myfun2(5)
608
/// less than 10
609
/// eval> myfun2(12)
610
/// 10 or greater
611
/// ~~~~~~~~
612
///
613
/// @sa @ref keyworddef
614
/// @sa @ref keywordattr
615
/// @sa @ref LangObjectSystemRef
616
///
617
/// -----------------------------------------------------------------------
618
///
619
/// @section chaiscriptfunctionobjects Function Objects
620
///
621
/// Functions are first class types in ChaiScript and can be used as variables.
622
///
623
/// ~~~~~~~~
624
/// eval> var p = print;
625
/// eval> p(1);
626
/// 1
627
/// ~~~~~~~~
628
///
629
/// They can also be passed to functions.
630
///
631
/// ~~~~~~~~
632
/// eval> def callfunc(f, lhs, rhs) { return f(lhs, rhs); }
633
/// eval> def do_something(lhs, rhs) { print("lhs: ${lhs}, rhs: ${rhs}"); }
634
/// eval> callfunc(do_something, 1, 2);
635
/// lhs: 1, rhs: 2
636
/// ~~~~~~~~
637
///
638
/// Operators can also be treated as functions by using the back tick operator. Building on the above example:
639
///
640
/// ~~~~~~~~
641
/// eval> callfunc(`+`, 1, 4);
642
/// 5
643
/// eval> callfunc(`*`, 3, 2);
644
/// 6
645
/// ~~~~~~~~
646
///
647
/// -----------------------------------------------------------------------
648
///
649
/// @sa @ref LangKeywordRef
650
/// @sa ChaiScript_Language for Built in Functions
651

652
/// @page LangKeywordRef ChaiScript Language Keyword Reference
653
///
654
///
655
/// -----------------------------------------------------------------------
656
///
657
/// @section keywordattr attr
658
/// Defines a ChaiScript object attribute
659
///
660
/// ~~~~~~~~
661
/// Attribute Definition ::= "attr" class_name "::" attribute_name
662
/// ~~~~~~~~
663
///
664
/// @sa @ref LangObjectSystemRef
665
///
666
///
667
/// -----------------------------------------------------------------------
668
///
669
/// @section keywordauto auto
670
///
671
/// Defines a variable
672
///
673
/// ~~~~~~~~
674
/// Variable ::= "auto" identifier
675
/// ~~~~~~~~
676
///
677
/// Synonym for @ref keywordvar
678
///
679
/// -----------------------------------------------------------------------
680
///
681
/// @section keywordbreak break
682
/// Stops execution of a looping block.
683
///
684
/// ~~~~~~~~
685
/// Break Statement ::= "break"
686
/// ~~~~~~~~
687
///
688
/// @sa @ref keywordfor
689
/// @sa @ref keywordwhile
690
///
691
///
692
/// -----------------------------------------------------------------------
693
///
694
/// @section keyworddef def
695
/// Begins a function or method definition
696
///
697
/// ~~~~~~~~
698
/// Function Definition ::= "def" identifier "(" [[type] arg ("," [type] arg)*] ")" [":" guard] block
699
/// Method Definition ::= "def" class_name "::" method_name "(" [[type] arg ("," [type] arg)*] ")" [":" guard] block
700
/// ~~~~~~~~
701
///
702
/// identifier: name of function. Required.
703
/// args: comma-delimited list of parameter names with optional type specifiers. Optional.
704
/// guards: guarding statement that act as a prerequisite for the function. Optional.
705
/// { }: scoped block as function body. Required.
706
///
707
/// Functions return values in one of two ways:
708
///
709
/// By using an explicit return call, optionally passing the value to be returned.
710
/// By implicitly returning the value of the last expression (if it is not a while or for loop).
711
///
712
/// Method definitions for known types extend those types with new methods. This includes C++ and ChaiScript defined types.
713
/// Method definitions for unknown types implicitly define the named type.
714
///
715
/// @sa @ref LangObjectSystemRef
716
///
717
///
718
/// -----------------------------------------------------------------------
719
///
720
/// @section keywordelse else
721
/// @sa @ref keywordif
722
///
723
///
724
/// -----------------------------------------------------------------------
725
///
726
/// @section keywordfor for
727
/// ~~~~~~~~
728
/// For Block ::= "for" "(" [initial] ";" stop_condition ";" loop_expression ")" block
729
/// ~~~~~~~~
730
/// This loop can be broken using the @ref keywordbreak command.
731
///
732
///
733
/// -----------------------------------------------------------------------
734
///
735
/// @section keywordfun fun
736
/// Begins an anonymous function declaration (sometimes called a lambda).
737
///
738
/// ~~~~~~~~
739
/// Lambda ::= "fun" "(" [variable] ("," variable)*  ")" block
740
/// ~~~~~~~~
741
///
742
/// _Example_
743
///
744
/// ~~~~~~~~
745
/// // Generate an anonymous function object that adds 2 to its parameter
746
/// var f = fun(x) { x + 2; }
747
/// ~~~~~~~~
748
///
749
/// @sa @ref keyworddef for more details on ChaiScript functions
750
///
751
///
752
/// -----------------------------------------------------------------------
753
///
754
/// @section keywordif if
755
/// Begins a conditional block of code that only executes if the condition evaluates as true.
756
/// ~~~~~~~~
757
/// If Block ::= "if" "(" condition ")" block
758
/// Else If Block ::= "else if" "(" condition ")" block
759
/// Else Block ::= "else" block
760
/// ~~~~~~~~
761
///
762
/// _Example_
763
///
764
/// ~~~~~~~~
765
/// if (true) {
766
///   // do something
767
/// } else if (false) {
768
///   // do something else
769
/// } else {
770
///   // otherwise do this
771
/// }
772
/// ~~~~~~~~
773
///
774
///
775
/// -----------------------------------------------------------------------
776
///
777
/// @section keywordtry try
778
/// ~~~~~~~~
779
/// Try Block ::= "try" block
780
///  ("catch" ["(" [type] variable ")"] [":" guards] block)+
781
///    ["finally" block]
782
/// ~~~~~~~~
783
///
784
/// @sa ChaiScript_Language::throw
785
///
786
///
787
/// -----------------------------------------------------------------------
788
///
789
/// @section keywordwhile while
790
///
791
/// Begins a conditional block of code that loops 0 or more times, as long as the condition is true
792
///
793
/// ~~~~~~~~
794
/// While Block ::= "while" "(" condition ")" block
795
/// ~~~~~~~~
796
///
797
/// This loop can be broken using the @ref keywordbreak command.
798
///
799
///
800
/// -----------------------------------------------------------------------
801
///
802
/// @section keywordvar var
803
///
804
/// Defines a variable
805
///
806
/// ~~~~~~~~
807
/// Variable ::= "var" identifier
808
/// ~~~~~~~~
809
///
810
/// Synonym for @ref keywordauto
811

812
/// @namespace chaiscript
813
/// @brief Namespace chaiscript contains every API call that the average user will be concerned with.
814

815
/// @namespace chaiscript::detail
816
/// @brief Classes and functions reserved for internal use. Items in this namespace are not supported.
817

818
#include "chaiscript_basic.hpp"
819
#include "chaiscript_stdlib.hpp"
820
#include "language/chaiscript_parser.hpp"
821

822
namespace chaiscript {
823
  class ChaiScript : public ChaiScript_Basic {
824
  public:
825 1
    ChaiScript(std::vector<std::string> t_modulepaths = {},
826
               std::vector<std::string> t_usepaths = {},
827
               std::vector<Options> t_opts = chaiscript::default_options())
828 1
        : ChaiScript_Basic(chaiscript::Std_Lib::library(),
829 1
                           std::make_unique<parser::ChaiScript_Parser<eval::Noop_Tracer, optimizer::Optimizer_Default>>(),
830 1
                           std::move(t_modulepaths),
831 1
                           std::move(t_usepaths),
832 1
                           std::move(t_opts)) {
833
    }
834
  };
835
} // namespace chaiscript
836

837
#endif /* CHAISCRIPT_HPP_ */

Read our documentation on viewing source code .

Loading