<commit_before>package com.avsystem.commons
package rpc

import scala.annotation.StaticAnnotation

/**
  * For annotations applied on real RPC traits, their methods and parameters.
  */
trait RpcAnnotation extends StaticAnnotation

/**
  * For annotations applied on raw RPC traits, their methods and parameters.
  * They specify how real methods are matched against raw methods and real parameters against raw parameters.
  */
sealed trait RawRpcAnnotation extends StaticAnnotation
sealed trait RawMethodAnnotation extends RawRpcAnnotation
sealed trait RawParamAnnotation extends RawRpcAnnotation

/**
  * You can use this annotation on overloaded RPC methods to give them unique identifiers for RPC serialization.
  * You can also subclass this annotation provided that you always override the `name` parameter with another
  * constructor parameter.
  */
class rpcName(val name: String) extends RpcAnnotation

/**
  * You can use this annotation on real RPC methods to instruct macro engine to prepend method name (or [[rpcName]] if
  * specified) with given prefix. This annotation is mostly useful when aggregated by another annotation e.g.
  *
  * {{{
  *   sealed trait RestMethod extends RpcTag
  *   final class GET extends RestMethod with AnnotationAggregate {
  *     @rpcNamePrefix("GET_") type Implied
  *   }
  * }}}
  */
class rpcNamePrefix(val prefix: String) extends RpcAnnotation

/**
  * Base trait for RPC tag annotations. Tagging gives more direct control over how real methods
  * and their parameters are matched against raw methods and their parameters.
  * For more information about method tagging, see documentation of [[methodTag]].
  * For more information about parameter tagging, see documentation of [[paramTag]].
  */
trait RpcTag extends RpcAnnotation

/**
  * May be applied on raw method parameter of type `String` to indicate that macro generated implementation of
  * `AsReal` should pass real method's RPC name as this parameter and that macro generated implementation of
  * `AsRaw` should expect real method's RPC name to be passed there.
  *
  * Macro generation of `AsRaw` implementations require that raw methods annotated as [[multi]] must take at least
  * one raw parameter annotated as [[methodName]] (it may also be aggregated into some [[composite]] parameter).
  * This is necessary to properly identify which real method should be called.
  */
final class methodName extends RawParamAnnotation

/**
  * Can be applied on raw method parameters or metadata parameters. When a parameter is annotated as `@composite`,
  * the macro engine expects its type to be a class with public primary constructor. Then, it recursively inspects its
  * constructor parameters and treats them as if they were direct parameters. This effectively groups multiple
  * raw parameters or multiple metadata parameters into a single class.
  */
final class composite extends RawParamAnnotation

/**
  * Base trait for RPC arity annotations, [[single]], [[optional]] and [[multi]].
  * Arity annotations may be used in multiple contexts:
  *
  * - raw methods
  * - raw parameters
  * - metadata parameters for raw methods and raw parameters
  * - metadata parameters that reify annotations (i.e. annotated with [[reifyAnnot]])
  *
  * See documentation of each arity annotation for more details.
  */
sealed trait RpcArity extends RawParamAnnotation

/**
  * The default arity annotation. Usually there is no need to use this annotation explicitly.
  *
  * When applied on raw method, there must be exactly one real method matching this raw method and it must have
  * the same name (or [[rpcName]]) as raw method's name.
  *
  * When applied on raw parameter, specifies that this raw parameter must be matched by exactly one real parameter,
  * on the position that matches raw parameter's position. Names are ignored because - unlike methods - parameters are
  * identified by their position in parameter list(s) rather than their name.
  *
  * By default, [[single]] raw methods and parameters are [[verbatim]] which means that the real method must have
  * exactly the same return type as raw method and real parameter must have exactly the same type as raw parameter.
  *
  * When applied on method metadata parameter or parameter metadata parameter, the rules above apply in the same way
  * except that real method/parameter type is matched against the type passed as `T` to `TypedMetadata[T]` by
  * metadata class. For example, if method metadata class extends `TypedMetadata[Unit]` then `Unit` is assumed to be
  * the result type of raw method that this metadata class represents. Similarly, when parameter metadata class
  * extends `TypedMetadata[Int]` then raw parameter represented by this metadata class is assumed to be of type `Int`.
  *
  * Finally, when applied on metadata parameter with [[reifyAnnot]], that parameter is supposed to hold exactly one
  * instance of an annotation of given type from real trait/method/param. If there is no such annotation available,
  * compilation error will be raised.
  */
final class single extends RpcArity

/**
  * When applied on raw method, it works almost the same way as [[single]] except that it is not required that
  * matching real method exists in real RPC trait. If there is no matching real method, macro-materialized `AsRaw`
  * implementation will implement the raw method with a code that throws an exception.
  *
  * When applied on raw parameter, specifies that this raw parameter may be matched by a real parameter but this is
  * not required. Whether a real parameter matches an optional raw parameter is determined by its type and/or tag
  * (see [[paramTag]] for more information on param tagging).
  *
  * Raw parameters marked as [[optional]] must be typed as `Option[T]` (or `Opt[T]`, `OptArg[T]` or whatever type that
  * has an instance of `OptionLike`). By default, [[optional]] raw parameters are [[verbatim]] which means that the
  * option-wrapped type `T` must match exactly the type of real parameter.
  *
  * In the macro generated code that translates a raw call into a real call, when the raw parameter value is absent
  * (the `Option[T]` is empty) then real parameter's default value will be used as fallback. This allows introducing
  * new parameters into RPC interfaces without breaking backwards compatibility.
  *
  * [[optional]] may also be used on method metadata parameters or parameter metadata parameters. It works the same
  * way as with [[single]] except that metadata class must be wrapped in an `OptionLike` type (`Option`, `Opt`, etc.).
  *
  * Finally, [[optional]] may also be used for metadata parameters that hold reified annotations (see [[reifyAnnot]]).
  * In that case it is not required that the annotation being reified is actually present on the real trait/method/param.
  * For that to work, metadata param must be typed as `Option[A]`, `Opt[A]`, etc. where `A` is the type of annotation
  * being reified.
  */
final class optional extends RpcArity

/**
  * When applied on raw method, specifies that this raw method may be matched by many, arbitrarily named real methods.
  * In order to distinguish between real methods, multi raw method must take real method's RPC name
  * (a `String`) as its first parameter and the only parameter in its first parameter list.
  * By default, result type of multi raw method is [[encoded]] and the macro engine searches for
  * appropriate `AsRaw` or `AsReal` conversion between real method result type and raw method result type.
  *
  * When applied on raw parameter, specifies that this raw parameter may be matched by arbitrary number of real
  * parameters whose values are typically [[encoded]] and collected into (or extracted from) raw parameter value.
  * The way real parameter values are collected and extracted depends on the type of raw parameter which must be
  * either:
  *
  * - an `Iterable[R]` or any subtype (e.g. `List[R]`)
  * - a `PartialFunction[String,R]` or any subtype (e.g. `Map[String,R]`)
  *
  * `R` denotes the type used to represent each real parameter value. Be default (unless [[verbatim]] is used) it means<commit_msg>doc fix<commit_after>package com.avsystem.commons
package rpc

import scala.annotation.StaticAnnotation

/**
  * For annotations applied on real RPC traits, their methods and parameters.
  */
trait RpcAnnotation extends StaticAnnotation

/**
  * For annotations applied on raw RPC traits, their methods and parameters.
  * They specify how real methods are matched against raw methods and real parameters against raw parameters.
  */
sealed trait RawRpcAnnotation extends StaticAnnotation
sealed trait RawMethodAnnotation extends RawRpcAnnotation
sealed trait RawParamAnnotation extends RawRpcAnnotation

/**
  * You can use this annotation on overloaded RPC methods to give them unique identifiers for RPC serialization.
  * You can also subclass this annotation provided that you always override the `name` parameter with another
  * constructor parameter.
  */
class rpcName(val name: String) extends RpcAnnotation

/**
  * You can use this annotation on real RPC methods to instruct macro engine to prepend method name (or [[rpcName]] if
  * specified) with given prefix. This annotation is mostly useful when aggregated by another annotation e.g.
  *
  * {{{
  *   sealed trait RestMethod extends RpcTag
  *   final class GET extends RestMethod with AnnotationAggregate {
  *     @rpcNamePrefix("GET_") type Implied
  *   }
  * }}}
  */
class rpcNamePrefix(val prefix: String) extends RpcAnnotation

/**
  * Base trait for RPC tag annotations. Tagging gives more direct control over how real methods
  * and their parameters are matched against raw methods and their parameters.
  * For more information about method tagging, see documentation of [[methodTag]].
  * For more information about parameter tagging, see documentation of [[paramTag]].
  */
trait RpcTag extends RpcAnnotation

/**
  * May be applied on raw method parameter of type `String` to indicate that macro generated implementation of
  * `AsReal` should pass real method's RPC name as this parameter and that macro generated implementation of
  * `AsRaw` should expect real method's RPC name to be passed there.
  *
  * Macro generation of `AsRaw` implementations require that raw methods annotated as [[multi]] must take at least
  * one raw parameter annotated as [[methodName]] (it may also be aggregated into some [[composite]] parameter).
  * This is necessary to properly identify which real method should be called.
  */
final class methodName extends RawParamAnnotation

/**
  * Can be applied on raw method parameters or metadata parameters. When a parameter is annotated as `@composite`,
  * the macro engine expects its type to be a class with public primary constructor. Then, it recursively inspects its
  * constructor parameters and treats them as if they were direct parameters. This effectively groups multiple
  * raw parameters or multiple metadata parameters into a single class.
  */
final class composite extends RawParamAnnotation

/**
  * Base trait for RPC arity annotations, [[single]], [[optional]] and [[multi]].
  * Arity annotations may be used in multiple contexts:
  *
  * - raw methods
  * - raw parameters
  * - metadata parameters for raw methods and raw parameters
  * - metadata parameters that reify annotations (i.e. annotated with [[reifyAnnot]])
  *
  * See documentation of each arity annotation for more details.
  */
sealed trait RpcArity extends RawParamAnnotation

/**
  * The default arity annotation. Usually there is no need to use this annotation explicitly.
  *
  * When applied on raw method, there must be exactly one real method matching this raw method and it must have
  * the same name (or [[rpcName]]) as raw method's name.
  *
  * When applied on raw parameter, specifies that this raw parameter must be matched by exactly one real parameter,
  * on the position that matches raw parameter's position. Names are ignored because - unlike methods - parameters are
  * identified by their position in parameter list(s) rather than their name.
  *
  * By default, [[single]] raw methods and parameters are [[verbatim]] which means that the real method must have
  * exactly the same return type as raw method and real parameter must have exactly the same type as raw parameter.
  *
  * When applied on method metadata parameter or parameter metadata parameter, the rules above apply in the same way
  * except that real method/parameter type is matched against the type passed as `T` to `TypedMetadata[T]` by
  * metadata class. For example, if method metadata class extends `TypedMetadata[Unit]` then `Unit` is assumed to be
  * the result type of raw method that this metadata class represents. Similarly, when parameter metadata class
  * extends `TypedMetadata[Int]` then raw parameter represented by this metadata class is assumed to be of type `Int`.
  *
  * Finally, when applied on metadata parameter with [[reifyAnnot]], that parameter is supposed to hold exactly one
  * instance of an annotation of given type from real trait/method/param. If there is no such annotation available,
  * compilation error will be raised.
  */
final class single extends RpcArity

/**
  * When applied on raw method, it works almost the same way as [[single]] except that it is not required that
  * matching real method exists in real RPC trait. If there is no matching real method, macro-materialized `AsRaw`
  * implementation will implement the raw method with a code that throws an exception.
  *
  * When applied on raw parameter, specifies that this raw parameter may be matched by a real parameter but this is
  * not required. Whether a real parameter matches an optional raw parameter is determined by its type and/or tag
  * (see [[paramTag]] for more information on param tagging).
  *
  * Raw parameters marked as [[optional]] must be typed as `Option[T]` (or `Opt[T]`, `OptArg[T]` or whatever type that
  * has an instance of `OptionLike`). By default, [[optional]] raw parameters are [[verbatim]] which means that the
  * option-wrapped type `T` must match exactly the type of real parameter.
  *
  * In the macro generated code that translates a raw call into a real call, when the raw parameter value is absent
  * (the `Option[T]` is empty) then real parameter's default value will be used as fallback. This allows introducing
  * new parameters into RPC interfaces without breaking backwards compatibility.
  *
  * [[optional]] may also be used on method metadata parameters or parameter metadata parameters. It works the same
  * way as with [[single]] except that metadata class must be wrapped in an `OptionLike` type (`Option`, `Opt`, etc.).
  *
  * Finally, [[optional]] may also be used for metadata parameters that hold reified annotations (see [[reifyAnnot]]).
  * In that case it is not required that the annotation being reified is actually present on the real trait/method/param.
  * For that to work, metadata param must be typed as `Option[A]`, `Opt[A]`, etc. where `A` is the type of annotation
  * being reified.
  */
final class optional extends RpcArity

/**
  * When applied on raw method, specifies that this raw method may be matched by many, arbitrarily named real methods.
  * In order to distinguish between real methods when translating raw call into real call,
  * multi raw method must take real method's RPC name (a `String`) as one of its parameters (see [[methodName]]).
  * By default, result type of multi raw method is [[encoded]] and the macro engine searches for
  * appropriate `AsRaw` or `AsReal` conversion between real method result type and raw method result type.
  *
  * When applied on raw parameter, specifies that this raw parameter may be matched by arbitrary number of real
  * parameters whose values are typically [[encoded]] and collected into (or extracted from) raw parameter value.
  * The way real parameter values are collected and extracted depends on the type of raw parameter which must be
  * either:
  *
  * - an `Iterable[R]` or any subtype (e.g. `List[R]`)
  * - a `PartialFunction[String,R]` or any subtype (e.g. `Map[String,R]`)
  *
  * `R` denotes the type used to represent each real parameter value. Be default (unless [[verbatim]] is used) it means
{'fraction_non_alphanumeric': 0.06452800098141447, 'fraction_numerical': 0.0, 'mean_word_length': 4.125432254008174, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2280208', 'n_tokens_mistral': 4050, 'n_tokens_neox': 3950, 'n_words': 2245}