Package dev.sympho.modular_commands.utils.parse

Interface UrlParser<T extends @NonNull Object>

Type Parameters:
T - The parsed type.
All Superinterfaces:
BiFunction<CommandContext,String,Mono<T>>, ParserFunction<String,T>
All Known Subinterfaces:
FunctorUrlParser<T>
All Known Implementing Classes:
ChannelRefUrlParser, ChannelUrlParser, EntityRefUrlParser, EntityUrlParser, FunctorUrlParser.Choice, FunctorUrlParser.ChoiceBase, FunctorUrlParser.PostParser, MessageRefUrlParser, MessageUrlParser, UrlParser.Choice, UrlParser.ChoiceBase, UrlParser.PostParser
public interface UrlParser<T extends @NonNull Object> extends ParserFunction<String,T>
A parser for URL-based arguments.
Since:
1.0
Version:
1.0

  • Field Details

    • MASKED_URL_PATTERN

      static final @Regex(1) Pattern MASKED_URL_PATTERN
      Pattern that matches a masked link.

  • Method Details

    • choice

      static <T extends @NonNull Object> UrlParser<T> choice(Function<URL,@Nullable UrlParser<T>> parserMapper)
      Creates a parser that delegates to other parsers, chosen by the given mapping function based on the URL to parse.
      Type Parameters:
      T - The parsed argument type.
      Parameters:
      parserMapper - The function to use to determine which parser to delegate to for a given URL.
      Returns:
      The parser.

    • choice

      static <T extends @NonNull Object> UrlParser<T> choice(Collection<? extends UrlParser<T>> parsers)
      Creates a parser that delegates to the given parsers.

      The parser choice is defined as the first parser in the iteration order of the given collection for which supports(URL) returns true for the URL being parsed. This implies that the iteration order matters if, and only if, there are URLs that may be supported by more than one of the parsers in the collection.

      Type Parameters:
      T - The parsed argument type.
      Parameters:
      parsers - The parsers to delegate to.
      Returns:
      The parser.

    • choice

      @SafeVarargs static <T extends @NonNull Object> UrlParser<T> choice(UrlParser<T>... parsers)
      Creates a parser that delegates to the given parsers.

      The parser choice is defined as the first parser in the given order for which supports(URL) returns true for the URL being parsed. This implies that the iteration order matters if, and only if, there are URLs that may be supported by more than one of the parsers in the collection.

      Type Parameters:
      T - The parsed argument type.
      Parameters:
      parsers - The parsers to delegate to.
      Returns:
      The parser.

    • choiceHost

      static <T extends @NonNull Object> UrlParser<T> choiceHost(Map<String,? extends UrlParser<T>> parsers)
      Creates a parser that delegates to a parser depending on the host of the URL, using the given host-parser mappings.
      Type Parameters:
      T - The parsed argument type.
      Parameters:
      parsers - The host-parser mappings to delegate to.
      Returns:
      The parser.

    • stripFormatting

      @SideEffectFree static String stripFormatting(String raw)
      Clears special URL formatting from the given string, if any exists.

      The following formatting types are supported:

      • Supressed links (links surrounded by <>)
      • Masked links (links that display as clickable text)

      Note that layered formats are supported if supported by Discord; for example, [Discord](<https://discord.com>) is a link that is both supressed and masked.

      Parameters:
      raw - The string to strip.
      Returns:
      The stripped string.

    • getUrl

      @SideEffectFree static URL getUrl(String raw) throws InvalidArgumentException
      Parses the given string into a URL.
      Parameters:
      raw - The string to parse.
      Returns:
      The URL.
      Throws:
      InvalidArgumentException - if the given string is not a valid URL.
      API Note:
      Mainly a wrapper to convert the URL exception into the invalid argument type.

    • parseUrl

      @SideEffectFree static @Nullable URL parseUrl(String raw, Collection<String> allowedProtocols) throws InvalidArgumentException
      Attempts to parse a string as a URL.

      Some effort is made to detect URLs surrounded by special markup; see stripFormatting(String).

      Parameters:
      raw - The string to parse.
      allowedProtocols - The acceptable protocols.
      Returns:
      The parsed URL if one could be parsed, or null if the given string is not a URL or has a protocol that is not contained in allowedProtocols.
      Throws:
      InvalidArgumentException - if the given string has a URL format (and an allowed protocol) but is invalid in some way.

    • parseUrl

      @SideEffectFree static @Nullable URL parseUrl(String raw, String allowedProtocol) throws InvalidArgumentException
      Attempts to parse a string as a URL.

      Some effort is made to detect URLs surrounded by special markup; see stripFormatting(String).

      Parameters:
      raw - The string to parse.
      allowedProtocol - The acceptable protocol.
      Returns:
      The parsed URL if one could be parsed, or null if the given string is not a URL or does not have the allowedProtocol.
      Throws:
      InvalidArgumentException - if the given string has a URL format (and the allowed protocol) but is invalid in some way.

    • supports

      @Pure boolean supports(URL url)
      Checks if the given URL is supported by this parser. If this returns false, calling parse(CommandContext, URL) with the same URL will result in an error.

      Note that the opposite isn't necessarily true; it is possible for this method to return true for a given URL while parse(CommandContext, URL) results in an error. That just means that the basic structure of the URL was detected as being compatible with this parser (for example, having a particular host and/or protocol), but was malformed or a variant that the parser doesn't support.

      Parameters:
      url - The URL to check.
      Returns:
      Whether the URL is compatible with this parser.

    • parse

      @SideEffectFree Mono<T> parse(CommandContext context, URL url) throws InvalidArgumentException
      Parses the given URL.
      Parameters:
      context - The execution context.
      url - The URL to parse.
      Returns:
      The parsed value. May result in a InvalidArgumentException if the URL is invalid.
      Throws:
      InvalidArgumentException - if the URL is invalid.

    • parse

      default Mono<T> parse(CommandContext context, String raw) throws InvalidArgumentException
      Description copied from interface: ParserFunction
      Parses the given raw argument from the user into the corresponding value.
      Specified by:
      parse in interface ParserFunction<String,T extends @NonNull Object>
      Parameters:
      context - The execution context.
      raw - The raw argument received from the user.
      Returns:
      A Mono that issues the parsed argument. If the raw value is invalid, it may fail with a InvalidArgumentException. May be empty, in which case the value defers to the default (functionally the same as if the argument was missing, but without causing an error if the parameter is required).
      Throws:
      InvalidArgumentException - if the given argument is not a valid value.

    • then

      @SideEffectFree default <V extends @NonNull Object> UrlParser<V> then(ParserFunction<T,V> after)
      Returns a composed parser that first applies this parser to its input, and then applies the after parser to the result. If parsing with either parser throws an exception, it is relayed to the caller of the composed parser.
      Specified by:
      then in interface ParserFunction<String,T extends @NonNull Object>
      Type Parameters:
      V - The type of output of the after parser, and of the composed parser.
      Parameters:
      after - The parser to apply after this parser is applied.
      Returns:
      The composed parser.