compiler/objectivec/names.h

0001 // Protocol Buffers - Google's data interchange format
0002 // Copyright 2008 Google Inc.  All rights reserved.
0003 //
0004 // Use of this source code is governed by a BSD-style
0005 // license that can be found in the LICENSE file or at
0006 // https://developers.google.com/open-source/licenses/bsd
0007
0008 // Helper functions for generating ObjectiveC code.
0009
0010 #ifndef GOOGLE_PROTOBUF_COMPILER_OBJECTIVEC_NAMES_H__
0011 #define GOOGLE_PROTOBUF_COMPILER_OBJECTIVEC_NAMES_H__
0012
0013 #include <string>
0014 #include <vector>
0015
0016 #include "absl/strings/string_view.h"
0017 #include "google/protobuf/descriptor.h"
0018
0019 // Must be included last
0020 #include "google/protobuf/port_def.inc"
0021
0022 namespace google {
0023 namespace protobuf {
0024 namespace compiler {
0025 namespace objectivec {
0026
0027 // Get/Set the path to a file to load for objc class prefix lookups.
0028 PROTOC_EXPORT absl::string_view GetPackageToPrefixMappingsPath();
0029 PROTOC_EXPORT void SetPackageToPrefixMappingsPath(absl::string_view file_path);
0030 // Get/Set if the proto package should be used to make the default prefix for
0031 // symbols. This will then impact most of the type naming apis below. It is done
0032 // as a global to not break any other generator reusing the methods since they
0033 // are exported.
0034 PROTOC_EXPORT bool UseProtoPackageAsDefaultPrefix();
0035 PROTOC_EXPORT void SetUseProtoPackageAsDefaultPrefix(bool on_or_off);
0036 // Get/Set the path to a file to load as exceptions when
0037 // `UseProtoPackageAsDefaultPrefix()` is `true`. An empty string means there
0038 // should be no exceptions.
0039 PROTOC_EXPORT absl::string_view GetProtoPackagePrefixExceptionList();
0040 PROTOC_EXPORT void SetProtoPackagePrefixExceptionList(
0041     absl::string_view file_path);
0042 // Get/Set a prefix to add before the prefix generated from the package name.
0043 // This is only used when UseProtoPackageAsDefaultPrefix() is True.
0044 PROTOC_EXPORT absl::string_view GetForcedPackagePrefix();
0045 PROTOC_EXPORT void SetForcedPackagePrefix(absl::string_view prefix);
0046
0047 // Returns true if the name requires a ns_returns_not_retained attribute applied
0048 // to it.
0049 PROTOC_EXPORT bool IsRetainedName(absl::string_view name);
0050
0051 // Returns true if the name starts with "init" and will need to have special
0052 // handling under ARC.
0053 PROTOC_EXPORT bool IsInitName(absl::string_view name);
0054
0055 // Returns true if the name requires a cf_returns_not_retained attribute applied
0056 // to it.
0057 PROTOC_EXPORT bool IsCreateName(absl::string_view name);
0058
0059 // Gets the objc_class_prefix or the prefix made from the proto package.
0060 PROTOC_EXPORT std::string FileClassPrefix(const FileDescriptor* file);
0061
0062 // Gets the path of the file we're going to generate (sans the .pb.h
0063 // extension).  The path will be dependent on the objectivec package
0064 // declared in the proto package.
0065 PROTOC_EXPORT std::string FilePath(const FileDescriptor* file);
0066
0067 // Just like FilePath(), but without the directory part.
0068 PROTOC_EXPORT std::string FilePathBasename(const FileDescriptor* file);
0069
0070 // Gets the name of the root class we'll generate in the file.  This class
0071 // is not meant for external consumption, but instead contains helpers that
0072 // the rest of the classes need
0073 PROTOC_EXPORT std::string FileClassName(const FileDescriptor* file);
0074
0075 // These return the fully-qualified class name corresponding to the given
0076 // descriptor.
0077 PROTOC_EXPORT std::string ClassName(const Descriptor* descriptor);
0078 PROTOC_EXPORT std::string ClassName(const Descriptor* descriptor,
0079                                     std::string* out_suffix_added);
0080 PROTOC_EXPORT std::string EnumName(const EnumDescriptor* descriptor);
0081
0082 // Returns the fully-qualified name of the enum value corresponding to the
0083 // the descriptor.
0084 PROTOC_EXPORT std::string EnumValueName(const EnumValueDescriptor* descriptor);
0085
0086 // Returns the name of the enum value corresponding to the descriptor.
0087 PROTOC_EXPORT std::string EnumValueShortName(
0088     const EnumValueDescriptor* descriptor);
0089
0090 // Reverse what an enum does.
0091 PROTOC_EXPORT std::string UnCamelCaseEnumShortName(absl::string_view name);
0092
0093 // Returns the name to use for the extension (used as the method off the file's
0094 // Root class).
0095 PROTOC_EXPORT std::string ExtensionMethodName(
0096     const FieldDescriptor* descriptor);
0097
0098 // Returns the transformed field name.
0099 PROTOC_EXPORT std::string FieldName(const FieldDescriptor* field);
0100 PROTOC_EXPORT std::string FieldNameCapitalized(const FieldDescriptor* field);
0101
0102 // The formatting options for FieldObjCType
0103 enum FieldObjCTypeOptions : unsigned int {
0104   // No options.
0105   kFieldObjCTypeOptions_None = 0,
0106   // Leave off the lightweight generics from any collection classes.
0107   kFieldObjCTypeOptions_OmitLightweightGenerics = 1 << 0,
0108   // For things that are pointers, include a space before the `*`.
0109   kFieldObjCTypeOptions_IncludeSpaceBeforeStar = 1 << 1,
0110   // For things that are basic types (int, float, etc.), include a space after
0111   // the type, needed for some usage cases. This is mainly needed when using the
0112   // type to declare variables. Pointers don't need the space to generate valid
0113   // code.
0114   kFieldObjCTypeOptions_IncludeSpaceAfterBasicTypes = 1 << 2,
0115 };
0116
0117 // This returns the ObjC type for the field. `options` allows some controls on
0118 // how the string is created for different usages.
0119 PROTOC_EXPORT std::string FieldObjCType(
0120     const FieldDescriptor* field,
0121     FieldObjCTypeOptions options = kFieldObjCTypeOptions_None);
0122
0123 // Returns the transformed oneof name.
0124 PROTOC_EXPORT std::string OneofEnumName(const OneofDescriptor* descriptor);
0125 PROTOC_EXPORT std::string OneofName(const OneofDescriptor* descriptor);
0126 PROTOC_EXPORT std::string OneofNameCapitalized(
0127     const OneofDescriptor* descriptor);
0128
0129 // Reverse of the above.
0130 PROTOC_EXPORT std::string UnCamelCaseFieldName(absl::string_view name,
0131                                                const FieldDescriptor* field);
0132
0133 // The name the commonly used by the library when built as a framework.
0134 // This lines up to the name used in the CocoaPod.
0135 extern PROTOC_EXPORT const char* const ProtobufLibraryFrameworkName;
0136 // Returns the CPP symbol name to use as the gate for framework style imports
0137 // for the given framework name to use.
0138 PROTOC_EXPORT std::string ProtobufFrameworkImportSymbol(
0139     absl::string_view framework_name);
0140
0141 // ---------------------------------------------------------------------------
0142
0143 // These aren't really "naming" related, but can be useful for something
0144 // building on top of ObjC Protos to be able to share the knowledge/enforcement.
0145
0146 // Checks if the file is one of the proto's bundled with the library.
0147 PROTOC_EXPORT bool IsProtobufLibraryBundledProtoFile(
0148     const FileDescriptor* file);
0149
0150 // Generator Prefix Validation Options (see generator.cc for a
0151 // description of each):
0152 struct Options {
0153   Options();
0154   std::string expected_prefixes_path;
0155   std::vector<std::string> expected_prefixes_suppressions;
0156   bool prefixes_must_be_registered;
0157   bool require_prefixes;
0158 };
0159
0160 // Checks the prefix for the given files and outputs any warnings as needed. If
0161 // there are flat out errors, then out_error is filled in with the first error
0162 // and the result is false.
0163 PROTOC_EXPORT bool ValidateObjCClassPrefixes(
0164     const std::vector<const FileDescriptor*>& files,
0165     const Options& validation_options, std::string* out_error);
0166 // Same was the other ValidateObjCClassPrefixes() calls, but the options all
0167 // come from the environment variables.
0168 PROTOC_EXPORT bool ValidateObjCClassPrefixes(
0169     const std::vector<const FileDescriptor*>& files, std::string* out_error);
0170
0171 }  // namespace objectivec
0172 }  // namespace compiler
0173 }  // namespace protobuf
0174 }  // namespace google
0175
0176 #include "google/protobuf/port_undef.inc"
0177
0178 #endif  // GOOGLE_PROTOBUF_COMPILER_OBJECTIVEC_NAMES_H__