All Downloads are FREE. Search and download functionalities are using the official Maven repository.

parsley.token.names.Names.scala Maven / Gradle / Ivy

The newest version!
/*
 * Copyright 2020 Parsley Contributors 
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */
package parsley.token.names

import parsley.Parsley
import parsley.token.predicate.{CharPredicate, NotRequired}

/** This class defines a uniform interface for defining parsers for user-defined
  * names (identifiers and operators), independent of how whitespace should be
  * handled after the name.
  *
  * @since 4.0.0
  * @note implementations of this class found within `Lexer` may employ sharing
  *       and refine the `def`s in this class into `val` or `lazy val` when overriding.
  *
  * @define disclaimer
  *   the exact behaviour of this parser is decided by the implementations given in
  *   `Lexer`, which will depend on user-defined configuration. Please see the
  *   relevant documentation of these specific objects.
  */
abstract class Names private[names] {
    /** This parser will parse an identifier based on the
      * defined identifier start and identifier letter. It
      * is capable of handling unicode characters if the
      * configuration permits. If hard keywords are specified
      * by the configuration, this parser is not permitted
      * to parse them.
      *
      * @example {{{
      * // identifierStart = Basic(_.isLetter)
      * // identifierLetter = Basic(_.isLetterOrDigit)
      * // hardKeywords = Set("if", ...)
      * scala> identifier.parse("x1")
      * val res0 = Success("x1")
      * scala> identifier.parse("1x")
      * val res1 = Failure(...)
      * scala> identifier.parse("")
      * val res2 = Failure(...)
      * scala> identifier.parse("iffy")
      * val res3 = Success("iffy")
      * scala> identifier.parse("if")
      * val res4 = Failure(...)
      * }}}
      *
      * @note $disclaimer
      * @since 4.0.0
      */
    def identifier: Parsley[String]
    /** This combinator will parse an identifier based on the
      * provided identifier start and described identifier letter. It
      * is capable of handling unicode characters if the
      * configuration permits.
      *
      * After parsing a valid identifier as in `identifier`,
      * this combinator will verify that the first character
      * matches the given parameter. If `NotRequired` is passed,
      * this combinator will be equivalent to `identifier`.
      *
      * If hard keywords are specified
      * by the configuration, this parser is not permitted
      * to parse them.
      *
      * @example {{{
      * // identifierStart = Basic(_.isLetter)
      * // identifierLetter = Basic(_.isLetterOrDigit)
      * // hardKeywords = Set("if", ...)
      * scala> identifier(Basic(_.isLower)).parse("x1")
      * val res0 = Success("x1")
      * scala> identifier(Basic(_.isLower)).parse("X1")
      * val res1 = Failure(...)
      * scala> identifier(Basic(_.isLower)).parse("1x")
      * val res2 = Failure(...)
      * scala> identifier(Basic(_.isLower)).parse("")
      * val res3 = Failure(...)
      * scala> identifier(Basic(_.isLower)).parse("iffy")
      * val res4 = Success("iffy")
      * scala> identifier(Basic(_.isLower)).parse("if")
      * val res5 = Failure(...)
      * }}}
      *
      * @param startChar describes what the starting character must be
      * @note $disclaimer
      * @since 4.0.0
      */
    def identifier(startChar: CharPredicate): Parsley[String]
    /** This parser will parse a user-defined operator based on the
      * defined operator start and operator letter. It
      * is capable of handling unicode characters if the
      * configuration permits. If hard operators are specified
      * by the configuration, this parser is not permitted
      * to parse them.
      *
      * @example {{{
      * // operatorStart = Basic(Set('+', '-'))
      * // operatorLetter = Basic(Set('+', '-', ':'))
      * // hardKeywords = Set("+", "+:", ...)
      * scala> userDefinedOperator.parse("-:")
      * val res0 = Success("-:")
      * scala> userDefinedOperator.parse("*:")
      * val res1 = Failure(...)
      * scala> userDefinedOperator.parse("")
      * val res2 = Failure(...)
      * scala> userDefinedOperator.parse("++")
      * val res3 = Success("++")
      * scala> userDefinedOperator.parse("+:")
      * val res4 = Failure(...)
      * scala> userDefinedOperator.parse("++:")
      * val res5 = Success("++:")
      * }}}
      *
      * @note $disclaimer
      * @since 4.0.0
      */
    def userDefinedOperator: Parsley[String]
    /** This combinator will parse a user-defined operator based on the
      * defined operator start and operator letter, refined by the
      * provided `startChar` and `endChar`. It
      * is capable of handling unicode characters if the
      * configuration permits.
      *
      * After parsing a valid operator as in `userDefinedOperator`,
      * this combinator will verify that the first and last characters
      * match the given parameters. If `NotRequired` is passed to
      * either argument, this will permit any character. Passing
      * it to both arguments will be equivalent to `userDefinedOperator`.
      *
      * If hard operators are specified
      * by the configuration, this parser is not permitted
      * to parse them.
      *
      * @example {{{
      * // operatorStart = Basic(Set('+', '-'))
      * // operatorLetter = Basic(Set('+', '-', ':'))
      * // hardKeywords = Set("+", "+:", ...)
      * scala> userDefinedOperator(NotRequired, Basic(Set(':'))).parse("-:")
      * val res0 = Success("-:")
      * scala> userDefinedOperator(NotRequired, Basic(Set(':'))).parse("*:")
      * val res1 = Failure(...)
      * scala> userDefinedOperator(NotRequired, Basic(Set(':'))).parse("")
      * val res2 = Failure(...)
      * scala> userDefinedOperator(NotRequired, Basic(Set(':'))).parse("++")
      * val res3 = Failure(...)
      * scala> userDefinedOperator(NotRequired, Basic(Set(':'))).parse("+:")
      * val res4 = Failure(...)
      * scala> userDefinedOperator(NotRequired, Basic(Set(':'))).parse("++:")
      * val res5 = Success("++:")
      * }}}
      *
      * @param startChar describes what the starting character must be
      * @param endChar  describes what the final character must be
      * @note $disclaimer
      * @since 4.0.0
      */
    def userDefinedOperator(startChar: CharPredicate, endChar: CharPredicate): Parsley[String]
    /** This combinator will parse a user-defined operator based on the
      * defined operator start and operator letter, refined by the
      * provided `startChar`. It is capable of handling unicode characters if the
      * configuration permits.
      *
      * After parsing a valid operator as in `userDefinedOperator`,
      * this combinator will verify that the first character
      * matches the given parameter. If `NotRequired` is passed it
      * will be equivalent to `userDefinedOperator`.
      *
      * If hard operators are specified
      * by the configuration, this parser is not permitted
      * to parse them.
      *
      * @example {{{
      * // operatorStart = Basic(Set('+', '-'))
      * // operatorLetter = Basic(Set('+', '-', ':'))
      * // hardKeywords = Set("+", "+:", ...)
      * scala> userDefinedOperator(Basic(Set('+'))).parse("-:")
      * val res0 = Failure(...)
      * scala> userDefinedOperator(Basic(Set('+'))).parse("*:")
      * val res1 = Failure(...)
      * scala> userDefinedOperator(Basic(Set('+'))).parse("")
      * val res2 = Failure(...)
      * scala> userDefinedOperator(Basic(Set('+'))).parse("++")
      * val res3 = Success("++")
      * scala> userDefinedOperator(Basic(Set('+'))).parse("+:")
      * val res4 = Failure(...)
      * scala> userDefinedOperator(Basic(Set('+'))).parse("++:")
      * val res5 = Success("++:")
      * }}}
      *
      * @param startChar describes what the starting character must be
      * @note $disclaimer
      * @since 4.1.0
      */
    final def userDefinedOperator(startChar: CharPredicate): Parsley[String] = userDefinedOperator(startChar, NotRequired)

    // TODO: Two variants of the above that also have reasons that describe
    //       the requirements of the identifier/operator
}




© 2015 - 2024 Weber Informatics LLC | Privacy Policy