The results might not be what you expect. +
-The %feature directive follows the same name matching rules -as the %rename directive (which is in fact just a special -form of %feature). This means that features can be applied with +The name matching rules outlined in the Ambiguity resolution and renaming +section applies to all %feature directives. +In fact the the %rename directive is just a special form of %feature. +The matching rules mean that features are very flexible and can be applied with pinpoint accuracy to specific declarations if needed. -
- --When a feature is defined, it is given a name and a value. Most commonly, the -value is supplied after the declaration name as shown for the "except" -example above. However, if the feature is simple, a value might be supplied -as an extra argument as shown for the "new" feature. -
- --A feature stays in effect until it is explicitly disabled. A feature is disabled by -supplying a %feature directive with no value. For example: -
- -
-%feature("except") Object::allocate; // Removes any previously defined feature
-
--If no declaration name is given, a global feature is defined. This feature is then +Additionally, if no declaration name is given, a global feature is said to be defined. +This feature is then attached to every declaration that follows. This is how global exception handlers are defined. For example:
@@ -635,9 +620,6 @@ are defined. For example: } ... bunch of declarations ... - -/* Disable the exception handler */ -%feature("except"); @@ -664,10 +646,10 @@ The following is the generic syntax for features:
-%feature("name","value", attribute1="AttibuteValue1") symbol;
-%feature("name", attribute1="AttibuteValue1") symbol {value};
-%feature("name", attribute1="AttibuteValue1") symbol %{value%};
-%feature("name", attribute1="AttibuteValue1") symbol "value";
+%feature("name","value", attribute1="AttributeValue1") symbol;
+%feature("name", attribute1="AttributeValue1") symbol {value};
+%feature("name", attribute1="AttributeValue1") symbol %{value%};
+%feature("name", attribute1="AttributeValue1") symbol "value";
+Feature flags are used to enable or disable a particular feature. Feature flags are a common but simple usage of %feature +and the feature value should be either 1 to enable or 0 to disable the feature. +
+ +
+%feature("name") // enables feature
+%feature("name", "1") // enables feature
+%feature("name", "x") // enables feature
+%feature("name", "0") // disables feature
+%feature("name", "") // clears feature
+
++Actually any value other than zero will enable the feature. +Note that if the value is omitted completely, the default value becomes 1, thereby enabling the feature. +A feature is cleared by specifying no value, see Clearing features. +The %immutable directive described in the Creating read-only variables section, +is just a macro for %feature("immutable"), and can be used to demonstrates feature flags: +
+ +
+ // features are disabled by default
+int red; // mutable
+
+%feature("immutable"); // global enable
+int orange; // immutable
+
+%feature("immutable","0"); // global disable
+int yellow; // mutable
+
+%feature("immutable","1"); // another form of global enable
+int green; // immutable
+
+%feature("immutable",""); // clears the global feature
+int blue; // mutable
+
++Note that features are disabled by default and must be explicitly enabled either globally or by specifying a targeted declaration. +The above intersperses SWIG directives with C code. Of course you can target features explicitly, so the above could also be rewritten as: +
+ +
+%feature("immutable","1") orange;
+%feature("immutable","1") green;
+int red; // mutable
+int orange; // immutable
+int yellow; // mutable
+int green; // immutable
+int blue; // mutable
+
++The above approach allows for the C declarations to be separated from the SWIG directives for when the C declarations are parsed from a C header file. +The logic above can of course be inverted and rewritten as: +
+ +
+%feature("immutable","1");
+%feature("immutable","0") red;
+%feature("immutable","0") yellow;
+%feature("immutable","0") blue;
+int red; // mutable
+int orange; // immutable
+int yellow; // mutable
+int green; // immutable
+int blue; // mutable
+
++A feature stays in effect until it is explicitly cleared. A feature is cleared by +supplying a %feature directive with no value. For example %feature("name",""). +A cleared feature means that any feature exactly matching any previously defined feature is no longer used in the name matching rules. +So if a feature is cleared, it might mean that another name matching rule will apply. +To clarify, let's consider the except feature again (%exception): +
+ +
+// Define global exception handler
+%feature("except") {
+ try {
+ $action
+ } catch (...) {
+ croak("Unknown C++ exception");
+ }
+}
+
+// Define exception handler for all clone methods to log the method calls
+%feature("except") *::clone() {
+ try {
+ logger.info("$action");
+ $action
+ } catch (...) {
+ croak("Unknown C++ exception");
+ }
+}
+
+... initial set of class declarations with clone methods ...
+
+// clear the previously defined feature
+%feature("except","") *::clone();
+
+... final set of class declarations with clone methods ...
+
++In the above scenario, the initial set of clone methods will log all method invocations from the target language. +This specific feature is cleared for the final set of clone methods. +However, these clone methods will still have an exception handler (without logging) as the next best feature match for them is the global exception handler. +
+ ++Note that clearing a feature is not always the same as disabling it. +Clearing the feature above with %feature("except","") *::clone() is not the same as specifying +%feature("except","0") *::clone(). The former will disable the feature for clone methods - +the feature is still a better match than the global feature. +If on the other hand, no global exception handler had been defined at all, +then clearing the feature would be the same as disabling it as no other feature would have matched. +
+ ++Note that the feature must match exactly for it to be cleared by any previously defined feature. +For example the following attempt to clear the initial feature will not work: +
+ +
+%feature("except") clone() { logger.info("$action"); $action }
+%feature("except","") *::clone();
+
++but this will: +
+ +
+%feature("except") clone() { logger.info("$action"); $action }
+%feature("except","") clone();
+
+@@ -710,7 +853,7 @@ For example:
-%feature("except") void hello(int i=0, double d=0.0);
+%feature("except") void hello(int i=0, double d=0.0) { ... }
void hello(int i=0, double d=0.0);
-%feature("except") void hello(int i, double d);
+%feature("except") void hello(int i, double d) { ... }
void hello(int i=0, double d=0.0);