github-repos/mirai
1
0
Fork 0
mirror of https://github.com/mamoe/mirai.git synced 2025-01-25 15:40:28 +08:00
Code Issues Packages Projects Releases Wiki Activity

Docs and API improvements

Browse Source
This commit is contained in:
Him188 2020-10-09 10:47:49 +08:00
parent 4ddee69531
commit 1e9b498ba9
8 changed files with 88 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/parse/CommandCall.kt
View File

@ -11,34 +11,32 @@
package net.mamoe.mirai.console.command.parse
import net.mamoe.mirai.console.command.Command
import net.mamoe.mirai.console.command.CommandSender
import net.mamoe.mirai.console.command.descriptor.ExperimentalCommandDescriptors
import net.mamoe.mirai.console.command.descriptor.UnresolvedCommandCallException
import net.mamoe.mirai.console.command.resolve.ResolvedCommandCall
import net.mamoe.mirai.console.extensions.CommandCallResolverProvider
import net.mamoe.mirai.console.internal.extension.GlobalComponentStorage
import net.mamoe.mirai.console.command.resolve.CommandCallResolver
import net.mamoe.mirai.console.util.ConsoleExperimentalApi
/**
* Unresolved [CommandCall].
*/
@ExperimentalCommandDescriptors
public interface CommandCall {
public val caller: CommandSender
/**
* One of callee [Command]'s [Command.allNames]
*/
public val calleeName: String
/**
* Explicit value arguments
*/
public val valueArguments: List<CommandValueArgument>
public companion object {
@JvmStatic
public fun CommandCall.resolveOrNull(): ResolvedCommandCall? {
GlobalComponentStorage.run {
CommandCallResolverProvider.useExtensions { provider ->
provider.instance.resolve(this@resolveOrNull)?.let { return it }
}
}
return null
}
@JvmStatic
public fun CommandCall.resolve(): ResolvedCommandCall {
return resolveOrNull() ?: throw UnresolvedCommandCallException(this)
}
}
/**
* Custom data for [CommandCallResolver]
*/
@ConsoleExperimentalApi
public val customData: Map<Any, Any>
}

17
backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/parse/CommandCallParser.kt
View File

@ -2,20 +2,35 @@ package net.mamoe.mirai.console.command.parse
import net.mamoe.mirai.console.command.CommandSender
import net.mamoe.mirai.console.command.descriptor.ExperimentalCommandDescriptors
import net.mamoe.mirai.console.command.resolve.CommandCallResolver
import net.mamoe.mirai.console.command.resolve.ResolvedCommandCall
import net.mamoe.mirai.console.extensions.CommandCallParserProvider
import net.mamoe.mirai.console.internal.extension.GlobalComponentStorage
import net.mamoe.mirai.console.util.ConsoleExperimentalApi
import net.mamoe.mirai.message.data.MessageChain
/**
* @see CommandCallParserProvider
* Lexical and syntactical parser for transforming a [MessageChain] into [CommandCall]
*
* @see CommandCallResolver The call resolver for [CommandCall] to become [ResolvedCommandCall]
* @see CommandCallParserProvider The extension point
*/
@ConsoleExperimentalApi
@ExperimentalCommandDescriptors
public interface CommandCallParser {
/**
* Lexically and syntactically parse a [message] into [CommandCall], but performs nothing about resolving a call.
*
* @return `null` if unable to parse (i.e. due to syntax errors).
*/
public fun parse(sender: CommandSender, message: MessageChain): CommandCall?
public companion object {
/**
* Calls [CommandCallParser]s provided by [CommandCallParserProvider] in [GlobalComponentStorage] sequentially,
* returning the first non-null result, `null` otherwise.
*/
@JvmStatic
public fun MessageChain.parseCommandCall(sender: CommandSender): CommandCall? {
GlobalComponentStorage.run {

5
backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/parse/CommandValueArgument.kt
View File

@ -24,7 +24,10 @@ import kotlin.reflect.typeOf
public typealias RawCommandArgument = MessageContent
@ExperimentalCommandDescriptors
public interface CommandValueArgument {
public interface CommandArgument
@ExperimentalCommandDescriptors
public interface CommandValueArgument : CommandArgument {
public val value: RawCommandArgument
public val typeVariants: List<TypeVariant<*>>
}

20
backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/resolve/CommandCallResolver.kt
View File

@ -11,8 +11,26 @@ package net.mamoe.mirai.console.command.resolve
import net.mamoe.mirai.console.command.descriptor.ExperimentalCommandDescriptors
import net.mamoe.mirai.console.command.parse.CommandCall
import net.mamoe.mirai.console.extensions.CommandCallResolverProvider
import net.mamoe.mirai.console.internal.extension.GlobalComponentStorage
/**
* The resolver converting a [CommandCall] into [ResolvedCommandCall] based on registered []
*/
@ExperimentalCommandDescriptors
public interface CommandCallResolver {
@ExperimentalCommandDescriptors
public fun resolve(call: CommandCall): ResolvedCommandCall?
public companion object {
@JvmStatic
@JvmName("resolveCall")
public fun CommandCall.resolve(): ResolvedCommandCall? {
GlobalComponentStorage.run {
CommandCallResolverProvider.useExtensions { provider ->
provider.instance.resolve(this@resolve)?.let { return it }
}
}
return null
}
}
}

22
backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/resolve/ResolvedCommandCall.kt
View File

@ -11,15 +11,37 @@ package net.mamoe.mirai.console.command.resolve;
import net.mamoe.mirai.console.command.Command
import net.mamoe.mirai.console.command.CommandSender
import net.mamoe.mirai.console.command.CompositeCommand
import net.mamoe.mirai.console.command.descriptor.CommandDescriptor
import net.mamoe.mirai.console.command.descriptor.CommandSignatureVariant
import net.mamoe.mirai.console.command.descriptor.ExperimentalCommandDescriptors
import net.mamoe.mirai.console.command.parse.CommandCall
import net.mamoe.mirai.console.command.parse.CommandValueArgument
/**
* The resolved [CommandCall].
*/
@ExperimentalCommandDescriptors
public interface ResolvedCommandCall {
public val caller: CommandSender
/**
* The callee [Command]
*/
public val callee: Command
/**
* The callee [CommandDescriptor], specifically a sub command from [CompositeCommand]
*/
public val calleeDescriptor: CommandDescriptor
/**
* The callee [CommandSignatureVariant]
*/
public val calleeSignature: CommandSignatureVariant
/**
* Resolved value arguments arranged mapping the [CommandSignatureVariant.valueParameters] by index.
*/
public val valueArguments: List<CommandValueArgument>
}

3
backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extensions/CommandParser.kt → backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extensions/CommandCallParserProvider.kt
View File

@ -14,6 +14,9 @@ import net.mamoe.mirai.console.command.parse.CommandCallParser
import net.mamoe.mirai.console.extension.AbstractExtensionPoint
import net.mamoe.mirai.console.extension.InstanceExtension
/**
* The resolver for a [CommandCall]
*/
@ExperimentalCommandDescriptors
public interface CommandCallParserProvider : InstanceExtension<CommandCallParser> {
public companion object ExtensionPoint : AbstractExtensionPoint<CommandCallParserProvider>(CommandCallParserProvider::class)

5
backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extensions/CommandResolverExtension.kt → backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extensions/CommandCallResolverProvider.kt
View File

@ -9,11 +9,12 @@
package net.mamoe.mirai.console.extensions
import net.mamoe.mirai.console.command.descriptor.ExperimentalCommandDescriptors
import net.mamoe.mirai.console.command.resolve.CommandCallResolver
import net.mamoe.mirai.console.extension.AbstractExtensionPoint
import net.mamoe.mirai.console.extension.InstanceExtension
@ExperimentalCommandDescriptors
public interface CommandCallResolverProvider : InstanceExtension<CommandCallResolver> {
public companion object ExtensionPoint : AbstractExtensionPoint<CommandCallResolverProvider>(CommandCallResolverProvider::class)
}
}

3
backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/internal/extension/ComponentStorageInternal.kt
View File

@ -20,6 +20,9 @@ import java.util.concurrent.CopyOnWriteArraySet
import kotlin.contracts.contract
import kotlin.reflect.KClass
/**
* The [ComponentStorage] containing all components provided by Mirai Console internals and installed plugins.
*/
internal object GlobalComponentStorage : AbstractConcurrentComponentStorage()
internal interface ExtensionRegistry<out E : Extension> {
val plugin: Plugin