Technical Documents

Increasing Authoring Capabilities by Linking to a Function

The example below shows readers a simple example of how to add an Eclipse function which will allow users to reference exponents when creating statements. Once added users can then author statements such as, "a number to the power of another number." Authority will now be able to use this added function when performing code generation.

To use an Eclipse function like "pow", the first step is to tell Authority that the function exists and that you want to use it. The process begins by linking to an external function under the Implementation Details node of the Knowledge Browser. Navigate to the Eclipse Procedures node, and right-click to Add a procedure...

This opens the Procedure dialog, which looks complex but really isn't. In the name field, type the exact name of the Eclipse procedure you wish to use. In this example the user will type in "pow". Please note that there is no error checking at this point, so you will need to be precisely correct.

Additionally, most of the fields present on this dialog are inactive for an Eclipse procedure, but Authority does need to know whether this procedure has side-effects. In other words, does it simply return a value, or does it change something? In this example the function changes nothing.

Next, since it is intended to use the return value of "pow", we will declare it to be not nullable.

Finally, Authority will need a list and name of the procedure's parameters. Include the input parameters only. At this time the return value does not need to be mentioned. In this example, the first parameter is the base, and the second is the exponent. Once again, there is no error checking at this time, so be sure to use the correct number of parameters in the correct order.

At this point Authority is aware of the "pow" function and its parameters. Click OK to close this dialog box.

The "pow" procedure is now listed as an available Eclipse resource. Authority displays ELEMENT "pow" because every Eclipse procedure returns an ELEMENT datatype. An element is simply one of the symbols, numbers or strings one sees inside an Eclipse fact.

Defining a Procedural Relation

Right-click the "pow" procedure and select Add a relation.

It is best to follow this path when creating a relation for a procedure because Authority sets up the Add/Edit Relation dialog with several appropriate defaults.

The name of the relation can be the same as the name of the procedure, which is "pow" in this case. This will avoid confusion downstream.

The user will now choose a type of procedure in the Type area. The choices are function, predicate and action. As explained earlier, a function returns a useful value (such as a sum) but has no side-effects. A predicate is a true/false test, again without side-effects. An action is a procedure with a side-effect, but makes something happen, such as writing results to a database of XML file. In this example, the "pow" procedure is a function because it returns a numeric value without creating any side-effects.

In the Roles list the user will find that Authority has automatically inserted a result value for this procedure. It has also included the two input parameters we defined in the previous dialog box, labeling both of them as values.

However, the user will need to modify the concepts and should not label them as values, but as real numbers.

Select the concept and click the Edit button.

Choose Select-Number-Decimal Number-Real Number. Hit OK.

You will need to do this for all concepts listed.

Up to this point, defining a relation for an external procedure has been very simple. It becomes more challenging when you enter the last phase, which is defining a verb phrasing for the relation.

Phrasing a Procedural Relation

When creating a phrasing for a procedural relation, users will sometimes have to "think outside of the box." Procedures will seem to require constructions that don't fit the subject-verb-object pattern. Eclipse relations will also require the same "outside of the box thinking."

From the Add/Edit Relation dialog for the relation "pow", click the New phrasing button. This pulls up the New/Edit Phrasing dialog with the first two values (result and base) cast as the subject and the direct object. The default verb is has.

What do we want this phrasing to say? The most natural phrasing would say, "the result is the base to the power of the exponent." In this type of situation, Authority insists on using "a first value, a second value, and a third value" as its preferred noun phrases. Therefore the target phrasing is "a first value is a second value to the power of a third value."

The first step is to change "has" to "is."

What remains to add to this phrasing? "A first value is a second value to the power of a third value." Notice that there are two remaining prepositional phrases to add. The first one, "to the power," is purely syntactic. It does not map into any element of the relation. The second one, "of a third value," maps into the exponent parameter.

Let's add the syntactic phrase "to the power." Click the New grammatical role button, which pops up the Grammatical Role dialog box.

By default, Authority assumes that the user wants to add the missing third value. The erroneous assumption can be corrected by changing the type of role from Relational to Syntactic.

The default grammatical role for "to the power" is "follows verb". This is not the best choice for this phrase. "Follows a second value" is a better choice. This will insert "to the power" just to the right of the second value in the phrasing.

To the power" needs the preposition "to." Pick it from the list of prepositions.

Now the user must enter the noun phrase. In this example the user wants to use "power." Simply type "the power" in the Text box.

Wait a minute. Do we want to say "to a power" or "to the power?" Mathematically the two phrases are quite different. Make sure to type correct phrasing.

At this point the Grammatical Role dialog seems complete and correct, so click OK and we'll see what has happened to the phrasing.

"A first value is a second value to the power..." is correct but it still needs one more element. However the "of a third value" still needs to be added to the phrasing. Click the New grammatical role button again.

Once again the Grammatical Role dialog is displayed. Authority now assumes that the user will add the remaining value to the phrasing. In this instance the assumption is correct.

Now the user wants to change follows verb to follows the power. Note that the list of possible grammatical roles grows as the phrasing grows. There is always a way to attach another term to the end of the existing phrasing.

This is a relational role, and the user can select "of" from the list of prepositions. Check the box that requires this element to be present in the phrasing.

Click OK to see if the phrasing is finally complete.

"A first value is a second value to the power of a third value." This looks just correct. Click OK to close the New/Edit Phrasing dialog.

This will return the user to Add/Edit Relation dialog which was left a few minutes ago. The "pow" relation is now completely defined, Click OK and save it.

The addition of a function is for making Authority aware of something that it does not natively understand or is custom to the organization. With the function in place, and phrasing added, it can be reference in natural language in creating statements. The example shows adding an Eclipse function (exponent) that Authority does not know out of the box. Once added in you can say something that "a number to the power of another number" and it will use that added function when doing code generation.

The example above shows users how to add an Eclipse function (exponent) that Authority does not natively understand out of the box. The same logic and path will be similar when adding JAVA function and .NET functions.