docs/build/html/_sources/lowlevel.txt

   1 .. index::
   2         single: 低水準関数; はじめに
   3
   4 ==========
   5 低水準関数
   6 ==========
   7
   8 低水準関数を学びます。
   9
  10 * callgc()
  11 * varptr()
  12 * space()
  13 * nullpointer()
  14 * object2pointer()
  15 * pointer2object()
  16 * ispointer()
  17 * ptrcmp()
  18 * ringvm_cfunctionslist()
  19 * ringvm_functionslist()
  20 * ringvm_classeslist()
  21 * ringvm_packageslist()
  22 * ringvm_memorylist()
  23 * ringvm_calllist()
  24 * ringvm_fileslist()
  25 * ringvm_settrace()
  26 * ringvm_tracedata()
  27 * ringvm_traceevent()
  28 * ringvm_tracefunc()
  29 * ringvm_scopescount()
  30 * ringvm_evalinscope()
  31 * ringvm_passerror()
  32 * ringvm_hideerrorMsg()
  33 * ringvm_callfunc()
  34 * ringvm_see()
  35 * ringvm_give()
  36 * ringvm_info()
  37
  38 .. index::
  39         pair: 低水準関数; callgc()
  40
  41 callgc() 関数
  42 =============
  43
  44 この関数は、関数実行中に代入操作では解放されない一時作業用変数を用いるループで強制的にガベージコレクター呼び出すために使用します。
  45
  46 この関数が必要になることは非常に稀なことですが、ゲームエンジンでイベントループなどを作成して、
  47 関数を呼び出して即席でリストの作成を開始するときに便利です。
  48
  49 用例
  50
  51 .. code-block:: ring
  52
  53         While True
  54
  55                 # イベントの処理
  56                 # 一時作業領域による関数の呼び出し。 myfunc(["temp list"]) などのリストです。
  57
  58                 # ガベージコレクターの呼び出し
  59                 callgc()
  60         End
  61
  62 .. tip:: Ring のガベージコレクターは関数の実行終了後または、
  63          代入ステートメントを使用したときに自動的に動作します。
  64
  65 .. index::
  66         pair: 低水準関数; varptr()
  67
  68 varptr() 関数
  69 =============
  70
  71 varptr() 関数は C / C++ 関数へポインタを渡します。
  72
  73 文法:
  74
  75 .. code-block:: ring
  76
  77         varptr(cVariableName, cPointerType) ---> 低水準オブジェクト (C ポインタ)
  78
  79 用例:
  80
  81 .. code-block:: ring
  82
  83         r = 10
  84         z = 20
  85         see r + nl
  86         see varptr("r","int")
  87         see varptr("z","int")
  88
  89 実行結果:
  90
  91 .. code-block:: ring
  92
  93         10
  94         00E3C740
  95         int
  96         2
  97         00E3BEC0
  98         int
  99         2
 100
 101 .. note:: 低水準オブジェクトのリストには三つの項目 (ポインタ、型、ステータス) を有しています。
 102
 103
 104 .. index::
 105         pair: 低水準関数; space()
 106
 107 space() 関数
 108 ============
 109
 110 space() 関数は指定されたバイト数のメモリ領域を確保します。
 111
 112 文法:
 113
 114 .. code-block:: ring
 115
 116         Space(nBytesCount) ---> 文字列
 117
 118 用例:
 119
 120 .. code-block:: ring
 121
 122         mystring = space(200)
 123         See "String Size : " + len(mystring) + nl
 124         See "String : " + mystring + nl
 125         See "String Pointer : "
 126         See varptr("mystring","char *")
 127
 128 実行結果:
 129
 130 .. code-block:: ring
 131
 132         String Size : 200
 133         String :
 134         String Pointer : 00FF8FE8
 135         char *
 136         2
 137
 138 .. note:: C 関数へバッファを渡すは space() と VarPtr() 関数が必要です。
 139
 140 .. index::
 141         pair: 低水準関数; nullpointer()
 142
 143 nullpointer() 関数
 144 ==================
 145
 146 仮引数でポインタを扱うことを想定しており、オプション扱いの仮引数に NULL ポインタを受け入れる場合は C 関数へ NULL ポインタを必ず渡してください。
 147
 148 用例:
 149
 150 この用例は LibSDL ライブラリから RingSDL にある SDL_BlitSurface() 関数を使用しています。
 151 この関数は第二仮引数、および最後の仮引数で SDL_Rect ポインタを受け入れます。
 152 また、関数は NULL ポインタを受け入れるために、 NULLPointer() 関数で NULL ポインタを渡せます。
 153
 154 .. code-block:: ring
 155
 156         SDL_BlitSurface(text, nullpointer(), surface, nullpointer())
 157
 158 .. note:: 前述のコードは単体では動作しません。最初に RingSDL の用法を学ぶ必要があります。
 159
 160 .. tip:: NULLPointer() 関数の代わりに NULL を仮引数として渡せます。
 161
 162 .. index::
 163         pair: 低水準関数; object2pointer()
 164
 165 object2pointer() 関数
 166 =====================
 167
 168 この関数は Ring リスト用の C ポインタとオブジェクトを取得します。
 169
 170 文法:
 171
 172 .. code-block:: ring
 173
 174         object2pointer(リスト|オブジェクト) --> 低水準オブジェクト (C ポインタ)
 175
 176 .. index::
 177         pair: 低水準関数; pointer2object()
 178
 179 pointer2object() 関数
 180 =====================
 181
 182 この関数は低水準オブジェクト (C ポインタ) から Ring のリスト、および / またはオブジェクトを取得します。
 183
 184 文法:
 185
 186 .. code-block:: ring
 187
 188         pointer2object(Low Level Object) ---> リスト|オブジェクト
 189
 190
 191 用例:
 192
 193 .. code-block:: ring
 194
 195         # リストの作成
 196         mylist = 1:5
 197
 198         # リストのポインタを作成
 199         x = object2pointer(mylist)
 200         see x
 201
 202         see nl
 203
 204         # リストへ項目を追加
 205         mylist + "welcome"
 206
 207         # リストの項目を表示
 208         y = pointer2object(x)
 209         see y
 210
 211 実行結果:
 212
 213 .. code-block:: ring
 214
 215         0069A5D8
 216         OBJECTPOINTER
 217         0
 218
 219         1
 220         2
 221         3
 222         4
 223         5
 224         welcome
 225
 226 .. note:: Ring の代入演算子は値によりリストとオブジェクトをコピーします。
 227         参照によりコピーするには object2pointer() および pointer2object() 関数を使用します。
 228
 229 .. tip:: object2pointer() および pointer2object() は stdlib で使用されています。
 230         Tree クラスの実装では子ノード (別オブジェクト) は親ノード (オブジェクト) を参照して作成します。
 231
 232 .. index::
 233         pair: 低水準関数; ispointer()
 234
 235 ispointer() 関数
 236 ================
 237
 238 仮引数がポインタ (C オブジェクト) であるか検査します。
 239
 240 文法:
 241
 242 .. code-block:: none
 243
 244         IsPointer(vPara) ---> True|False
 245
 246 用例:
 247
 248 .. code-block:: ring
 249
 250         fp = fopen(filename(),"r")
 251
 252         ? type(fp)
 253
 254         ? ispointer(fp)
 255
 256 実行結果:
 257
 258 .. code-block:: none
 259
 260         file
 261         1
 262
 263 .. index::
 264         pair: 低水準関数; ptrcmp()
 265
 266 ptrcmp() 関数
 267 =============
 268
 269 ptrcmp() 関数は二つのポインタ (C オブジェクト) 間で比較します。
 270
 271 文法:
 272
 273 .. code-block:: ring
 274
 275         ptrcmp(oObject1,oObject2) ---> oObject1 と oObject2 が等しいならば値は 1
 276                                        oObject1 と oObject2 が等しくないならば値は 0
 277
 278 用例:
 279
 280 .. code-block:: ring
 281
 282         fp = fopen("ptrcmp.ring","r")
 283         fp2 = fp
 284         fp3 = fopen("ptrcmp.ring","r")
 285
 286         see ptrcmp(fp,fp2) + nl
 287         see ptrcmp(fp,fp3) + nl
 288
 289         fclose(fp)
 290         fclose(fp3)
 291
 292 実行結果:
 293
 294 .. code-block:: ring
 295
 296         1
 297         0
 298
 299 .. index::
 300         pair: 低水準関数; RingVM_CFunctionsList()
 301
 302 ringvm_cfunctionslist() 関数
 303 ============================
 304
 305 C で記述された関数のリストを返す Ring 低水準関数です。
 306
 307 文法:
 308
 309 .. code-block:: ring
 310
 311         RingVM_CFunctionsList() ---> リスト
 312
 313 用例:
 314
 315 .. code-block:: ring
 316
 317         See RingVM_CFunctionsList()
 318
 319 .. index::
 320         pair: 低水準関数; RingVM_FunctionsList()
 321
 322 ringvm_functionslist() 関数
 323 ===========================
 324
 325 Ring で記述された関数のリストを返す関数です。
 326
 327 各リストメンバは次の項目のリストを有しています。
 328
 329 * 関数名
 330 * プログラムカウンタ (PC) - バイトコードによる関数の位置
 331 * ソースコードファイル名
 332 * プライベートフラグ (クラスにあるプライベートメソッドならば)
 333
 334 文法:
 335
 336 .. code-block:: ring
 337
 338         RingVM_FunctionsList() ---> リスト
 339
 340 用例:
 341
 342 .. code-block:: ring
 343
 344         test()
 345
 346         func test
 347                 see ringvm_functionslist()
 348
 349 実行結果:
 350
 351 .. code-block:: ring
 352
 353         test
 354         8
 355         B:/ring/tests/scripts/functionslist.ring
 356         0
 357
 358 .. index::
 359         pair: 低水準関数; RingVM_ClassesList()
 360
 361 ringvm_classeslist() 関数
 362 =========================
 363
 364 クラスのリストを返す関数です。
 365
 366 各リストメンバは次の項目のリストを有しています。
 367
 368 * クラス名
 369 * プログラムカウンタ (PC) - バイトコードによるクラスの位置
 370 * 親クラス名
 371 * メソッドのリスト
 372 * フラグ (親クラス情報の収集)
 373 * パッケージへのポインタ (または未使用のパッケージならば NULL)
 374
 375 文法:
 376
 377 .. code-block:: ring
 378
 379         RingVM_ClassesList() ---> リスト
 380
 381 用例:
 382
 383 .. code-block:: ring
 384
 385         see ringvm_classeslist()
 386
 387         class class1
 388                 func f1
 389         class class2 from class1
 390         class class3 from class1
 391
 392 実行結果:
 393
 394 .. code-block:: ring
 395
 396         class1
 397         9
 398
 399         f1
 400         13
 401         B:/ring/tests/scripts/classeslist.ring
 402         0
 403         0
 404         00000000
 405         class2
 406         16
 407         class1
 408         0
 409         00000000
 410         class3
 411         20
 412         class1
 413         0
 414         00000000
 415
 416 .. index::
 417         pair: 低水準関数; RingVM_PackagesList()
 418
 419 ringvm_packageslist() 関数
 420 ==========================
 421
 422 パッケージのリストを返す関数です。
 423
 424 各リストメンバは次の項目のリストを有しています。
 425
 426 * パッケージ名
 427 * クラスのリスト
 428
 429 文法:
 430
 431 .. code-block:: ring
 432
 433         RingVM_PackagesList() ---> リスト
 434
 435 用例:
 436
 437 .. code-block:: ring
 438
 439         see ringvm_packageslist()
 440
 441         package package1
 442                 class class1
 443
 444         package package2
 445                 class class1
 446
 447         package package3
 448                 class class1
 449
 450 実行結果:
 451
 452 .. code-block:: ring
 453
 454         package1
 455         class1
 456         11
 457
 458         0
 459         00FEF838
 460         package2
 461         class1
 462         17
 463
 464         0
 465         00FEF978
 466         package3
 467         class1
 468         23
 469
 470         0
 471         00FEFF68
 472
 473 .. index::
 474         pair: 低水準関数; RingVM_MemoryList()
 475
 476 ringvm_memorylist() 関数
 477 ========================
 478
 479 メモリのスコープと変数のリストを返す関数です。
 480
 481 各リストメンバには、次の異なるスコープにある変数のリストを有しています。
 482
 483 スコープリストにある各項目のリストには次の項目があります。
 484
 485 * 変数の名前
 486 * 変数の型
 487 * 変数の値
 488 * 値がリストの場合はポインタの型 (リスト/項目)
 489 * プライベートフラグ (変数がクラスの属性ならば)
 490
 491 文法:
 492
 493 .. code-block:: ring
 494
 495         RingVM_MemoryList() ---> リスト
 496
 497 用例:
 498
 499 .. code-block:: ring
 500
 501         x = 10
 502         test()
 503         func test
 504                 y = 20
 505                 see ringvm_memorylist()
 506
 507 実行結果:
 508
 509 .. code-block:: ring
 510
 511         true
 512         2
 513         1
 514         0
 515         0
 516         false
 517         2
 518         0
 519         0
 520         0
 521         nl
 522         1
 523
 524
 525         0
 526         0
 527         null
 528         1
 529
 530         0
 531         0
 532         ring_gettemp_var
 533         4
 534         00000000
 535         0
 536         0
 537         ccatcherror
 538         1
 539         NULL
 540         0
 541         0
 542         ring_settemp_var
 543         4
 544         00000000
 545         0
 546         0
 547         ring_tempflag_var
 548         2
 549         0
 550         0
 551         0
 552         stdin
 553         3
 554         50512DB8
 555         file
 556         0
 557         0
 558         0
 559         stdout
 560         3
 561         50512DD8
 562         file
 563         0
 564         0
 565         0
 566         stderr
 567         3
 568         50512DF8
 569         file
 570         0
 571         0
 572         0
 573         this
 574         4
 575         00000000
 576         0
 577         0
 578         sysargv
 579         3
 580         B:/ring/bin/ring
 581         B:/ring/tests/scripts/memorylist.ring
 582         0
 583         0
 584         x
 585         2
 586         10
 587         0
 588         0
 589         y
 590         2
 591         20
 592         0
 593         0
 594
 595 .. index::
 596         pair: 低水準関数; RingVM_CallList()
 597
 598 ringvm_calllist() 関数
 599 ======================
 600
 601 関数呼び出しリストのリストを返す関数です。
 602
 603 各リストメンバは次の項目のリストを有しています。
 604
 605 * 関数の型
 606 * 関数の名前
 607 * プログラムカウンタ (PC)
 608 * スタックポインタ (SP)
 609 * 一時作業用。メモリのリスト
 610 * メソッドまたは関数のフラグ
 611 * 呼び出し元のプログラムカウンタ (PC)
 612 * FuncExec フラグ
 613 * ListStart フラグ
 614 * 入れ子リストのポインタ
 615 * ステートリスト
 616
 617
 618 文法:
 619
 620 .. code-block:: ring
 621
 622         RingVM_CallList() ---> リスト
 623
 624 用例:
 625
 626 .. code-block:: ring
 627
 628         hello()
 629         func hello
 630                 test()
 631
 632         func test
 633                 mylist = ringvm_calllist()
 634                 for t in mylist see t[2] + nl next
 635
 636 実行結果:
 637
 638 .. code-block:: ring
 639
 640         function hello() in file B:/ring/tests/scripts/calllist.ring
 641         called from line 1
 642         function test() in file B:/ring/tests/scripts/calllist.ring
 643         called from line 3
 644         ringvm_calllist
 645
 646
 647 .. index::
 648         pair: 低水準関数; RingVM_FilesList()
 649
 650 ringvm_fileslist() 関数
 651 =======================
 652
 653 Ring ファイルのリストを返す関数です。
 654
 655 文法:
 656
 657 .. code-block:: ring
 658
 659         RingVM_FilesList() ---> リスト
 660
 661 用例:
 662
 663 .. code-block:: ring
 664
 665         load "stdlib.ring"
 666         see ringvm_fileslist()
 667
 668 実行結果:
 669
 670 .. code-block:: ring
 671
 672         B:/ring/tests/scripts/fileslist.ring
 673         B:\ring\bin\stdlib.ring
 674         eval
 675         stdlib.ring
 676         stdlib.rh
 677         stdclasses.ring
 678         stdfunctions.ring
 679         stdbase.ring
 680         stdstring.ring
 681         stdlist.ring
 682         stdstack.ring
 683         stdqueue.ring
 684         stdmath.ring
 685         stddatetime.ring
 686         stdfile.ring
 687         stdsystem.ring
 688         stddebug.ring
 689         stddatatype.ring
 690         stdconversion.ring
 691         stdodbc.ring
 692         stdmysql.ring
 693         stdsecurity.ring
 694         stdinternet.ring
 695         stdhashtable.ring
 696         stdtree.ring
 697
 698 .. index::
 699         pair: 低水準関数; ringvm_settrace()
 700
 701 ringvm_settrace() 関数
 702 ======================
 703
 704 ringvm_settrace() はトレース関数名を決定する関数です。
 705
 706 トレース関数は Ring
 707 関数でありイベントごとに呼び出されます。
 708
 709 文法:
 710
 711 .. code-block:: ring
 712
 713         RingVM_SetTrace(cCode)
 714
 715 .. index::
 716         pair: 低水準関数; ringvm_tracedata()
 717
 718 ringvm_tracedata() 関数
 719 =======================
 720
 721 関数の内側でイベントをトレースします。
 722
 723 ringvm_tracedata() 関数はイベントデータを取得します。
 724
 725 イベントデータのリストには次の項目があります。
 726
 727 * ソースコードの行番号
 728 * ソースファイル名
 729 * 関数またはメソッド名
 730 * メソッドまたは関数 (Bool : True=メソッド、 False=関数またはファイル)
 731
 732 文法:
 733
 734 .. code-block:: ring
 735
 736         RingVM_TraceData() ---> aDataList
 737
 738 .. index::
 739         pair: 低水準関数; ringvm_traceevent()
 740
 741 ringvm_traceevent() 関数
 742 ========================
 743
 744 関数の内側でイベントをトレースします。
 745
 746 ringvm_traceevent() 関数はイベントの種類を検出します。
 747
 748 * 改行
 749 * 関数の前
 750 * 関数の後
 751 * ランタイムエラー
 752 * C 関数の前
 753 * C 関数の後
 754
 755 文法:
 756
 757 .. code-block:: ring
 758
 759         RingVM_TraceEvent() ---> nTraceEvent
 760
 761 .. index::
 762         pair: 低水準関数; ringvm_tracefunc()
 763
 764 ringvm_tracefunc() 関数
 765 =======================
 766
 767 この関数はイベントのトレースで使用する関数名を返します。
 768
 769 文法:
 770
 771 .. code-block:: ring
 772
 773         RingVM_TraceEvent() ---> cCode
 774
 775 .. index::
 776         pair: 低水準関数; ringvm_scopescount()
 777
 778 ringvm_scopescount() 関数
 779 =========================
 780
 781 RingVM_ScopesCount() 関数は、
 782 アプリケーションで使用されているスコープの本数を検出します。
 783
 784 プログラムの開始時において、スコープは存在します (グローバルスコープのみ)。
 785
 786 関数の呼び出し時に、新しいスコープが作成されます。
 787
 788 関数実行終了後は、関数のスコープは削除されます。
 789
 790 文法:
 791
 792 .. code-block:: ring
 793
 794         RingVM_ScopesCount() ---> nScopes
 795
 796 .. index::
 797         pair: 低水準関数; ringvm_evalinscope()
 798
 799 ringvm_evalinscope() 関数
 800 =========================
 801
 802 ringvm_evalinscope() は eval() 関数と類似する関数です。
 803
 804 eval() とは異なり、現在のスコープにあるコードを実行します。
 805
 806 RingVM_EvalInScope() は指定されたスコープにあるスコープを実行します。
 807
 808 文法:
 809
 810 .. code-block:: ring
 811
 812         RingVM_EvalInScope(nScope,cCode)
 813
 814 .. index::
 815         pair: 低水準関数; ringvm_passerror()
 816
 817 ringvm_passerror() 関数
 818 =======================
 819
 820 ランタイムエラーが発生した時はエラーメッセージを表示後に
 821 Ring はプログラムの実行を終了します。
 822
 823 ringvm_passerror() 関数を使うと、
 824 前述の動作を回避してプログラムの実行を継続できます。
 825
 826 文法:
 827
 828 .. code-block:: ring
 829
 830         RingVM_PassError()
 831
 832 .. index::
 833         pair: 低水準関数; ringvm_hideerrorMsg()
 834
 835 ringvm_hideerrormsg() 関数
 836 ==========================
 837
 838 RingVM_HideErrorMsg() 関数は、
 839 ランタイムエラーメッセージの表示を有効または無効化します。
 840
 841 文法:
 842
 843 .. code-block:: ring
 844
 845         RingVM_HideErrorMsg(lStatus)
 846
 847 .. index::
 848         pair: 低水準関数; ringvm_callfunc()
 849
 850 ringvm_callfunc() 関数
 851 ======================
 852
 853 eval() 関数ではなく ringvm_callfunc() 関数を使うと、
 854 文字列から関数を呼び出します。
 855
 856 文法:
 857
 858 .. code-block:: ring
 859
 860         RingVM_CallFunc(cFuncName)
 861
 862
 863 .. index::
 864         pair: 低水準関数; 用例 - トレース関数の用法
 865
 866 用例 - トレース関数の用法
 867 =============================
 868
 869 この用例では、プログラムのイベントをトレースするためにトレース関数を使用しています！
 870
 871 トレースライブラリは低水準関数よりも実用的です！
 872
 873 .. code-block:: ring
 874
 875         load "tracelib.ring"
 876
 877         ringvm_settrace("mytrace()")
 878
 879         see "Hello, world!" + nl
 880         see "Welcome" + nl
 881         see "How are you?" +nl
 882         mytest()
 883         new myclass { mymethod() }
 884
 885         func mytest
 886                 see "Message from mytest" + nl
 887
 888         func mytrace
 889                 see "====== The Trace function is Active ======" + nl +
 890                         "Trace Function Name : " + ringvm_TraceFunc() + nl +
 891                         "Trace Event : "
 892                 switch ringvm_TraceEvent()
 893                         on TRACEEVENT_NEWLINE           see "New Line"
 894                         on TRACEEVENT_NEWFUNC           see "New Function"
 895                         on TRACEEVENT_RETURN            see "Return"
 896                         on TRACEEVENT_ERROR             see "Error"
 897                         on TRACEEVENT_BEFORECFUNC       see "Before C Function"
 898                         on TRACEEVENT_AFTERCFUNC        see "After C Function"
 899                 off
 900                 see nl +
 901                         "Line Number : " + ringvm_tracedata()[TRACEDATA_LINENUMBER] + nl +
 902                         "File Name   : " + ringvm_tracedata()[TRACEDATA_FILENAME] + nl +
 903                         "Function Name : " + ringvm_tracedata()[TRACEDATA_FUNCNAME] + nl +
 904                         "Method or Function : "
 905                         if ringvm_tracedata()[TRACEDATA_METHODORFUNC] =
 906                                          TRACEDATA_METHODORFUNC_METHOD
 907                                 see "Method"
 908                         else
 909                                 if ringvm_tracedata()[TRACEDATA_FUNCNAME] = NULL
 910                                         see "Command"
 911                                 else
 912                                         see "Function"
 913                                 ok
 914                         ok
 915                         see nl + Copy("=",42) + nl
 916
 917         class myclass
 918                 func mymethod
 919                         see "Message from mymethod" + nl
 920
 921 実行結果:
 922
 923 .. code-block:: none
 924
 925         ====== The Trace function is Active ======
 926         Trace Function Name : mytrace()
 927         Trace Event : After C Function
 928         Line Number : 3
 929         File Name   : test1.ring
 930         Function Name : ringvm_settrace
 931         Method or Function : Function
 932         ==========================================
 933         ====== The Trace function is Active ======
 934         Trace Function Name : mytrace()
 935         Trace Event : New Line
 936         Line Number : 5
 937         File Name   : test1.ring
 938         Function Name :
 939         Method or Function : Command
 940         ==========================================
 941         Hello, world!
 942         ====== The Trace function is Active ======
 943         Trace Function Name : mytrace()
 944         Trace Event : New Line
 945         Line Number : 6
 946         File Name   : test1.ring
 947         Function Name :
 948         Method or Function : Command
 949         ==========================================
 950         Welcome
 951         ====== The Trace function is Active ======
 952         Trace Function Name : mytrace()
 953         Trace Event : New Line
 954         Line Number : 7
 955         File Name   : test1.ring
 956         Function Name :
 957         Method or Function : Command
 958         ==========================================
 959         How are you?
 960         ====== The Trace function is Active ======
 961         Trace Function Name : mytrace()
 962         Trace Event : New Line
 963         Line Number : 8
 964         File Name   : test1.ring
 965         Function Name :
 966         Method or Function : Command
 967         ==========================================
 968         ====== The Trace function is Active ======
 969         Trace Function Name : mytrace()
 970         Trace Event : New Function
 971         Line Number : 8
 972         File Name   : test1.ring
 973         Function Name : mytest
 974         Method or Function : Function
 975         ==========================================
 976         ====== The Trace function is Active ======
 977         Trace Function Name : mytrace()
 978         Trace Event : New Line
 979         Line Number : 12
 980         File Name   : test1.ring
 981         Function Name : mytest
 982         Method or Function : Function
 983         ==========================================
 984         Message from mytest
 985         ====== The Trace function is Active ======
 986         Trace Function Name : mytrace()
 987         Trace Event : New Line
 988         Line Number : 14
 989         File Name   : test1.ring
 990         Function Name : mytest
 991         Method or Function : Function
 992         ==========================================
 993         ====== The Trace function is Active ======
 994         Trace Function Name : mytrace()
 995         Trace Event : Return
 996         Line Number : 8
 997         File Name   : test1.ring
 998         Function Name :
 999         Method or Function : Command
1000         ==========================================
1001         ====== The Trace function is Active ======
1002         Trace Function Name : mytrace()
1003         Trace Event : New Line
1004         Line Number : 9
1005         File Name   : test1.ring
1006         Function Name :
1007         Method or Function : Command
1008         ==========================================
1009         ====== The Trace function is Active ======
1010         Trace Function Name : mytrace()
1011         Trace Event : New Line
1012         Line Number : 43
1013         File Name   : test1.ring
1014         Function Name :
1015         Method or Function : Command
1016         ==========================================
1017         ====== The Trace function is Active ======
1018         Trace Function Name : mytrace()
1019         Trace Event : Before C Function
1020         Line Number : 9
1021         File Name   : test1.ring
1022         Function Name : ismethod
1023         Method or Function : Function
1024         ==========================================
1025         ====== The Trace function is Active ======
1026         Trace Function Name : mytrace()
1027         Trace Event : After C Function
1028         Line Number : 9
1029         File Name   : test1.ring
1030         Function Name : ismethod
1031         Method or Function : Function
1032         ==========================================
1033         ====== The Trace function is Active ======
1034         Trace Function Name : mytrace()
1035         Trace Event : New Function
1036         Line Number : 9
1037         File Name   : test1.ring
1038         Function Name : mymethod
1039         Method or Function : Method
1040         ==========================================
1041         ====== The Trace function is Active ======
1042         Trace Function Name : mytrace()
1043         Trace Event : New Line
1044         Line Number : 44
1045         File Name   : test1.ring
1046         Function Name : mymethod
1047         Method or Function : Method
1048         ==========================================
1049         Message from mymethod
1050         ====== The Trace function is Active ======
1051         Trace Function Name : mytrace()
1052         Trace Event : Return
1053         Line Number : 9
1054         File Name   : test1.ring
1055         Function Name :
1056         Method or Function : Command
1057         ==========================================
1058         ====== The Trace function is Active ======
1059         Trace Function Name : mytrace()
1060         Trace Event : Before C Function
1061         Line Number : 9
1062         File Name   : test1.ring
1063         Function Name : ismethod
1064         Method or Function : Function
1065         ==========================================
1066         ====== The Trace function is Active ======
1067         Trace Function Name : mytrace()
1068         Trace Event : After C Function
1069         Line Number : 9
1070         File Name   : test1.ring
1071         Function Name : ismethod
1072         Method or Function : Function
1073         ==========================================
1074         ====== The Trace function is Active ======
1075         Trace Function Name : mytrace()
1076         Trace Event : Before C Function
1077         Line Number : 9
1078         File Name   : test1.ring
1079         Function Name : ismethod
1080         Method or Function : Function
1081         ==========================================
1082         ====== The Trace function is Active ======
1083         Trace Function Name : mytrace()
1084         Trace Event : After C Function
1085         Line Number : 9
1086         File Name   : test1.ring
1087         Function Name : ismethod
1088         Method or Function : Function
1089         ==========================================
1090         ====== The Trace function is Active ======
1091         Trace Function Name : mytrace()
1092         Trace Event : New Line
1093         Line Number : 11
1094         File Name   : test1.ring
1095         Function Name :
1096         Method or Function : Command
1097         ==========================================
1098
1099
1100 .. index::
1101         pair: 低水準関数; 用例 - トレースライブラリ
1102
1103 用例 - トレースライブラリ
1104 ===========================
1105
1106 この用例では、トレースライブラリ作成用のトレース関数を使用します。
1107
1108 トレースライブラリにより、
1109 すばらしいトレースツールとインタラクティブデバッガを利用できます。
1110
1111 .. code-block:: ring
1112
1113         # イベントのトレース
1114         TRACEEVENT_NEWLINE      = 1
1115         TRACEEVENT_NEWFUNC      = 2
1116         TRACEEVENT_RETURN       = 3
1117         TRACEEVENT_ERROR        = 4
1118         TRACEEVENT_BEFORECFUNC  = 5
1119         TRACEEVENT_AFTERCFUNC   = 6
1120
1121         # データのトレース
1122         TRACEDATA_LINENUMBER    = 1
1123         TRACEDATA_FILENAME      = 2
1124         TRACEDATA_FUNCNAME      = 3
1125         TRACEDATA_METHODORFUNC  = 4
1126
1127         # 関数のメソッド
1128         TRACEDATA_METHODORFUNC_METHOD           = TRUE
1129         TRACEDATA_METHODORFUNC_NOTMETHOD        = FALSE
1130
1131         TRACE_BREAKPOINTS = TRUE
1132
1133         TRACE_TEMPLIST = []
1134
1135         func Trace cType
1136                 switch trim(lower(cType))
1137                 on :AllEvents
1138                         ringvm_settrace("TraceLib_AllEvents()")
1139                 on :Functions
1140                         ringvm_settrace("TraceLib_Functions()")
1141                 on :PassError
1142                         ringvm_settrace("TraceLib_PassError()")
1143                 on :Debugger
1144                         ringvm_settrace("TraceLib_Debugger()")
1145                 on :LineByLine
1146                         ringvm_settrace("TraceLib_LineByLine()")
1147                 off
1148
1149         func TraceLib_AllEvents
1150                 if right(ringvm_tracedata()[TRACEDATA_FILENAME],13) = "tracelib.ring"
1151                         return
1152                 ok
1153                 see "====== The Trace function is Active ======" + nl +
1154                         "Trace Function Name : " + ringvm_TraceFunc() + nl +
1155                         "Trace Event : "
1156                 switch ringvm_TraceEvent()
1157                         on TRACEEVENT_NEWLINE           see "New Line"
1158                         on TRACEEVENT_NEWFUNC           see "New Function"
1159                         on TRACEEVENT_RETURN            see "Return"
1160                         on TRACEEVENT_ERROR             see "Error"
1161                         on TRACEEVENT_BEFORECFUNC       see "Before C Function"
1162                         on TRACEEVENT_AFTERCFUNC        see "After C Function"
1163                 off
1164                 see nl +
1165                         "Line Number : " + ringvm_tracedata()[TRACEDATA_LINENUMBER] + nl +
1166                         "File Name   : " + ringvm_tracedata()[TRACEDATA_FILENAME] + nl +
1167                         "Function Name : " + ringvm_tracedata()[TRACEDATA_FUNCNAME] + nl +
1168                         "Method or Function : "
1169                         if ringvm_tracedata()[TRACEDATA_METHODORFUNC] =
1170                                          TRACEDATA_METHODORFUNC_METHOD
1171                                 see "Method"
1172                         else
1173                                 if ringvm_tracedata()[TRACEDATA_FUNCNAME] = NULL
1174                                         see "Command"
1175                                 else
1176                                         see "Function"
1177                                 ok
1178                         ok
1179                         see nl + Copy("=",42) + nl
1180
1181         func TraceLib_Functions
1182                 if right(ringvm_tracedata()[TRACEDATA_FILENAME],13) = "tracelib.ring"
1183                         return
1184                 ok
1185                 switch ringvm_TraceEvent()
1186                         on TRACEEVENT_NEWFUNC
1187                                 see "Open Func : " +
1188                                 ringvm_TraceData()[TRACEDATA_FUNCNAME] + nl
1189                         on TRACEEVENT_RETURN
1190                                 see "Return to Func : " +
1191                                 ringvm_TraceData()[TRACEDATA_FUNCNAME] + nl
1192                 off
1193
1194         func TraceLib_PassError
1195                 if right(ringvm_tracedata()[TRACEDATA_FILENAME],13) = "tracelib.ring"
1196                         return
1197                 ok
1198                 switch ringvm_TraceEvent()
1199                         on  TRACEEVENT_ERROR
1200                                 see nl
1201                                 see "TraceLib : After Error !" + nl
1202                                 ringvm_passerror()
1203                 off
1204
1205         func TraceLib_Debugger
1206                 if right(ringvm_tracedata()[TRACEDATA_FILENAME],13) = "tracelib.ring"
1207                         return
1208                 ok
1209                 switch ringvm_TraceEvent()
1210                         on  TRACEEVENT_ERROR
1211                                 _BreakPoint()
1212                 off
1213
1214         func TraceLib_LineByLine
1215                 if right(ringvm_tracedata()[TRACEDATA_FILENAME],13) = "tracelib.ring" or
1216                         ringvm_TraceEvent() != TRACEEVENT_NEWLINE
1217                         return
1218                 ok
1219                 aList = ringvm_tracedata()
1220                 see "Before Line : " + aList[TRACEDATA_LINENUMBER] + nl
1221                 _BreakPoint()
1222
1223         func BreakPoint
1224                 if not TRACE_BREAKPOINTS
1225                         return
1226                 ok
1227                 _BreakPoint()
1228
1229         func _BreakPoint
1230                 see nl+nl+Copy("=",60) + nl +
1231                 Copy(" ",20)+"Interactive Debugger" + nl +
1232                 Copy("=",60) + nl +
1233                 "Command (Exit)        : End Program" + nl +
1234                 "Command (Cont)        : Continue Execution" + nl +
1235                 "Command (Locals)      : Print local variables names" + nl +
1236                 "Command (LocalsData)  : Print local variables data" + nl +
1237                 "Command (Globals)     : Print global variables names" + nl +
1238                 "We can execute Ring code" + nl +
1239                 Copy("=",60) + nl
1240                 while true
1241                                 see nl + "code:> "
1242                                 give cCode
1243                         cmd = trim(lower(cCode))
1244                         if cmd = "exit" or cmd = "bye"
1245                                 shutdown()
1246                         ok
1247                         nScope = ringvm_scopescount()-2
1248                         switch cmd
1249                                 on "locals"
1250                                         ringvm_EvalInScope(nScope,"see locals() callgc()")
1251                                         loop
1252                                 on "localsdata"
1253                                         PrintLocalsData(nScope)
1254                                         loop
1255                                 on "globals"
1256                                         ringvm_EvalInScope(nScope,"see globals() callgc()")
1257                                         loop
1258                                 on "cont"
1259                                         ringvm_passerror()
1260                                         exit
1261                         off
1262                         Try
1263                                 ringvm_EvalInScope(nScope,cCode)
1264                                 catch
1265                                                 see cCatchError
1266                                 done
1267                 end
1268
1269         func NoBreakPoints
1270                 TRACE_BREAKPOINTS = FALSE
1271
1272
1273         func PrintLocalsData nScope
1274                 if nScope = 1   # グローバル
1275                         ringvm_Evalinscope(nScope,'TRACE_TEMPLIST = globals()')
1276                 else
1277                         ringvm_Evalinscope(nScope,'TRACE_TEMPLIST = locals() callgc()')
1278                 ok
1279                 see nl
1280                 aTempList = TRACE_TEMPLIST
1281                 TRACE_TEMPLIST = []
1282                 nSpaces = 5
1283                 for TRACE_ITEM in aTempList
1284                         if len(TRACE_ITEM) + 5 > nSpaces
1285                                 nSpaces = len(TRACE_ITEM) + 5
1286                         ok
1287                 next
1288                 for TRACE_ITEM in aTempList
1289                         see "Variable : " +  TRACE_ITEM
1290                         cVarName = TRACE_ITEM
1291                         see copy(" ",nSpaces-len(cVarName)) + " Type : "
1292                         ringvm_Evalinscope(nScope,"see type(" +  TRACE_ITEM +")")
1293                         ringvm_Evalinscope(nScope,"see Copy(' ',fabs(15-len(type(" +
1294                                                   TRACE_ITEM +"))))")
1295                         see " Value : "
1296                         ringvm_Evalinscope(nScope,"see " +  TRACE_ITEM)
1297                         see nl
1298                 next
1299
1300
1301 .. index::
1302         pair: 低水準関数; ringvm_see()
1303
1304 ringvm_see() 関数
1305 =================
1306
1307 ringvm_see() 関数は See 命令の挙動を変更します。
1308
1309 また ring_see() 関数は元の挙動を使用します。
1310
1311 用例:
1312
1313 .. code-block:: ring
1314
1315         see "Hello world" + nl
1316         see 123 + nl
1317         see ["one","two","three"]
1318         see new point {x=10 y=20 z=30}
1319
1320         func ringvm_see t
1321                 ring_see("We want to print: ")
1322                 ring_See(t)
1323
1324         class point x y z
1325
1326 実行結果:
1327
1328 .. code-block:: none
1329
1330         We want to print: Hello world
1331         We want to print: 123
1332         We want to print: one
1333         two
1334         three
1335         We want to print: x: 10.000000
1336         y: 20.000000
1337         z: 30.000000
1338
1339 .. index::
1340         pair: 低水準関数; ringvm_give()
1341
1342 ringvm_give() 関数
1343 ==================
1344
1345 ringvm_give() 関数は Give 命令の挙動を変更します。
1346
1347 また ring_give() 関数は元の挙動を使用します。
1348
1349 用例:
1350
1351 .. code-block:: ring
1352
1353         see "Name: " give name
1354         see "Hello " + name
1355
1356         func ringvm_give
1357                 see "Mahmoud" + nl
1358                 return "Mahmoud"
1359
1360 実行結果:
1361
1362 .. code-block:: ring
1363
1364         Name: Mahmoud
1365         Hello Mahmoud
1366
1367 .. index::
1368         pair: 低水準関数; ringvm_info()
1369
1370 ringvm_info() 関数
1371 ==================
1372
1373 ringvm_info () は Ring VM 構造体に関する情報をリストとして返す内部関数です。
1374
1375 この関数は Ring チームが VM の状態を調査するための高度な検証に限り使用されています。
1376
1377 文法:
1378
1379 .. code-block:: ring
1380
1381         ringvm_info() ---> VM 構造体に関する情報のリスト
1382