1	#Region "Microsoft.VisualBasic::53c50f4ab87cbef2763d7b567429a14d, Microsoft.VisualBasic.Core\CommandLine\Interpreters\View\SDKManual.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 SDKManual
35	'
36	'         Function: HelpSummary, LaunchManual, MarkdownDoc
37	'
38	'
39	' /********************************************************************************/
40
41	#End Region
42
43	Imports System.Runtime.CompilerServices
44	Imports System.Text
45	Imports Microsoft.VisualBasic.ApplicationServices.Debugging
46	Imports Microsoft.VisualBasic.ApplicationServices.Development
47	Imports Microsoft.VisualBasic.CommandLine.Grouping
48	Imports Microsoft.VisualBasic.CommandLine.Reflection
49	Imports Microsoft.VisualBasic.CommandLine.Reflection.EntryPoints
50	Imports Microsoft.VisualBasic.ComponentModel.DataSourceModel
51	Imports Microsoft.VisualBasic.Language
52	Imports Microsoft.VisualBasic.Linq
53	Imports Microsoft.VisualBasic.Scripting
54	Imports Microsoft.VisualBasic.Scripting.TokenIcer.Prefix
55	Imports Microsoft.VisualBasic.Terminal.Utility
56	Imports Microsoft.VisualBasic.Text
57	Imports VBCore = Microsoft.VisualBasic.App
58
59	Namespace CommandLine.ManView
60
61	''' <summary>
62	''' Generates the help document in markdown format.
63	''' (生成markdown格式的帮助文件)
64	''' </summary>
65	Module SDKManual
66
67	''' <summary>
68	''' 这个是用于在终端上面显示的无格式的文本输出
69	''' </summary>
70	''' <param name="CLI"></param>
71	''' <returns></returns>
72	<Extension>
73	Public Function LaunchManual(CLI As Interpreter) As Integer
74	Dim assm As AssemblyInfo = ApplicationInfoUtils.FromTypeModule(CLI.Type)
75	Dim title As String = $"{Application.ProductName} [version {Application.ProductVersion}]" & vbCrLf &
76	vbCrLf &
77	"## " & assm.AssemblyTitle & vbCrLf &
78	vbCrLf &
79	"Description: " & assm.AssemblyDescription & vbCrLf &
80	"Company:     " & assm.AssemblyCompany & vbCrLf &
81	assm.AssemblyCopyright  ' 首页
82
83	Dim sb As New StringBuilder
84
85	Call sb.AppendLine($"Module AssemblyName: {App.ExecutablePath.ToFileURL}")
86	Call sb.AppendLine($"Root namespace: " & CLI.ToString)
87	Call sb.AppendLine(vbCrLf & vbCrLf & CLI.HelpSummary(False))
88
89	Dim firstPage As String = sb.ToString
90	Dim pages As List(Of String) = {
91	DebuggerArgs.DebuggerHelps,
92	CLI.Type.NamespaceEntry.Description
93	}.AsList
94
95	pages += LinqAPI.Exec(Of String) <=
96	_
97	From api As SeqValue(Of APIEntryPoint)
98	In CLI.APIList.SeqIterator(offset:=1)
99	Let index As String = api.i & ".   "
100	Let info As String = api.value.HelpInformation
101	Select index & info
102
103	Call New IndexedManual(pages, title).ShowManual()
104
105	Return 0
106	End Function
107
108	''' <summary>
109	''' 这个是用于保存于文件之中的markdown格式的有格式标记的文本输出
110	''' </summary>
111	''' <returns></returns>
112	'''
113	<Extension>
114	Public Function MarkdownDoc(App As Interpreter) As String
115	Dim sb As New StringBuilder($"# { VisualBasic.App.ProductName} [version { VisualBasic.App.Version}]")
116	Dim type As Type = App.Type
117	Dim assm As AssemblyInfo = ApplicationInfoUtils.FromTypeModule(App.Type)
118
119	Call sb.AppendLine()
120	Call sb.AppendLine("> " & App.Type.NamespaceEntry.Description.LineTokens.JoinBy(vbCrLf & "> "))
121	Call sb.AppendLine()
122	Call sb.AppendLine("<!--more-->")
123	Call sb.AppendLine()
124	Call sb.AppendLine($"**{assm.AssemblyTitle}**<br/>")
125	Call sb.AppendLine($"_{assm.AssemblyDescription}_<br/>")
126	Call sb.AppendLine(assm.AssemblyCopyright)
127	Call sb.AppendLine()
128
129	Call sb.AppendLine($"**Module AssemblyName**: {type.Assembly.Location.BaseName}<br/>")
130	Call sb.AppendLine($"**Root namespace**: ``{App.Type.FullName}``<br/>")
131
132	Dim helps As ExceptionHelp = type.GetAttribute(Of ExceptionHelp)
133
134	If Not helps Is Nothing Then
135	Call sb.AppendLine()
136	Call sb.AppendLine("------------------------------------------------------------")
137	Call sb.AppendLine("If you are having trouble debugging this Error, first read the best practices tutorial for helpful tips that address many common problems:")
138	Call sb.AppendLine("> " & helps.Documentation)
139	Call sb.AppendLine()
140	Call sb.AppendLine()
141	Call sb.AppendLine("The debugging facility Is helpful To figure out what's happening under the hood:")
142	Call sb.AppendLine("> " & helps.Debugging)
143	Call sb.AppendLine()
144	Call sb.AppendLine()
145	Call sb.AppendLine("If you're still stumped, you can try get help from author directly from E-mail:")
146	Call sb.AppendLine("> " & helps.EMailLink)
147	Call sb.AppendLine()
148	End If
149
150	Call sb.AppendLine(vbCrLf & vbCrLf & App.HelpSummary(True))
151	Call sb.AppendLine()
152	Call sb.AppendLine("## CLI API list")
153	Call sb.AppendLine("--------------------------")
154
155	For Each i As SeqValue(Of APIEntryPoint) In App.APIList.SeqIterator
156	Dim api As APIEntryPoint = i.value
157
158	Call sb.Append($"<h3 id=""{api.Name}""> {i.i + 1}. ")
159	Call sb.AppendLine(api.HelpInformation(md:=True) _
160	.LineTokens _
161	.Select(Function(s) s.Trim) _
162	.JoinBy(vbCrLf))
163
164	If api.Arguments.Count > 0 Then
165	Dim prints = api.Arguments _
166	.Where(Function(x) Not x.Value.AcceptTypes.IsNullOrEmpty) _
167	.ToArray
168
169	If Not prints.Length = 0 Then
170	Call sb.AppendLine("##### Accepted Types")
171
172	For Each param As NamedValue(Of Argument) In prints
173	Call sb.AppendLine("###### " & param.Name)
174
175	For Each pType As Type In param.Value.AcceptTypes
176	Call sb.AppendLine(Activity.DisplayType(pType))
177	Next
178	Next
179	End If
180	End If
181	Next
182
183	Return sb.ToString
184	End Function
185
186	''' <summary>
187	''' Returns the summary brief help information of all of the commands in current cli interpreter.
188	''' (枚举出本CLI解释器之中的所有的命令的帮助的摘要信息)
189	''' </summary>
190	''' <returns></returns>
191	''' <remarks></remarks>
192	''' <param name="markdown">Output in markdown format?</param>
193	<Extension>
194	Public Function HelpSummary(App As Interpreter, markdown As Boolean) As String
195	Dim sb As New StringBuilder(1024)
196	Dim nameMaxLen% = App.APIList _
197	.Select(Function(x) Len(x.Name)) _
198	.Max
199
200	If Not markdown Then
201	Dim descr = VBCore.Info.AssemblyDescription
202
203	Call sb.AppendLine()
204
205	Call sb.AppendLine(" // ")
206	Call sb.AppendLine(" // " & Strings.Trim(descr))
207	Call sb.AppendLine(" // ")
208	Call sb.AppendLine(" // VERSION:   " & (VBCore.Info.AssemblyVersion Or "1.0.0.*".AsDefault))
209	Call sb.AppendLine(" // COPYRIGHT: " & VBCore.Info.AssemblyCopyright)
210	Call sb.AppendLine(" // GUID:      " & VBCore.Info.Guid)
211	Call sb.AppendLine(" // ")
212
213	Call sb.AppendLine()
214	Call sb.AppendLine()
215
216	For Each line$ In Paragraph.SplitParagraph(App.Info.Description, 110)
217	Call sb.AppendLine(" " & line$)
218	Next
219
220	Call sb.AppendLine()
221	Call sb.AppendLine()
222	Call sb.AppendLine("SYNOPSIS")
223	Call sb.AppendLine($"{VBCore.AssemblyName} command [/argument argument-value...] [/@set environment-variable=value...]")
224	Call sb.AppendLine()
225	End If
226
227	Call sb.AppendLine(ListAllCommandsPrompt)
228	Call sb.AppendLine()
229
230	Dim gg As New Grouping(CLI:=App)
231	Dim print = Sub(list As IEnumerable(Of APIEntryPoint), left$)
232	If markdown Then
233	Call sb.AppendLine("|Function API|Info|")
234	Call sb.AppendLine("|------------|----|")
235	End If
236
237	For Each API As APIEntryPoint In list
238	If Not markdown Then
239	Dim indent% = 3 + nameMaxLen - Len(API.Name)
240	Dim blank$ = New String(c:=" "c, count:=indent)
241	Dim lines As String() = Paragraph _
242	.SplitParagraph(API.Info, 90 - nameMaxLen) _
243	.ToArray
244	Dim line$ = $"{left}{API.Name}:  {blank}{lines.FirstOrDefault}"
245
246	Call sb.AppendLine(line)
247
248	If lines.Length > 1 Then
249	For Each line$ In lines.Skip(1)
250	Call sb.AppendLine(left & New String(" "c, nameMaxLen + 6) & line$)
251	Next
252	End If
253	Else
254	Call sb.AppendLine(
255	$"|[{API.Name}](#{API.Name})|{API.Info.LineTokens.JoinBy("<br />")}|")
256	End If
257	Next
258
259	Call sb.AppendLine()
260	Call sb.AppendLine()
261	End Sub
262
263	If gg.GroupData.ContainsKey(undefined) Then
264	If markdown Then
265	Call sb.AppendLine("##### Generic function API list")
266	End If
267
268	Dim undefines = gg.GroupData(undefined)
269	Call print(undefines.Data, " ")
270	Else
271	' 2017-1-20
272	' 命令行解释器之中已经定义完了所有的API，所以这里已经没有未定义分组的API了
273	End If
274
275	If gg.GroupData.Count > 1 AndAlso Not markdown Then
276	Call sb.AppendLine("API list that with functional grouping")
277	Call sb.AppendLine()
278	End If
279
280	For Each g As SeqValue(Of Groups) In gg _
281	.Where(Function(list) list.Name <> undefined) _
282	.SeqIterator(offset:=1)
283
284	If markdown Then
285	Call sb.AppendLine($"##### {g.i}. {g.value.Name}")
286	Else
287	Call sb.AppendLine($"{g.i}. {g.value.Name}")
288	End If
289
290	Dim describ$ = Trim(g.value.Description)
291	Dim indent As New String(" "c, (g.i & ". ").Length)
292
293	If Not String.IsNullOrEmpty(describ) Then
294	Call sb.AppendLine()
295
296	If markdown Then
297	Call sb.AppendLine(describ)
298	Else
299	For Each line$ In Paragraph.SplitParagraph(describ, 110)
300	Call sb.AppendLine(indent & line)
301	Next
302	End If
303	End If
304
305	Call sb.AppendLine()
306	Call sb.AppendLine()
307	Call print(g.value.Data, left:=indent)
308	Next
309
310	If Not markdown Then
311	Call sb.AppendLine(New String("-"c, 100))
312	Call sb.AppendLine()
313	Call sb.AppendLine("   " & $"1. You can using ""{AssemblyName} ??<commandName>"" for getting more details command help.")
314	Call sb.AppendLine("   " & $"2. Using command ""{AssemblyName} /CLI.dev [---echo]"" for CLI pipeline development.")
315	End If
316
317	Return sb.ToString.TrimEnd(ASCII.CR, ASCII.LF, " "c)
318	End Function
319
320	Public Const ListAllCommandsPrompt As String = "All of the command that available in this program has been list below:"
321	End Module
322	End Namespace