Module gpb_defs

Operations on definitions.

Description

Operations on definitions

Data Types

def()

def() = 
    {proto_defs_version, version()} |
    {{msg, Name :: atom()}, [field()]} |
    {{group, Name :: atom()}, [field()]} |
    {{enum, Name :: atom()},
     [{Sym :: atom(), Value :: integer()} |
      {option, Name :: atom(), Val :: term()}] |
     [{Sym :: atom(), Value :: integer(), [Opt :: ee_option()]}]} |
    {{service, Name :: atom()},
     [#rpc{name = atom() | undefined,
           input = any(),
           output = any(),
           input_stream = boolean() | undefined,
           output_stream = boolean() | undefined,
           opts = [term()] | undefined}]} |
    {package, Name :: atom()} |
    {syntax, string()} |
    {{extensions, MsgName :: atom()}, [field_number_extension()]} |
    {{extend, MsgName :: atom()}, MoreFields :: [field()]} |
    {{ext_origin, MsgName :: atom()},
     {atom(), MoreFields :: [field()]}} |
    {proto3_msgs, [MsgName :: atom()]} |
    {{reserved_numbers, MsgName :: atom()}, [reserved_num()]} |
    {{reserved_names, MsgName :: atom()}, [FieldName :: atom()]} |
    {import, ProtoFile :: string()} |
    {{msg_options, MsgName :: atom()}, [msg_option()]} |
    {{enum_options, MsgName :: atom()}, [enum_option()]} |
    {{service_options, MsgName :: atom()}, [service_option()]} |
    {{msg_containment, ProtoName :: string()},
     [MsgName :: atom()]} |
    {{pkg_containment, ProtoName :: string()}, PkgName :: atom()} |
    {{service_containment, ProtoName :: string()},
     [ServiceName :: atom()]} |
    {{rpc_containment, ProtoName :: string()},
     [{ServiceName :: atom(), RpcName :: atom()}]} |
    {{enum_containment, ProtoName :: string()},
     [EnumName :: atom()]} |
    {file, {BaseSansExt :: string(), Base :: string()}}

defs()

defs() = [def()]

ee_option()

ee_option() = 
    {atom() | [NameComponent :: atom()], OptionValue :: term()}

enum_option()

enum_option() = 
    {atom() | [NameComponent :: atom()], OptionValue :: term()}

field()

field() = 
    #field{name = atom() | undefined,
           fnum = integer() | undefined,
           rnum = pos_integer() | undefined,
           type =
               gpb_field_type() |
               gpb_internal_intermediary_ref() |
               gpb_internal_intermediary_map_ref() |
               undefined,
           occurrence =
               required | optional | repeated | defaulty |
               undefined,
           opts = [term()]} |
    #gpb_oneof{name = atom() | undefined,
               rnum = pos_integer() | undefined,
               fields =
                   [#field{name = atom() | undefined,
                           fnum = integer() | undefined,
                           rnum = pos_integer() | undefined,
                           type =
                               gpb_field_type() |
                               gpb_internal_intermediary_ref() |
                               gpb_internal_intermediary_map_ref() |
                               undefined,
                           occurrence =
                               required | optional | repeated |
                               defaulty | undefined,
                           opts = [term()]}] |
                   undefined,
               opts = [term()]}

field_number_extension()

field_number_extension() = 
    {Lower :: integer(), Upper :: integer() | max}

gpb_field_type()

gpb_field_type() = 
    int32 | int64 | uint32 | uint64 | sint32 | sint64 | fixed32 |
    fixed64 | sfixed32 | sfixed64 | bool | float | double |
    string | bytes |
    {enum, atom()} |
    {msg, atom()} |
    {group, atom()} |
    {map, gpb_map_key(), gpb_map_value()} |
    unknown

gpb_internal_intermediary_map_ref()

gpb_internal_intermediary_map_ref() = 
    {map,
     gpb_map_key(),
     gpb_map_value() | gpb_internal_intermediary_ref()}

gpb_internal_intermediary_ref()

gpb_internal_intermediary_ref() = 
    {ref, term()} |
    {msg, list()} |
    {group, list()} |
    {enum, list()}

gpb_map_key()

gpb_map_key() = 
    int32 | int64 | uint32 | uint64 | sint32 | sint64 | fixed32 |
    fixed64 | sfixed32 | sfixed64 | bool | string

gpb_map_value()

gpb_map_value() = gpb_scalar() | {enum, atom()} | {msg, atom()}

gpb_scalar()

gpb_scalar() = 
    int32 | int64 | uint32 | uint64 | sint32 | sint64 | fixed32 |
    fixed64 | sfixed32 | sfixed64 | bool | float | double |
    string | bytes

msg_option()

msg_option() = 
    {[NameComponent :: atom()], OptionValue :: term()}

reserved_num()

reserved_num() = 
    integer() | {Lower :: integer(), Upprt :: integer() | max}

service_option()

service_option() = 
    {atom() | [NameComponent :: atom()], OptionValue :: term()}

version()

version() = integer()

Function Index

convert_defs_from_latest_version/2Convert proto definitions on the latest format to some earlier format.
convert_defs_to_latest_version/1Convert proto definitions from some format found in the definitions, into the latest version for internal use within gpb.
earliest_supported_defs_version/0Return the earliest supported proto defs version.
fetch_imports/1Fetch the imported files.
format_error/1
latest_defs_version/0Return the number of the latest proto defs version.
rootward_names/2
supported_defs_versions/0Return a list of supported versions of the definition format.

Function Details

convert_defs_from_latest_version/2

convert_defs_from_latest_version(Defs, TargetVersion :: version()) ->
                                    {ok, Defs} | {error, term()}

Convert proto definitions on the latest format to some earlier format.

convert_defs_to_latest_version/1

convert_defs_to_latest_version(Defs) ->
                                  {ok, Defs} | {error, term()}

Convert proto definitions from some format found in the definitions, into the latest version for internal use within gpb.

earliest_supported_defs_version/0

earliest_supported_defs_version() -> any()

Return the earliest supported proto defs version.

fetch_imports/1

fetch_imports(Defs :: defs()) -> [ProtoFile :: string()]

Fetch the imported files.

format_error/1

format_error(Reason) -> any()

latest_defs_version/0

latest_defs_version() -> any()

Return the number of the latest proto defs version.

rootward_names/2

rootward_names(Path, Name) -> any()

supported_defs_versions/0

supported_defs_versions() -> [version()]

Return a list of supported versions of the definition format.

The format is currently a list of tuples, most are 2-tuples.

A new version means a non-backwards-compatible version change.

Even when the version number has not changed, there may still be differences, but only backwards compatible changes.

See file doc/dev-guide/proto-defs-versions.md for more info.

Format versions obey the Erlang term order and be compared like normal Erlang terms with for instance =<.


Generated by EDoc