{"size": 5169, "ext": "scrbl", "max_stars_repo_path": "scribblings/syntax.scrbl", "max_stars_repo_name": "Hallicopter/racket-protobuf", "max_stars_repo_stars_event_min_datetime": "2021-03-15T02:48:50.000Z", "max_stars_repo_stars_event_max_datetime": "2021-03-15T02:48:50.000Z", "max_issues_repo_path": "scribblings/syntax.scrbl", "max_issues_repo_name": "Hallicopter/racket-protobuf", "max_issues_repo_issues_event_min_datetime": null, "max_issues_repo_issues_event_max_datetime": null, "max_forks_repo_path": "scribblings/syntax.scrbl", "max_forks_repo_name": "Hallicopter/racket-protobuf", "max_forks_repo_forks_event_min_datetime": null, "max_forks_repo_forks_event_max_datetime": null}
{"max_stars_count": 1, "max_issues_count": null, "max_forks_count": null, "avg_line_length": 34.6912751678, "max_line_length": 92, "alphanum_fraction": 0.692783904}
#lang scribble/manual
@require[(for-label "../syntax.rkt" "../reflection.rkt")]

@title{Syntax}

@defmodule[(lib "protobuf/syntax")]{

  Racket syntax to represent protocol buffer definitions as used by
  code output from @tt{protoc-gen-racket}.

}

@defform[(define-primitive-type name type
           reader writer)
         #:contracts
         ([reader (-> input-port? any/c)]
          [writer (-> any/c output-port? any)])]{

  Binds @racketid[primitive:]@racket[name] to an instance of
  @racket[primitive-info] using the quoted @racket[type] and the
  specified @racket[reader] and @racket[writer].

  This is an internal utility macro and should normally not be used
  since the set of primitive wire types for protocol buffers is not
  intended to be extended.

}

@deftogether[(
  @defthing[primitive:int32 primitive-info?]{}
  @defthing[primitive:int64 primitive-info?]{}
  @defthing[primitive:uint32 primitive-info?]{}
  @defthing[primitive:uint64 primitive-info?]{}
  @defthing[primitive:sint32 primitive-info?]{}
  @defthing[primitive:sint64 primitive-info?]{}
  @defthing[primitive:fixed32 primitive-info?]{}
  @defthing[primitive:fixed64 primitive-info?]{}
  @defthing[primitive:sfixed32 primitive-info?]{}
  @defthing[primitive:sfixed64 primitive-info?]{}
  @defthing[primitive:bool primitive-info?]{}
  @defthing[primitive:float primitive-info?]{}
  @defthing[primitive:double primitive-info?]{}
  @defthing[primitive:bytes primitive-info?]{}
  @defthing[primitive:string primitive-info?]{}
)]{

  The primitive protocol buffer types.

}

@deftogether[(
  @defproc[(primitive:uint* [max-size (or/c exact-positive-integer? #f)]) primitive-info?]{}
  @defproc[(primitive:sint* [max-size (or/c exact-positive-integer? #f)]) primitive-info?]{}
)]{

  Generators for variants of the primitive protocol buffer integer
  types that modify or lift the maximum encoded size restriction for
  these values.

  The @tt{protoc-gen-racket} code generator uses these types when it
  finds an @litchar{(extend.protobuf.max_size)} option on a field of
  type @litchar{uint64} or @litchar{sint64}. The @racket[max-size]
  will be the value of the option or @racket[#f] in case the option is
  zero. Protocol buffer definitions using this extension must
  @litchar{import "extend/protobuf/bigint.proto"} from this library's
  distribution.

  Note that relaxing the size restriction is not compatible with other
  implementations of protocol buffers and lifting the restriction
  entirely may also be vulnerable to denial of service attacks.

}

@defform[(define-enum-type name
           ([alt tag] ...))
         #:contracts
         ([tag exact-nonnegative-integer?])]{

  Binds @racketid[enum:]@racket[name] to an instance of
  @racket[enum-info] and defines the enumeration conversion procedures
  @racketid[integer->]@racket[name] and @racket[name]@racketid[->integer].

  Each @racket[alt] is a possible symbolic enumeration item
  corresponding to the numeric @racket[tag].

}

@defform/subs[#:literals
              (required optional repeated packed)
              (define-message-type name
                ([label type field tag . default] ...))
              ([label required optional repeated packed])
              #:contracts
              ([type (or/c primitive-info? enum-info? struct-type?)]
               [tag exact-nonnegative-integer?])]{

  Defines a structure type similar to the following code: @racketblock[
    (struct name message
      ([field #:auto] ...)
      #:transparent #:mutable
      #:auto-value (void)
      #:property prop:protobuf (delay (message-info 'name ...)))
  ]

  In addition to the unary constructor procedure @racket[name] that is
  of limited use, a variadic constructor @racket[name]@racketid[*] is
  created. This constructor accepts an optional keyword argument for
  every declared field of the message.

  The accessors generated for each field accept an additional optional
  argument to specify a default value. If the accessor is applied to
  an instance of the message type in which the field is set to
  @racket[(void)], the default value is applied in case it is a thunk
  or is returned otherwise.

  If no explicit default value is specified for a missing field, the
  accessors behave as follows:
  @itemize[
    @item{
      The accessor for a required field raises an
      @racket[exn:fail:user] error.
    }
    @item{
      The accessor for an optional field runs a default thunk with
      @racket[default].
    }
    @item{
      The accessor for a repeated (or packed repeated) field returns
      an empty list.
    }
  ]

}

@defform/subs[#:literals
              (required optional repeated packed)
              (define-message-extension name
                [label type field tag . default])
              ([label required optional repeated packed])
              #:contracts
              ([type (or/c primitive-info? enum-info? struct-type?)]
               [tag exact-nonnegative-integer?])]{

  Registers an extension field for the existing message type called
  @racket[name]. The field declaration syntax is identical to that of
  a single field in @racket[define-message-type].

}
