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

11
#ifndef CHAISCRIPT_HPP_
12
#define CHAISCRIPT_HPP_
13

14

15

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

486

487

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

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

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

655

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

816

817
/// @namespace chaiscript
818
/// @brief Namespace chaiscript contains every API call that the average user will be concerned with.
819

820
/// @namespace chaiscript::detail
821
/// @brief Classes and functions reserved for internal use. Items in this namespace are not supported.
822

823
#include "chaiscript_basic.hpp"
824
#include "language/chaiscript_parser.hpp"
825
#include "chaiscript_stdlib.hpp"
826

827

828
namespace chaiscript 
829
{
830
  class ChaiScript : public ChaiScript_Basic
831
  {
832
    public:
833 1
      ChaiScript(std::vector<std::string> t_modulepaths = {},
834
          std::vector<std::string> t_usepaths = {},
835
          const std::vector<Options> &t_opts = chaiscript::default_options())
836 1
        : ChaiScript_Basic(
837 1
            chaiscript::Std_Lib::library(),
838 1
            std::make_unique<parser::ChaiScript_Parser<eval::Noop_Tracer, optimizer::Optimizer_Default>>(),
839 1
            t_modulepaths, t_usepaths, t_opts)
840
        {
841
        }
842
  };
843
}
844

845
#endif /* CHAISCRIPT_HPP_ */

Read our documentation on viewing source code .

Loading