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