piqi.protobuf.piqi

% Copyright 2009, 2010, 2011, 2012, 2013, 2017, 2018 Anton Lavrik
%
% Licensed under the Apache License, Version 2.0 (the "License");
% you may not use this file except in compliance with the License.
% You may obtain a copy of the License at
%
%     http://www.apache.org/licenses/LICENSE-2.0
%
% Unless required by applicable law or agreed to in writing, software
% distributed under the License is distributed on an "AS IS" BASIS,
% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
% See the License for the specific language governing permissions and
% limitations under the License.


% Google Protocol Buffers extension for Piqi self-spec
%
% This file defines two kinds of extensions to the base Piqi self-specification:
%
%   - properties related to Protocol Buffer's .proto files that are used by
%     "piqi to-proto" command
%
%   - properties related to binary binary Google Protocol Buffers format also
%     known as wire format
%
%
% The document describing Protocol Buffers binary "wire" format:
%
%   https://developers.google.com/protocol-buffers/docs/encoding


.protobuf-package "piqi_org.piqi"


.include [ .module piqi ]


%
% mapping between Piqi primitive and Protobuf types
%

.extend [
    .typedef int

    .with.protobuf-type "sint32"
    .with.protobuf-wire-type.zigzag-varint
]

.extend [
    .typedef uint

    .with.protobuf-type "uint32"
    .with.protobuf-wire-type.varint
]

.extend [
    .typedef int32

    .with.protobuf-type "sint32"
    .with.protobuf-wire-type.zigzag-varint
]

.extend [
    .typedef uint32

    .with.protobuf-type "uint32"
    .with.protobuf-wire-type.varint
]

.extend [
    .typedef int64

    .with.protobuf-type "sint64"
    .with.protobuf-wire-type.zigzag-varint
]

.extend [
    .typedef uint64

    .with.protobuf-type "uint64"
    .with.protobuf-wire-type.varint
]

.extend [
    .typedef int32-fixed

    .with.protobuf-type "sfixed32"
    .with.protobuf-wire-type.signed-fixed32
]

.extend [
    .typedef uint32-fixed

    .with.protobuf-type "fixed32"
    .with.protobuf-wire-type.fixed32
]

.extend [
    .typedef int64-fixed

    .with.protobuf-type "sfixed64"
    .with.protobuf-wire-type.signed-fixed64
]

.extend [
    .typedef uint64-fixed

    .with.protobuf-type "fixed64"
    .with.protobuf-wire-type.fixed64
]

.extend [
    .typedef float64

    .with.protobuf-type "double"
    .with.protobuf-wire-type.fixed64
]

.extend [
    .typedef float32

    .with.protobuf-type "float"
    .with.protobuf-wire-type.fixed32
]

% These two types are specific to Protocol Buffers. They have the same
% on-the-wire representation as uint32/64. The difference is that they allow
% negative integers (which representation is very inefficient requiring many
% bytes for small absolue values).
.alias [
    .name protobuf-int32
    .type int32
    .piqi-type.int

    .protobuf-type "int32"
    .protobuf-wire-type.signed-varint
]

.alias [
    .name protobuf-int64
    .type int64
    .piqi-type.int

    .protobuf-type "int64"
    .protobuf-wire-type.signed-varint
]


%
% properties specific to .piqi to .proto conversion
%

.extend [
    .typedef* [ record field variant option enum alias list ]

    .with.field [
        .name protobuf-name
        .type string
        .optional
    ]
]


.extend [
    .typedef* [ piqi record variant list enum ]

    .with.field [
        % arbitrary string that will be included in .proto message and enum
        % definitions as a result of .piqi -> .proto conversion

        .name protobuf-custom
        .type string
        .repeated
    ]
]


.extend [
    .typedef piqi

    .with.field [
        .name protobuf-package
        .type string
        .optional
    ]
]


.extend [
    .typedef alias

    .with.field [
        .name protobuf-type
        .type string
        .optional
    ]
]


.extend [
    .typedef enum

    .with.field [
        % prefix each enum option's name with the specified string; it helps to
        % deal with the fact that enum doesn't form a C++ namespace meaning that
        % enum constants are defined directly in the outer namespace; it was
        % announced that this problem will be fixed in protobuf-2.5

        .name protobuf-prefix
        .type string
        .optional
    ]
]


%
% definitions and extensions related to how data is represented on the wire
%

.enum [
    .name protobuf-wire-type

    .option [ varint ]
    .option [ zigzag-varint ]
    .option [ fixed32 ]
    .option [ fixed64 ]
    .option [ signed-varint ]
    .option [ signed-fixed32 ]
    .option [ signed-fixed64 ]
    .option [ block ]
]


.extend [
    .typedef alias

    .with.field [
        .type protobuf-wire-type
        .optional
    ]
]


.extend [
    .typedef* [ field option ]

    .with.field [
        % for fields and variant options: unique integer field id
        % from (1 -- (2^29-1)) range used for identifying individual fields and
        % options encoded in wire format
        %
        % for enum options: non-unique integer constant from a full int32 range

        .name code
        .type int32
        .optional
    ]
]


.extend [
    .typedef* [ field list ]

    % indication that Protobuf "packed" format is used for repeated fields or
    % list elements
    .with.field [
        .name protobuf-packed
        .optional
    ]
]


.extend [
    .typedef variant

    % specifies the name for the protobuf "oneof", when present "piqi to-proto"
    % wraps all variant options into protobuf's oneof construct:
    %
    %   oneof <name> { <options> }
    %
    .with.field [
        .name protobuf-oneof
        .type string
        .optional
    ]
]