44966442.f1ad2ae6.js

(window.webpackJsonp=window.webpackJsonp||[]).push([[21],{119:function(e,t,n){"use strict";n.d(t,"a",(function(){return u})),n.d(t,"b",(function(){return d}));var o=n(0),r=n.n(o);function s(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);t&&(o=o.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,o)}return n}function i(e){for(var t=1;t<arguments.length;t++){var n=null!=arguments[t]?arguments[t]:{};t%2?a(Object(n),!0).forEach((function(t){s(e,t,n[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(n)):a(Object(n)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(n,t))}))}return e}function p(e,t){if(null==e)return{};var n,o,r=function(e,t){if(null==e)return{};var n,o,r={},s=Object.keys(e);for(o=0;o<s.length;o++)n=s[o],t.indexOf(n)>=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var s=Object.getOwnPropertySymbols(e);for(o=0;o<s.length;o++)n=s[o],t.indexOf(n)>=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var c=r.a.createContext({}),l=function(e){var t=r.a.useContext(c),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},u=function(e){var t=l(e.components);return r.a.createElement(c.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return r.a.createElement(r.a.Fragment,{},t)}},b=r.a.forwardRef((function(e,t){var n=e.components,o=e.mdxType,s=e.originalType,a=e.parentName,c=p(e,["components","mdxType","originalType","parentName"]),u=l(n),b=o,d=u["".concat(a,".").concat(b)]||u[b]||m[b]||s;return n?r.a.createElement(d,i(i({ref:t},c),{},{components:n})):r.a.createElement(d,i({ref:t},c))}));function d(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var s=n.length,a=new Array(s);a[0]=b;var i={};for(var p in t)hasOwnProperty.call(t,p)&&(i[p]=t[p]);i.originalType=e,i.mdxType="string"==typeof e?e:o,a[1]=i;for(var c=2;c<s;c++)a[c]=n[c];return r.a.createElement.apply(null,a)}return r.a.createElement.apply(null,n)}b.displayName="MDXCreateElement"},89:function(e,t,n){"use strict";n.r(t),n.d(t,"frontMatter",(function(){return i})),n.d(t,"metadata",(function(){return p})),n.d(t,"toc",(function(){return c})),n.d(t,"default",(function(){return u}));var o=n(3),r=n(7),s=(n(0),n(119)),a=["components"],i={title:"Defining custom options",sidebar_label:"User-defined options",layout:"docs"},p={unversionedId:"user_defined_options",id:"user_defined_options",isDocsHomePage:!1,title:"Defining custom options",description:"ScalaPB allows you to define custom options you can use to annotate any",source:"@site/../docs/target/mdoc/user_defined_options.md",slug:"/user_defined_options",permalink:"/docs/user_defined_options",version:"current",sidebar_label:"User-defined options",sidebar:"someSidebar",previous:{title:"Sealed oneofs",permalink:"/docs/sealed-oneofs"},next:{title:"gRPC",permalink:"/docs/grpc"}},c=[{value:"Define your options",id:"define-your-options",children:[]},{value:"Example code",id:"example-code",children:[]}],l={toc:c};function u(e){var t=e.components,n=Object(r.a)(e,a);return Object(s.b)("wrapper",Object(o.a)({},l,n,{components:t,mdxType:"MDXLayout"}),Object(s.b)("p",null,"ScalaPB allows you to define custom options you can use to annotate any\nelement in a proto file, and access these annotations at run time."),Object(s.b)("p",null,"Learn more about ",Object(s.b)("a",{parentName:"p",href:"https://developers.google.com/protocol-buffers/docs/proto#custom_options"},"custom options"),"."),Object(s.b)("h2",{id:"define-your-options"},"Define your options"),Object(s.b)("p",null,"In ",Object(s.b)("inlineCode",{parentName:"p"},"my_opts.proto"),":"),Object(s.b)("pre",null,Object(s.b)("code",{parentName:"pre",className:"language-protobuf"},'syntax = "proto2";\n\npackage custom_options;\n\nimport "google/protobuf/descriptor.proto";\n\nextend google.protobuf.FileOptions {\n  optional string my_file_option = 50000;\n}\n\nmessage MyMessageOption {\n  optional int32 priority = 1;\n}\n\nextend google.protobuf.MessageOptions {\n  optional MyMessageOption my_message_option = 50001;\n}\n\nmessage Tag {\n  optional string name = 1;\n}\n\n// Extensions can be defined inside messages,\n// But there is no relationship between the enclosing message and the\n// extension - it only uses for namespace purposes.\nmessage Wrapper {\n  extend google.protobuf.FieldOptions {\n    repeated Tag tags = 50003;\n  }\n}\n')),Object(s.b)("p",null,"Use the options like this:"),Object(s.b)("pre",null,Object(s.b)("code",{parentName:"pre",className:"language-protobuf"},'syntax = "proto2";\n\npackage custom_options;\n\nimport "custom_options/my_opts.proto";\n\noption (my_file_option) = "hello!";\n\nmessage OneMessage {\n    option (my_message_option).priority = 17;\n\n    // Field level option, with repeated field.\n    optional int32 number = 1 [(Wrapper.tags) = {name: "tag1"},\n                               (Wrapper.tags) = {name: "tag2"}];\n}\n')),Object(s.b)("p",null,"Extensions that are defined at file scope are generated under the descriptor\nproto (usually name ",Object(s.b)("inlineCode",{parentName:"p"},"FileNameProto"),"). Otherwise, the extension is defined in\nthe companion object of the containing class."),Object(s.b)("p",null,"To access the option value of an element, you need to obtain its descriptor:"),Object(s.b)("pre",null,Object(s.b)("code",{parentName:"pre",className:"language-scala"},'assert(\n  my_opts.CustomOptionsMyOptsProto.myFileOption.get(\n    use_opts.CustomOptionsUseOptsProto.scalaDescriptor.getOptions) ==\n      Some("hello!"))\n\nassert(\n  my_opts.CustomOptionsMyOptsProto.myMessageOption.get(\n    use_opts.OneMessage.scalaDescriptor.getOptions).get ==\n      my_opts.MyMessageOption().update(_.priority := 17))\n\nval numberField = use_opts.OneMessage.descriptor.findFieldByName(\n  "number").get\n\nassert(\n  my_opts.Wrapper.tags.get(\n    numberField.getOptions) == Seq(\n      my_opts.Tag(name = Some("tag1")),\n      my_opts.Tag(name = Some("tag2"))))\n')),Object(s.b)("p",null,"If you prefer to start with the descriptor, you use can the ",Object(s.b)("inlineCode",{parentName:"p"},"extension"),"\nmethod:"),Object(s.b)("pre",null,Object(s.b)("code",{parentName:"pre",className:"language-scala"},'assert(use_opts.CustomOptionsUseOptsProto.scalaDescriptor.getOptions.extension(\n  my_opts.CustomOptionsMyOptsProto.myFileOption) == Some("hello!"))\n\nassert(use_opts.OneMessage.scalaDescriptor.getOptions.extension(\n  my_opts.CustomOptionsMyOptsProto.myMessageOption).get ==\n      my_opts.MyMessageOption().update(_.priority := 17))\n\nassert(numberField.getOptions.extension(\n  my_opts.Wrapper.tags) == Seq(\n      my_opts.Tag(name = Some("tag1")),\n      my_opts.Tag(name = Some("tag2"))))\n')),Object(s.b)("h2",{id:"example-code"},"Example code"),Object(s.b)("p",null,"The full source code of this example is available below:"),Object(s.b)("ul",null,Object(s.b)("li",{parentName:"ul"},Object(s.b)("a",{parentName:"li",href:"https://github.com/scalapb/ScalaPB/tree/master/examples/custom_options/src/main/protobuf/custom_options"},"Protobufs")),Object(s.b)("li",{parentName:"ul"},Object(s.b)("a",{parentName:"li",href:"https://github.com/scalapb/ScalaPB/tree/master/examples/custom_options/src/main/scala/custom_options"},"Scala"))))}u.isMDXComponent=!0}}]);