types.go 4.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199
  1. /*
  2. * ECAL
  3. *
  4. * Copyright 2020 Matthias Ladkau. All rights reserved.
  5. *
  6. * This Source Code Form is subject to the terms of the MIT
  7. * License, If a copy of the MIT License was not distributed with this
  8. * file, You can obtain one at https://opensource.org/licenses/MIT.
  9. */
  10. package util
  11. import (
  12. "time"
  13. "devt.de/krotik/ecal/parser"
  14. )
  15. /*
  16. Processor models a top level execution instance for ECAL.
  17. */
  18. type Processor interface {
  19. }
  20. /*
  21. ECALImportLocator is used to resolve imports.
  22. */
  23. type ECALImportLocator interface {
  24. /*
  25. Resolve a given import path and parse the imported file into an AST.
  26. */
  27. Resolve(path string) (string, error)
  28. }
  29. /*
  30. ECALFunction models a callable function in ECAL.
  31. */
  32. type ECALFunction interface {
  33. /*
  34. Run executes this function. The envirnment provides a unique instanceID for
  35. every code location in the running code, the variable scope of the function,
  36. an instance state which can be used in combinartion with the instanceID
  37. to store instance specific state (e.g. for iterator functions) and a list
  38. of argument values which were passed to the function by the calling code.
  39. */
  40. Run(instanceID string, vs parser.Scope, is map[string]interface{}, tid uint64, args []interface{}) (interface{}, error)
  41. /*
  42. DocString returns a descriptive text about this function.
  43. */
  44. DocString() (string, error)
  45. }
  46. /*
  47. Logger is required external object to which the interpreter releases its log messages.
  48. */
  49. type Logger interface {
  50. /*
  51. LogError adds a new error log message.
  52. */
  53. LogError(v ...interface{})
  54. /*
  55. LogInfo adds a new info log message.
  56. */
  57. LogInfo(v ...interface{})
  58. /*
  59. LogDebug adds a new debug log message.
  60. */
  61. LogDebug(v ...interface{})
  62. }
  63. /*
  64. ContType represents a way how to resume code execution of a suspended thread.
  65. */
  66. type ContType int
  67. /*
  68. Available lexer token types
  69. */
  70. const (
  71. Resume ContType = iota // Resume code execution until the next breakpoint or the end
  72. StepIn // Step into a function call or over the next non-function call
  73. StepOver // Step over the current statement onto the next line
  74. StepOut // Step out of the current function call
  75. )
  76. /*
  77. ECALDebugger is a debugging object which can be used to inspect and modify a running
  78. ECAL environment.
  79. */
  80. type ECALDebugger interface {
  81. /*
  82. HandleInput handles a given debug instruction. It must be possible to
  83. convert the output data into a JSON string.
  84. */
  85. HandleInput(input string) (interface{}, error)
  86. /*
  87. StopThreads will continue all suspended threads and set them to be killed.
  88. Returns true if a waiting thread was resumed. Can wait for threads to end
  89. by ensuring that for at least d time no state change occured.
  90. */
  91. StopThreads(d time.Duration) bool
  92. /*
  93. BreakOnStart breaks on the start of the next execution.
  94. */
  95. BreakOnStart(flag bool)
  96. /*
  97. BreakOnError breaks if an error occurs.
  98. */
  99. BreakOnError(flag bool)
  100. /*
  101. VisitState is called for every state during the execution of a program.
  102. */
  103. VisitState(node *parser.ASTNode, vs parser.Scope, tid uint64) TraceableRuntimeError
  104. /*
  105. VisitStepInState is called before entering a function call.
  106. */
  107. VisitStepInState(node *parser.ASTNode, vs parser.Scope, tid uint64) TraceableRuntimeError
  108. /*
  109. VisitStepOutState is called after returning from a function call.
  110. */
  111. VisitStepOutState(node *parser.ASTNode, vs parser.Scope, tid uint64, soErr error) TraceableRuntimeError
  112. /*
  113. RecordThreadFinished lets the debugger know that a thread has finished.
  114. */
  115. RecordThreadFinished(tid uint64)
  116. /*
  117. SetBreakPoint sets a break point.
  118. */
  119. SetBreakPoint(source string, line int)
  120. /*
  121. DisableBreakPoint disables a break point but keeps the code reference.
  122. */
  123. DisableBreakPoint(source string, line int)
  124. /*
  125. RemoveBreakPoint removes a break point.
  126. */
  127. RemoveBreakPoint(source string, line int)
  128. /*
  129. ExtractValue copies a value from a suspended thread into the
  130. global variable scope.
  131. */
  132. ExtractValue(threadId uint64, varName string, destVarName string) error
  133. /*
  134. InjectValue copies a value from an expression (using the global
  135. variable scope) into a suspended thread.
  136. */
  137. InjectValue(threadId uint64, varName string, expression string) error
  138. /*
  139. Continue will continue a suspended thread.
  140. */
  141. Continue(threadId uint64, contType ContType)
  142. /*
  143. Status returns the current status of the debugger.
  144. */
  145. Status() interface{}
  146. /*
  147. Describe decribes a thread currently observed by the debugger.
  148. */
  149. Describe(threadId uint64) interface{}
  150. }
  151. /*
  152. DebugCommand is command which can modify and interrogate the debugger.
  153. */
  154. type DebugCommand interface {
  155. /*
  156. Execute the debug command and return its result. It must be possible to
  157. convert the output data into a JSON string.
  158. */
  159. Run(debugger ECALDebugger, args []string) (interface{}, error)
  160. /*
  161. DocString returns a descriptive text about this command.
  162. */
  163. DocString() string
  164. }