1	#Region "Microsoft.VisualBasic::04369fce4edad7572df6e2634f9e59eb, Microsoft.VisualBasic.Core\ApplicationServices\Debugger.vb"
2
3	' Author:
4	'
5	'       asuka (amethyst.asuka@gcmodeller.org)
6	'       xie (genetics@smrucc.org)
7	'       xieguigang (xie.guigang@live.com)
8	'
9	' Copyright (c) 2018 GPL3 Licensed
10	'
11	'
12	' GNU GENERAL PUBLIC LICENSE (GPL3)
13	'
14	'
15	' This program is free software: you can redistribute it and/or modify
16	' it under the terms of the GNU General Public License as published by
17	' the Free Software Foundation, either version 3 of the License, or
18	' (at your option) any later version.
19	'
20	' This program is distributed in the hope that it will be useful,
21	' but WITHOUT ANY WARRANTY; without even the implied warranty of
22	' MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
23	' GNU General Public License for more details.
24	'
25	' You should have received a copy of the GNU General Public License
26	' along with this program. If not, see <http://www.gnu.org/licenses/>.
27
28
29
30	' /********************************************************************************/
31
32	' Summaries:
33
34	' Module VBDebugger
35	'
36	'     Function: die, LinqProc
37	'     Delegate Sub
38	'
39	'         Properties: ForceSTDError, Mute, UsingxConsole
40	'
41	'         Function: __DEBUG_ECHO, Assert, BENCHMARK, (+2 Overloads) PrintException, this
42	'                   Warning
43	'
44	'         Sub: (+2 Overloads) __DEBUG_ECHO, __INFO_ECHO, (+3 Overloads) Assertion, AttachLoggingDriver, cat
45	'              (+3 Overloads) Echo, EchoLine, WaitOutput, WriteLine
46	'
47	'
48	'
49	' /********************************************************************************/
50
51	#End Region
52
53	Imports System.Reflection
54	Imports System.Runtime.CompilerServices
55	Imports System.Text
56	Imports Microsoft.VisualBasic.ApplicationServices
57	Imports Microsoft.VisualBasic.ApplicationServices.Debugging
58	Imports Microsoft.VisualBasic.ApplicationServices.Debugging.Logging
59	Imports Microsoft.VisualBasic.Language
60	Imports Microsoft.VisualBasic.Language.C
61	Imports Microsoft.VisualBasic.Language.Default
62	Imports Microsoft.VisualBasic.Language.Perl
63	Imports Microsoft.VisualBasic.Linq.Extensions
64	Imports Microsoft.VisualBasic.Scripting.Runtime
65	Imports Microsoft.VisualBasic.Terminal
66	Imports Microsoft.VisualBasic.Terminal.Utility
67
68	''' <summary>
69	''' Debugger helper module for VisualBasic Enterprises System.
70	''' </summary>
71	Public Module VBDebugger
72
73	''' <summary>
74	''' Assert that the expression value is correctly or not?
75	''' </summary>
76	''' <param name="message$">The exception message</param>
77	''' <param name="failure">If this expression test is True, then die expression will raise an exception</param>
78	''' <returns></returns>
79	'''
80	<MethodImpl(MethodImplOptions.AggressiveInlining)>
81	Public Function die(message$, Optional failure As Assert(Of Object) = Nothing, <CallerMemberName> Optional caller$ = Nothing) As ExceptionHandle
82	Return New ExceptionHandle With {
83	.Message = message,
84	.failure = failure Or defaultAssert
85	}
86	End Function
87
88	''' <summary>
89	''' 当在执行大型的数据集合的时候怀疑linq里面的某一个任务进入了死循环状态，可以使用这个方法来检查是否如此
90	''' </summary>
91	''' <typeparam name="T"></typeparam>
92	''' <param name="source"></param>
93	''' <param name="tag"></param>
94	''' <returns></returns>
95	'''
96	<MethodImpl(MethodImplOptions.AggressiveInlining)>
97	<Extension> Public Function LinqProc(Of T)(source As IEnumerable(Of T), <CallerMemberName> Optional tag$ = Nothing) As EventProc
98	Return New EventProc(source.Count, tag)
99	End Function
100
101	''' <summary>
102	''' 当前的调试器的信息输出登记，默认是输出所有的信息
103	''' </summary>
104	Friend m_level As DebuggerLevels = DebuggerLevels.On
105	''' <summary>
106	''' 是否静默掉所有的调试器输出信息？默认不是
107	''' </summary>
108	Friend m_mute As Boolean = False
109
110	''' <summary>
111	''' 对外部开放的调试日志的获取接口类型的申明
112	''' </summary>
113	''' <param name="header">消息的类型的头部标签</param>
114	''' <param name="message">消息文本内容，一般为一行文本</param>
115	''' <param name="level">日志消息的错误等级</param>
116	Public Delegate Sub LoggingDriver(header$, message$, level As MSG_TYPES)
117
118	''' <summary>
119	''' Disable the debugger information outputs on the console if this <see cref="Mute"/> property is set to
120	''' <see cref="Boolean.True"/>, and enable the output if this property is set to <see cref="Boolean.False"/>.
121	''' NOTE: this debugger option property can be overrides by the debugger parameter from the CLI parameter
122	''' named ``--echo``
123	''' </summary>
124	''' <returns></returns>
125	Public Property Mute As Boolean
126	Get
127	Return m_mute
128	End Get
129	Set(value As Boolean)
130	' off的时候，不会输出任何信息
131	If m_level = DebuggerLevels.Off Then
132	m_mute = True
133	Else
134	m_mute = value
135	End If
136	End Set
137	End Property
138
139	''' <summary>
140	''' Force the app debugging output redirect into the std_error device.
141	''' </summary>
142	''' <returns></returns>
143	Public Property ForceSTDError As Boolean = False
144
145	''' <summary>
146	''' Test how long this <paramref name="test"/> will takes.
147	''' </summary>
148	''' <param name="test"></param>
149	''' <param name="trace$"></param>
150	''' <returns></returns>
151	<Extension>
152	Public Function BENCHMARK(test As Action, <CallerMemberName> Optional trace$ = Nothing) As Long
153	Dim start = Now.ToLongTimeString
154	Dim ms& = Utils.Time(test)
155	Dim end$ = Now.ToLongTimeString
156
157	If Not Mute AndAlso m_level < DebuggerLevels.Warning Then
158	Dim head$ = $"Benchmark `{ms.FormatTicks}` {start} - {[end]}"
159	Dim str$ = " " & $"{trace} -> {CStrSafe(test.Target, "null")}::{test.Method.Name}"
160
161	Call My.Log4VB.Print(head, str, ConsoleColor.Magenta, ConsoleColor.Magenta)
162	End If
163
164	Return ms
165	End Function
166
167	''' <summary>
168	''' Output the full debug information while the project is debugging in debug mode.
169	''' (向标准终端和调试终端输出一些带有时间戳的调试信息)
170	''' </summary>
171	''' <param name="msg">The message fro output to the debugger console, this function will add a time stamp automaticly To the leading position Of the message.</param>
172	''' <param name="indent"></param>
173	''' <returns>其实这个函数是不会返回任何东西的，只是因为为了Linq调试输出的需要，所以在这里是返回Nothing的</returns>
174	<Extension> Public Function __DEBUG_ECHO(msg$, Optional indent% = 0, Optional mute As Boolean = False) As String
175	Static indents$() = {"",
176	New String(" ", 1), New String(" ", 2), New String(" ", 3), New String(" ", 4),
177	New String(" ", 5), New String(" ", 6), New String(" ", 7), New String(" ", 8),
178	New String(" ", 9), New String(" ", 10)
179	}
180
181	If Not mute AndAlso Not VBDebugger.Mute AndAlso m_level < DebuggerLevels.Warning Then
182	Dim head As String = $"DEBUG {Now.ToString}"
183	Dim str As String = $"{indents(indent)} {msg}"
184
185	Call My.Log4VB.Print(head, str, ConsoleColor.White, MSG_TYPES.DEBUG)
186
187	#If DEBUG Then
188	Call Debug.WriteLine($"[{head}]{str}")
189	#End If
190	End If
191
192	Return Nothing
193	End Function
194
195	<Extension> Public Sub __INFO_ECHO(msg$)
196	If Not Mute AndAlso m_level < DebuggerLevels.Warning Then
197	Dim head As String = $"INFOM {Now.ToString}"
198	Dim str As String = " " & msg
199
200	Call My.Log4VB.Print(head, str, ConsoleColor.White, MSG_TYPES.INF)
201
202	#If DEBUG Then
203	Call Debug.WriteLine($"[{head}]{str}")
204	#End If
205	End If
206	End Sub
207
208	<MethodImpl(MethodImplOptions.AggressiveInlining)>
209	Public Sub AttachLoggingDriver(driver As LoggingDriver)
210	My.Log4VB.logs.Add(driver)
211	End Sub
212
213	''' <summary>
214	''' The function will print the exception details information on the standard <see cref="console"/>, <see cref="debug"/> console, and system <see cref="trace"/> console.
215	''' (分别在标准终端，调试终端，系统调试终端之中打印出错误信息，请注意，函数会直接返回False可以用于指定调用者函数的执行状态，这个函数仅仅是在终端上面打印出错误，不会保存为日志文件)
216	''' </summary>
217	''' <typeparam name="ex"></typeparam>
218	''' <param name="exception"></param>
219	'''
220	<MethodImpl(MethodImplOptions.AggressiveInlining)>
221	<Extension> Public Function PrintException(Of ex As Exception)(exception As ex, <CallerMemberName> Optional memberName$ = "") As Boolean
222	Return New Exception(memberName, exception).ToString.PrintException(memberName)
223	End Function
224
225	''' <summary>
226	''' 可以使用这个方法<see cref="MethodBase.GetCurrentMethod"/>.<see cref="GetFullName"/>获取得到<paramref name="memberName"/>所需要的参数信息
227	''' </summary>
228	''' <param name="msg"></param>
229	''' <param name="memberName"></param>
230	''' <returns></returns>
231	'''
232	<MethodImpl(MethodImplOptions.AggressiveInlining)>
233	<Extension>
234	Public Function PrintException(msg$, <CallerMemberName> Optional memberName$ = "") As Boolean
235	Return My.Log4VB.Print($"ERROR {Now.ToString}", $"<{memberName}>::{msg}", ConsoleColor.Red, MSG_TYPES.ERR)
236	End Function
237
238	''' <summary>
239	''' 等待调试器输出工作线程将内部的消息队列输出完毕
240	''' </summary>
241	Public Sub WaitOutput()
242	Call My.InnerQueue.WaitQueue()
243	End Sub
244
245	''' <summary>
246	''' 使用<see cref="xConsole"/>输出消息
247	''' </summary>
248	''' <returns></returns>
249	Public Property UsingxConsole As Boolean = False
250
251	''' <summary>
252	''' 输出的终端消息带有指定的终端颜色色彩，当<see cref="UsingxConsole"/>为True的时候，
253	''' <paramref name="msg"/>参数之中的文本字符串兼容<see cref="xConsole"/>语法，
254	''' 而<paramref name="color"/>将会被<see cref="xConsole"/>覆盖而不会起作用
255	''' </summary>
256	''' <param name="msg">兼容<see cref="xConsole"/>语法</param>
257	''' <param name="color">当<see cref="UsingxConsole"/>参数为True的时候，这个函数参数将不会起作用</param>
258	'''
259	<MethodImpl(MethodImplOptions.AggressiveInlining)>
260	<Extension>
261	Public Sub WriteLine(msg$, color As ConsoleColor)
262	My.Log4VB.WriteLine(msg, color)
263	End Sub
264
265	''' <summary>
266	''' Display the wraning level(YELLOW color) message on the console.
267	''' </summary>
268	''' <param name="msg"></param>
269	''' <param name="calls"></param>
270	''' <returns></returns>
271	<Extension>
272	Public Function Warning(msg As String, <CallerMemberName> Optional calls As String = "") As String
273	If Not Mute Then
274	Dim head As String = $"WARNG <{calls}> {Now.ToString}"
275
276	Call My.Log4VB.Print(head, " " & msg, ConsoleColor.Yellow, MSG_TYPES.DEBUG)
277	#If DEBUG Then
278	Call Debug.WriteLine($"[{head}]{msg}")
279	#End If
280	End If
281
282	Return Nothing
283	End Function
284
285	''' <summary>
286	''' If <paramref name="test"/> boolean value is False, then the assertion test failure. If the test is failure the specific message will be output on the console.
287	''' </summary>
288	''' <param name="test"></param>
289	''' <param name="fails"></param>
290	''' <param name="level"></param>
291	''' <param name="calls"></param>
292	<Extension>
293	Public Sub Assertion(test As Boolean, fails As String, level As MSG_TYPES, <CallerMemberName> Optional calls As String = "")
294	If Not test = True Then
295	If level = MSG_TYPES.DEBUG Then
296	If m_level < DebuggerLevels.Warning Then
297	Call fails.__DEBUG_ECHO(memberName:=calls)
298	End If
299	ElseIf level = MSG_TYPES.ERR Then
300	If m_level <> DebuggerLevels.Off Then
301	Call WriteLine(fails, ConsoleColor.Red)
302	End If
303	ElseIf level = MSG_TYPES.WRN Then
304	If m_level <> DebuggerLevels.Error Then
305	Call Warning(fails, calls)
306	End If
307	Else
308	If m_level < DebuggerLevels.Warning Then
309	Call Console.WriteLine($"@{calls}::" & fails)
310	End If
311	End If
312	End If
313	End Sub
314
315	''' <summary>
316	''' If the <paramref name="test"/> message is not null or empty string, then the console will output the message.
317	''' </summary>
318	''' <param name="test"></param>
319	''' <param name="level"></param>
320	''' <param name="calls"></param>
321	<Extension>
322	Public Sub Assertion(test As String, level As MSG_TYPES, <CallerMemberName> Optional calls As String = "")
323	Call VBDebugger.Assertion((String.IsNullOrEmpty(test) OrElse String.IsNullOrWhiteSpace(test)), test, level, calls)
324	End Sub
325
326	''' <summary>
327	''' Use an assert statement to disrupt normal execution if a boolean condition is false.
328	''' If <paramref name="test"/> is false(means this assertion test failure), then throw exception.
329	''' </summary>
330	''' <param name="test"></param>
331	''' <param name="msg"></param>
332	Public Sub Assertion(test As Boolean, msg As String, <CallerMemberName> Optional calls As String = "")
333	Dim null = test Or die(message:=msg, caller:=calls)
334	End Sub
335
336	Public Function Assert(test As Boolean,
337	failed$,
338	Optional success$ = Nothing,
339	Optional failedLevel As MSG_TYPES = MSG_TYPES.ERR,
340	<CallerMemberName> Optional calls As String = "") As Boolean
341	If test Then
342	If Not String.IsNullOrEmpty(success) Then
343	Call success.__DEBUG_ECHO
344	End If
345
346	Return True
347	Else
348	Select Case failedLevel
349	Case MSG_TYPES.DEBUG
350	Call failed.__DEBUG_ECHO
351	Case MSG_TYPES.ERR
352	Call failed.PrintException(calls)
353	Case MSG_TYPES.WRN
354	Call failed.Warning(calls)
355	Case Else
356	Call failed.Echo(calls)
357	End Select
358
359	Return False
360	End If
361	End Function
362
363	''' <summary>
364	''' Output the full debug information while the project is debugging in debug mode.
365	''' (向标准终端和调试终端输出一些带有时间戳的调试信息)
366	''' </summary>
367	''' <param name="MSG">The message fro output to the debugger console, this function will add a time stamp automaticly To the leading position Of the message.</param>
368	''' <param name="Indent"></param>
369	<MethodImpl(MethodImplOptions.AggressiveInlining)>
370	<Extension> Public Sub __DEBUG_ECHO(MSG As StringBuilder, Optional Indent As Integer = 0)
371	Call MSG.ToString.__DEBUG_ECHO(Indent)
372	End Sub
373
374	<Extension> Public Sub __DEBUG_ECHO(Of T)(value As T, <CallerMemberName> Optional memberName As String = "")
375	Call (Scripting.InputHandler.ToString(value) & "              @" & memberName).__DEBUG_ECHO
376	End Sub
377
378	''' <summary>
379	''' Returns the current function name.
380	''' </summary>
381	''' <param name="caller">
382	''' The caller function name, do not assign any value to this parameter! Just leave it blank.
383	''' </param>
384	''' <returns></returns>
385	Public Function this(<CallerMemberName> Optional caller As String = "") As String
386	Return caller
387	End Function
388
389	<Extension> Public Sub Echo(Of T)(array As IEnumerable(Of T), <CallerMemberName> Optional memberName As String = "")
390	Call String.Join(", ", array.Select(Function(obj) Scripting.ToString(obj)).ToArray).__DEBUG_ECHO
391	End Sub
392
393	<Extension> Public Sub Echo(lines As IEnumerable(Of String))
394	For Each line$ In lines
395	Call Console.WriteLine(line)
396	Next
397	End Sub
398
399	''' <summary>
400	''' Alias for <see cref="Console.WriteLine"/>
401	''' </summary>
402	''' <param name="s$"></param>
403	<Extension> Public Sub EchoLine(s$)
404	If Not Mute Then
405	Call My.InnerQueue.AddToQueue(
406	Sub()
407	Call Console.WriteLine(s)
408	End Sub)
409	End If
410	End Sub
411
412	''' <summary>
413	''' Alias for <see cref="Console.Write"/>
414	''' </summary>
415	''' <param name="c"></param>
416	<Extension> Public Sub Echo(c As Char)
417	If Not Mute Then
418	Call Console.Write(c)
419	End If
420	End Sub
421
422	''' <summary>
423	''' print message, alias for <see cref="Console.Write(String)"/>.(支持``sprintf``之中的转义字符)
424	''' </summary>
425	''' <param name="s$"></param>
426	Public Sub cat(s$)
427	If Not Mute Then
428	Call My.InnerQueue.AddToQueue(
429	Sub()
430	Call Console.Write(s.ReplaceMetaChars)
431	End Sub)
432	End If
433	End Sub
434	End Module