352 lines
15 KiB
VB.net
352 lines
15 KiB
VB.net
#Region "Microsoft.VisualBasic::794e03f64fd5de438866f90e1b17fcf9, Microsoft.VisualBasic.Core\CommandLine\Interpreters\View\SDKManual.vb"
|
||
|
||
' Author:
|
||
'
|
||
' asuka (amethyst.asuka@gcmodeller.org)
|
||
' xie (genetics@smrucc.org)
|
||
' xieguigang (xie.guigang@live.com)
|
||
'
|
||
' Copyright (c) 2018 GPL3 Licensed
|
||
'
|
||
'
|
||
' GNU GENERAL PUBLIC LICENSE (GPL3)
|
||
'
|
||
'
|
||
' This program is free software: you can redistribute it and/or modify
|
||
' it under the terms of the GNU General Public License as published by
|
||
' the Free Software Foundation, either version 3 of the License, or
|
||
' (at your option) any later version.
|
||
'
|
||
' This program is distributed in the hope that it will be useful,
|
||
' but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
' MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||
' GNU General Public License for more details.
|
||
'
|
||
' You should have received a copy of the GNU General Public License
|
||
' along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||
|
||
|
||
|
||
' /********************************************************************************/
|
||
|
||
' Summaries:
|
||
|
||
' Module SDKManual
|
||
'
|
||
' Function: HelpSummary, LaunchManual, MarkdownDoc
|
||
'
|
||
' Sub: AppSummary
|
||
'
|
||
'
|
||
' /********************************************************************************/
|
||
|
||
#End Region
|
||
|
||
Imports System.IO
|
||
Imports System.Runtime.CompilerServices
|
||
Imports System.Text
|
||
Imports Microsoft.VisualBasic.ApplicationServices.Debugging
|
||
Imports Microsoft.VisualBasic.ApplicationServices.Development
|
||
Imports Microsoft.VisualBasic.ApplicationServices.Terminal.Utility
|
||
Imports Microsoft.VisualBasic.CommandLine.Grouping
|
||
Imports Microsoft.VisualBasic.CommandLine.Reflection
|
||
Imports Microsoft.VisualBasic.CommandLine.Reflection.EntryPoints
|
||
Imports Microsoft.VisualBasic.ComponentModel.DataSourceModel
|
||
Imports Microsoft.VisualBasic.Language
|
||
Imports Microsoft.VisualBasic.Linq
|
||
Imports Microsoft.VisualBasic.Scripting
|
||
Imports Microsoft.VisualBasic.Scripting.TokenIcer.Prefix
|
||
Imports Microsoft.VisualBasic.Text
|
||
Imports VBCore = Microsoft.VisualBasic.App
|
||
|
||
Namespace CommandLine.ManView
|
||
|
||
''' <summary>
|
||
''' Generates the help document in markdown format.
|
||
''' (生成markdown格式的帮助文件)
|
||
''' </summary>
|
||
Module SDKManual
|
||
|
||
''' <summary>
|
||
''' 这个是用于在终端上面显示的无格式的文本输出
|
||
''' </summary>
|
||
''' <param name="CLI"></param>
|
||
''' <returns></returns>
|
||
<Extension>
|
||
Public Function LaunchManual(CLI As Interpreter) As Integer
|
||
Dim assm As AssemblyInfo = ApplicationInfoUtils.FromTypeModule(CLI.Type)
|
||
Dim title As String = $"{Application.ProductName} [version {Application.ProductVersion}]" & vbCrLf &
|
||
vbCrLf &
|
||
"## " & assm.AssemblyTitle & vbCrLf &
|
||
vbCrLf &
|
||
"Description: " & assm.AssemblyDescription & vbCrLf &
|
||
"Company: " & assm.AssemblyCompany & vbCrLf &
|
||
assm.AssemblyCopyright ' 首页
|
||
|
||
Dim sb As New StringBuilder
|
||
|
||
Call sb.AppendLine($"Module AssemblyName: {App.ExecutablePath.ToFileURL}")
|
||
Call sb.AppendLine($"Root namespace: " & CLI.ToString)
|
||
Call sb.AppendLine(vbCrLf & vbCrLf & CLI.HelpSummary(False))
|
||
|
||
Dim firstPage As String = sb.ToString
|
||
Dim pages As List(Of String) = {
|
||
DebuggerArgs.DebuggerHelps,
|
||
CLI.Type.NamespaceEntry.Description
|
||
}.AsList
|
||
|
||
pages += LinqAPI.Exec(Of String) <=
|
||
_
|
||
From api As SeqValue(Of APIEntryPoint)
|
||
In CLI.APIList.SeqIterator(offset:=1)
|
||
Let index As String = api.i & ". "
|
||
Let info As String = api.value.HelpInformation
|
||
Select index & info
|
||
|
||
Call New IndexedManual(pages, title).ShowManual()
|
||
|
||
Return 0
|
||
End Function
|
||
|
||
''' <summary>
|
||
''' 这个是用于保存于文件之中的markdown格式的有格式标记的文本输出
|
||
''' </summary>
|
||
''' <returns></returns>
|
||
'''
|
||
<Extension>
|
||
Public Function MarkdownDoc(App As Interpreter) As String
|
||
Dim sb As New StringBuilder($"# { VisualBasic.App.ProductName} [version { VisualBasic.App.Version}]")
|
||
Dim type As Type = App.Type
|
||
Dim assm As AssemblyInfo = ApplicationInfoUtils.FromTypeModule(App.Type)
|
||
|
||
Call sb.AppendLine()
|
||
Call sb.AppendLine("> " & App.Type.NamespaceEntry.Description.LineTokens.JoinBy(vbCrLf & "> "))
|
||
Call sb.AppendLine()
|
||
Call sb.AppendLine("<!--more-->")
|
||
Call sb.AppendLine()
|
||
Call sb.AppendLine($"**{assm.AssemblyTitle}**<br/>")
|
||
Call sb.AppendLine($"_{assm.AssemblyDescription}_<br/>")
|
||
Call sb.AppendLine(assm.AssemblyCopyright)
|
||
Call sb.AppendLine()
|
||
|
||
Call sb.AppendLine($"**Module AssemblyName**: {type.Assembly.Location.BaseName}<br/>")
|
||
Call sb.AppendLine($"**Root namespace**: ``{App.Type.FullName}``<br/>")
|
||
|
||
Dim helps As ExceptionHelp = type.GetAttribute(Of ExceptionHelp)
|
||
|
||
If Not helps Is Nothing Then
|
||
Call sb.AppendLine()
|
||
Call sb.AppendLine("------------------------------------------------------------")
|
||
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:")
|
||
Call sb.AppendLine("> " & helps.Documentation)
|
||
Call sb.AppendLine()
|
||
Call sb.AppendLine()
|
||
Call sb.AppendLine("The debugging facility Is helpful To figure out what's happening under the hood:")
|
||
Call sb.AppendLine("> " & helps.Debugging)
|
||
Call sb.AppendLine()
|
||
Call sb.AppendLine()
|
||
Call sb.AppendLine("If you're still stumped, you can try get help from author directly from E-mail:")
|
||
Call sb.AppendLine("> " & helps.EMailLink)
|
||
Call sb.AppendLine()
|
||
End If
|
||
|
||
Call sb.AppendLine(vbCrLf & vbCrLf & App.HelpSummary(True))
|
||
Call sb.AppendLine()
|
||
Call sb.AppendLine("## CLI API list")
|
||
Call sb.AppendLine("--------------------------")
|
||
|
||
For Each i As SeqValue(Of APIEntryPoint) In App.APIList.SeqIterator
|
||
Dim api As APIEntryPoint = i.value
|
||
|
||
Call sb.Append($"<h3 id=""{api.Name}""> {i.i + 1}. ")
|
||
Call sb.AppendLine(api.HelpInformation(md:=True) _
|
||
.LineTokens _
|
||
.Select(Function(s) s.Trim) _
|
||
.JoinBy(vbCrLf))
|
||
|
||
If api.Arguments.Count > 0 Then
|
||
Dim prints = api.Arguments _
|
||
.Where(Function(x) Not x.Value.AcceptTypes.IsNullOrEmpty) _
|
||
.ToArray
|
||
|
||
If Not prints.Length = 0 Then
|
||
Call sb.AppendLine("##### Accepted Types")
|
||
|
||
For Each param As NamedValue(Of Argument) In prints
|
||
Call sb.AppendLine("###### " & param.Name)
|
||
|
||
For Each pType As Type In param.Value.AcceptTypes
|
||
Call sb.AppendLine(Activity.DisplayType(pType))
|
||
Next
|
||
Next
|
||
End If
|
||
End If
|
||
Next
|
||
|
||
Return sb.ToString
|
||
End Function
|
||
|
||
''' <summary>
|
||
'''
|
||
''' </summary>
|
||
''' <param name="assem"></param>
|
||
''' <param name="description">命令行的使用功能描述信息文本</param>
|
||
''' <param name="SYNOPSIS">命令行的使用语法</param>
|
||
''' <param name="write"></param>
|
||
<Extension>
|
||
Public Sub AppSummary(assem As AssemblyInfo, description$, SYNOPSIS$, write As TextWriter)
|
||
Dim descr = assem.AssemblyDescription
|
||
|
||
Call write.WriteLine()
|
||
|
||
Call write.WriteLine(" // ")
|
||
Call write.WriteLine(" // " & Strings.Trim(descr) Or "[No description]".AsDefault)
|
||
Call write.WriteLine(" // ")
|
||
Call write.WriteLine(" // VERSION: " & (assem.AssemblyVersion Or "1.0.0.*".AsDefault))
|
||
Call write.WriteLine(" // ASSEMBLY: " & assem.AssemblyFullName)
|
||
Call write.WriteLine(" // COPYRIGHT: " & assem.AssemblyCopyright)
|
||
Call write.WriteLine(" // GUID: " & assem.Guid)
|
||
Call write.WriteLine(" // BUILT: " & assem.BuiltTime.ToString)
|
||
Call write.WriteLine(" // ")
|
||
|
||
Call write.WriteLine()
|
||
Call write.WriteLine()
|
||
|
||
For Each line$ In Paragraph.SplitParagraph(description, 110)
|
||
Call write.WriteLine(" " & line$)
|
||
Next
|
||
|
||
If Not SYNOPSIS.StringEmpty Then
|
||
Call write.WriteLine()
|
||
Call write.WriteLine()
|
||
Call write.WriteLine("SYNOPSIS")
|
||
Call write.WriteLine(SYNOPSIS)
|
||
Call write.WriteLine()
|
||
End If
|
||
|
||
Call write.Flush()
|
||
End Sub
|
||
|
||
''' <summary>
|
||
''' Returns the summary brief help information of all of the commands in current cli interpreter.
|
||
''' (枚举出本CLI解释器之中的所有的命令的帮助的摘要信息)
|
||
''' </summary>
|
||
''' <returns></returns>
|
||
''' <remarks></remarks>
|
||
''' <param name="markdown">Output in markdown format?</param>
|
||
<Extension>
|
||
Public Function HelpSummary(App As Interpreter, markdown As Boolean) As String
|
||
Dim sb As New StringBuilder(1024)
|
||
Dim nameMaxLen% = App.APIList _
|
||
.Select(Function(x) Len(x.Name)) _
|
||
.Max
|
||
|
||
If Not markdown Then
|
||
Call ($"{VBCore.AssemblyName} command [/argument argument-value...] [/@set environment-variable=value...]") _
|
||
.DoCall(Sub(SYNOPSIS)
|
||
Call VBCore.Info.AppSummary(
|
||
description:=App.Info.Description,
|
||
SYNOPSIS:=SYNOPSIS,
|
||
write:=New StringWriter(sb)
|
||
)
|
||
End Sub)
|
||
End If
|
||
|
||
Call sb.AppendLine(ListAllCommandsPrompt)
|
||
Call sb.AppendLine()
|
||
|
||
Dim gg As New Grouping(CLI:=App)
|
||
Dim print = Sub(list As IEnumerable(Of APIEntryPoint), left$)
|
||
If markdown Then
|
||
Call sb.AppendLine("|Function API|Info|")
|
||
Call sb.AppendLine("|------------|----|")
|
||
End If
|
||
|
||
For Each API As APIEntryPoint In list
|
||
If Not markdown Then
|
||
Dim indent% = 3 + nameMaxLen - Len(API.Name)
|
||
Dim blank$ = New String(c:=" "c, count:=indent)
|
||
Dim lines As String() = Paragraph _
|
||
.SplitParagraph(API.Info, 90 - nameMaxLen) _
|
||
.ToArray
|
||
Dim line$ = $"{left}{API.Name}: {blank}{lines.FirstOrDefault}"
|
||
|
||
Call sb.AppendLine(line)
|
||
|
||
If lines.Length > 1 Then
|
||
For Each line$ In lines.Skip(1)
|
||
Call sb.AppendLine(left & New String(" "c, nameMaxLen + 6) & line$)
|
||
Next
|
||
End If
|
||
Else
|
||
Call sb.AppendLine(
|
||
$"|[{API.Name}](#{API.Name})|{API.Info.LineTokens.JoinBy("<br />")}|")
|
||
End If
|
||
Next
|
||
|
||
Call sb.AppendLine()
|
||
Call sb.AppendLine()
|
||
End Sub
|
||
|
||
If gg.GroupData.ContainsKey(undefined) Then
|
||
If markdown Then
|
||
Call sb.AppendLine("##### Generic function API list")
|
||
End If
|
||
|
||
Dim undefines = gg.GroupData(undefined)
|
||
Call print(undefines.Data, " ")
|
||
Else
|
||
' 2017-1-20
|
||
' 命令行解释器之中已经定义完了所有的API，所以这里已经没有未定义分组的API了
|
||
End If
|
||
|
||
If gg.GroupData.Count > 1 AndAlso Not markdown Then
|
||
Call sb.AppendLine("API list that with functional grouping")
|
||
Call sb.AppendLine()
|
||
End If
|
||
|
||
For Each g As SeqValue(Of Groups) In gg _
|
||
.Where(Function(list) list.Name <> undefined) _
|
||
.SeqIterator(offset:=1)
|
||
|
||
If markdown Then
|
||
Call sb.AppendLine($"##### {g.i}. {g.value.Name}")
|
||
Else
|
||
Call sb.AppendLine($"{g.i}. {g.value.Name}")
|
||
End If
|
||
|
||
Dim describ$ = Trim(g.value.Description)
|
||
Dim indent As New String(" "c, (g.i & ". ").Length)
|
||
|
||
If Not String.IsNullOrEmpty(describ) Then
|
||
Call sb.AppendLine()
|
||
|
||
If markdown Then
|
||
Call sb.AppendLine(describ)
|
||
Else
|
||
For Each line$ In Paragraph.SplitParagraph(describ, 110)
|
||
Call sb.AppendLine(indent & line)
|
||
Next
|
||
End If
|
||
End If
|
||
|
||
Call sb.AppendLine()
|
||
Call sb.AppendLine()
|
||
Call print(g.value.Data, left:=indent)
|
||
Next
|
||
|
||
If Not markdown Then
|
||
Call sb.AppendLine(New String("-"c, 100))
|
||
Call sb.AppendLine()
|
||
Call sb.AppendLine(" " & $"1. You can using ""{AssemblyName} ??<commandName>"" for getting more details command help.")
|
||
Call sb.AppendLine(" " & $"2. Using command ""{AssemblyName} /CLI.dev [---echo]"" for CLI pipeline development.")
|
||
Call sb.AppendLine(" " & $"3. Using command ""{AssemblyName} /i"" for enter interactive console mode.")
|
||
End If
|
||
|
||
Return sb.ToString.TrimEnd(ASCII.CR, ASCII.LF, " "c)
|
||
End Function
|
||
|
||
Public Const ListAllCommandsPrompt As String = "All of the command that available in this program has been list below:"
|
||
End Module
|
||
End Namespace
|