Notation conventions for methods: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(59 intermediate revisions by 3 users not shown)
Line 1: Line 1:
These conventions apply primarily to the syntax for method invocation and the argument descriptions in the reference sections for individual class methods.
The syntax for each <var class="product">SOUL</var> system method is displayed in the form of a usage statement which shows how you specify a typical invocation of the method (and receive its result, if any).  
The syntax includes:
<ul>
<ul>
<li>Method names are in mixed case with initial and internal capital letters. User Language keywords and variable name references are also in mixed case. This mixed-case convention is adhered to in text and syntax; it is not strictly adhered to in code examples. For more information about mixed-case User Language, see [[Mixed-case User Language]].
<li>Keywords and placeholder words
<li>Punctuation literals (parentheses, colons, etc. that you must specify)
<li>Special characters (square brackets, hyphens) that you do not specify because they are part of the syntax structure, not the method content
</ul>
For example, here is the syntax for the <var>FindNextItem</var> method of the <var>Arraylist</var> class:
{{Template:Arraylist:FindNextItem syntax}}
 
The <var>FindNextItem</var> method does the following:
<ul>
<li>Accepts two arguments (the second of which is [[#Optional arguments|optional]] &mdash; as indicated by the square brackets (<tt>[]</tt>) &mdash; and also [[#Named arguments|named]] &mdash; as indicated by the name and equal sign (<tt>=</tt>).
 
<li>Takes as input the <var>Arraylist</var> that is the [[Methods#Comparing methods to complex subroutines|method object]] (<var class="term">al</var>).
 
<li>May throw the <var>ItemNotFound</var> [[#Exceptions|exception]].
 
<li>Otherwise (that is, if successful), returns the item of that method object <var>Arraylist</var>, as indicated by the assignment to <var class="term">%item</var>.
</ul>
 
Commas are always required to separate arguments, whether named or not. Trailing commas are not required. Commas after missing arguments are required only if a following un-named argument is specified.
 
While the target of a function or property is shown as an assignment to a descriptive %variable, the function or property output can also be used in an expression, for example, as the method object in a subsequent method invocation or passed as a method, $function, or complex subroutine argument. In addition, if a function is [[#Callable functions|callable]], it may be invoked as a statement, without any target for the result.
 
The following sections describe additional aspects of the syntax, and [[Classes and Objects#Member reference|Member reference]] provides further discussion about invoking methods.
 
==Mixed case==
Method names are in mixed case with initial and internal capital letters. <var class="product">SOUL</var> keywords and variable name references are also in mixed case. This mixed-case convention is adhered to in text and syntax; it is not strictly adhered to in code examples. For more information about mixed-case <var class="product">User Language</var>, see [[Mixed-case SOUL]].
<p></p>
<p></p>
<li>In syntax, method arguments are required unless otherwise stated. Omitting a mandatory argument results in a compilation error. Optional arguments are enclosed in brackets ([ ]) in syntax and are described with the word "optional."
 
<p></p>
==Method type==
<li>Some method arguments may be passed by name; they are specified with a following equal sign (=) in method syntax diagrams. For arguments described as "name allowed" (or "name required"), you may specify (or must specify) the argument name along with the argument value when you invoke the method. You specify such argument name and value pairs in the form:
The methods are labeled by type, of which there are four:
*: <p class="syntax"><span class="literal">methodname</span><span class="literal">(</span> <span class="term">argName=</span><span class="term">argValue</span> <span class="literal">)</span></p>
<table class="thJustBold">
: Whether an argument name is a "named parameter" is declared for the method within the class definition with the NameAllowed or NameRequired keyword.
<tr><th>Functions
<p></p>
</th><td>Methods that produce an output value. Sample syntax: {{Template:String:StringToHex syntax}}
<li>Many functions that return a result may also be invoked by the keyword <var>Call</var>. The descriptions of such functions say that they are "callable" and display a bracketed %variable and equality sign in syntax (for example, <code>[%name = ]</code>). The Call keyword is almost always optional so a callable method can usually be invoked via simply specifying the method object followed by colon (<code>:</code>) and the method name.
</td></tr>
<p></p>
<tr><th>Subroutines
<li>Methods are non-shared unless otherwise identified. A shared method is recognizable by the <var class="term">%(classname):</var> notation preceding the method name in the method syntax, which implies that the method need not operate on a particular object. Using the class name in this way denotes that the method is shared, and it models one way you can invoke the method. You can also invoke shared methods using the %objectVariable: notation used by non-shared, or instance, methods. In this case, %objectVariable is used to identify the class to which the method belongs, not that the method operates on %objectVariable (note that %objectVariable may be null for a shared method invocation). For example, the following two statements assign the same value to <code>%max</code>, if <code>%sl</code> is a <var>Stringlist</var> object:
</th><td>Methods that produce no output value. Sample syntax: {{Template:Recordset:RemoveRecord syntax}}
<p class="code">%max = %sl:MaxItemLength
</td></tr>
%max = %(Stringlist):MaxItemLength
<tr><th>Properties
</th><td>Methods that produce an output value and that can sometimes be set to a value. Sample syntax: {{Template:HttpRequest:URL syntax}}
</td></tr>
<tr><th>Constructors
</th><td>Methods that produce a new object instance. Sample syntax: {{Template:XmlDoc:New syntax}}
</td></tr></table>
 
==Optional arguments==
In syntax, method arguments are required unless otherwise stated. Omitting a mandatory argument results in a compilation error. Optional arguments are enclosed in brackets (<tt>[]</tt>) in syntax and are described in text with the word "optional."
 
==Named arguments==
Some method arguments may be passed using their name; they are specified with a following equal sign (<tt>=</tt>) in method syntax diagrams. For arguments described as "name allowed" (or "name required"), you may specify (or must specify) the argument name along with the argument value when you invoke the method. You specify such argument name and value pairs in the form:
<code>object:methodname(... argName=argValue ...)</code>. For example, the <var>Stringlist</var> method <var>RegexCapture</var> has two optional arguments whose names are required if you specify the argument:
 
<p class="syntax"><span class="term">sl</span><span class="literal">:[[RegexCapture (Stringlist function)|RegexCapture]]</span><span class="literal">(</span> <span class="term" title="String">string</span><span class="comma">,</span> <span class="term" title="String">regex</span><span class="comma">,</span> <span class="squareb">[</span><span class="literal" title="String">Options=</span> <span class="term" title="String">string</span><span class="squareb">]</span><span class="comma">,</span> <span class="squareb">[</span><span class="literal" title="%output">Status=</span> <span class="term" title="%output">%output</span><span class="squareb">]</span><span class="literal">)</span></p>
 
A "named argument" is declared for a method within the class definition with the <var>NameAllowed</var> or <var>NameRequired</var> keyword.
 
==Callable functions==
Many functions that return a result may also be invoked by the keyword <var>Call</var>. The descriptions of such functions say that they are "callable" and display a bracketed %variable and equals sign in syntax. For example:
{{Template:Stringlist:Add syntax}}
The <var>Call</var> keyword is optional for a callable function, so you can invoke it by simply specifying the method object followed by colon (<tt>:</tt>) and the method name:
<p class="code">%sl:Add('the end')</p>
 
The definition of a callable function includes the keyword <var>[[Classes and Objects#callable|Callable]]</var>.
 
Subroutines are always invocable with <var>Call</var>, though a subroutine definition does not and must not include the keyword <var>Callable</var>.
 
==Shared methods==
Methods are non-shared unless otherwise identified. [[Shared class members|Shared methods]] are denoted by the <code>%(classname):</code> notation preceding the method name in the method syntax, which implies that the method need not operate on a particular object. For example:
<p class="code">%max = %(Stringlist):maxItemLength
</p>
Using the class name as above is one way you can invoke the method. You can also employ the <code>%objectVariable:</code> notation used by non-shared, or instance, methods.  
For example, if <code>%sl</code> is a <var>Stringlist</var> object, the following statement assigns the same value to <code>%max</code> as in the preceding example statement:
<p class="code">%max = %sl:maxItemLength
</p>
In this case, <code>%sl</code> indicates the class to which the method belongs, not that the method operates on <code>%sl</code> (which may even be null for a shared method invocation).
 
For a shared member whose [[Classes and Objects#datatype|datatype]] is an object of the member's class, a third type of invocation is probably more common than the preceding two. If assigned to an object variable of the class, the member may be invoked with no method object. The <var>[[Descending (SortOrder function)|Descending]]</var> method of the <var>SortOrder</var> class is an example:
<p class="code">%sortOrder = descending(price)</p>
 
Such a shared member is also known as a [[Object variables#Virtual Constructor methods|virtual constructor]] or factory method, and this is the syntax commonly used for a <var>Constructor</var>, as described below. The virtual constructor in the preceding example might also simply be called directly as an argument in another method:
<p class="code">%arrayl = %arrayl:sortNew(descending(price))</p>
In this case, the virtual constructor's class is implicitly identified via the <var>SortNew</var> method's argument definition.
 
==Constructors==
Methods that produce a new object instance of their class are known generally as "constructors." These include the <var>[[Object variables#Using New or other Constructors|New]]</var> method
in Janus system classes (a non-shared method whose method type is <var>Constructor</var>), and the shared method [[Object variables#Virtual constructors|virtual constructors]] (mentioned in [[#Shared methods|"Shared methods"]] above).
 
All constructors are recognizable by the <code>[%(classname):]</code> notation preceding the method name in the method syntax. As for a shared method, the class name in the syntax indicates both of the following:
<ul>
<li>A constructor does not operate on a specified [[Object oriented programming in SOUL#methobj|method object]].
<li>The invocation of a constructor requires a context that identifies the class of the object instance that the method produces.
</ul>
 
The class name is shown within square brackets (thus, optional) for a constructor, however, because you can always invoke a constructor by assignment to an object variable of its class with no other class identifier, as in:
<p class="code">%myobj = new</p>
The object variable provides the class context.
 
The invocation of the <code>New</code> constructor, above, is equivalent to using the class name, as in:
<p class="code">%myobj = %(MyClass):new</p>
 
And both forms of invocation above are equivalent to explicitly specifying a method object instead, although the method object merely identifies the class of the constructor and it is not operated upon:
<p class="code">%myobj = %myclass:new</p>
<code>%myclass</code> above may even be <var>Null</var>.
 
Although the preceding examples of constructor invocation use assignment statements, you can invoke a constructor with or without a method object or explicit class specification in other contexts that allow its class to be determined, for example as an argument in another method. This class-identifying requirement is '''not''' met, for example, in this statement, which is ''invalid'': <code>Print New</code>
 
The use of constructors is discussed in [[Object_variables#Creating object instances|"Creating object instances"]].
 
==Exceptions==
If a system method may throw one or more [[Object oriented programming in SOUL#exception|exceptions]], the method syntax displayed for that method contains the name of the exception(s) below the syntax, preceded by the word <code>Throws</code>. If your use of a method may cause one of these, and you have a reasonable set of actions to perform for it, you can include a <var>[[Exceptions#Try_and_Catch|Catch]]</var> for it; otherwise, the exception result is a request cancelling error.
 
<blockquote class="note">
<p><b>Note:</b> For methods in some classes, it is possible that an exception could be thrown which is not shown in the method's syntax box. A method is susceptible to this if all of these are true: </p>
<ul>
 
<li>The method is not a <var>[[#Shared methods|Shared]]</var> method.
 
<li>The syntax of its class's <var>New</var> method includes one or more exceptions (true for several classes). </li>
 
<li>The method object in the invocation is <var>Null</var>, which causes <var>New</var> to be invoked [[Classes and Objects#The Auto keyword on object declarations|implicitly]].  </li>
 
<li>The implicit <var>New</var> call throws the exception.  </li>
</ul>
 
For example, the <var>[[Run (Daemon function)|Run]]</var> function in the following example can cause a <var>MaxDaemExceeded</var> exception:
<p class="code">begin
%daem is object daemon auto new
%daem:run('LOGWHO'):print
end
</p>
 
The <var>Run</var> invocation above can be wrapped in a <var>Try</var> block, but if the application needs to anticipate this type of implicit exception, it might be better to use an explicit instantiation of the object:
<p class="code">begin
%daem is object daemon
try
  %daem = new
catch maxDaemExceeded
  ...
end try
%daem:run('LOGWHO'):print
end
</p>
</p>
</blockquote>
==See also==
<ul>
<li>[[XmlDoc API#Conventions and terminology for XmlDoc API methods|Conventions and terminology for XmlDoc API methods]]
</ul>
</ul>

Latest revision as of 17:51, 14 August 2015

The syntax for each SOUL system method is displayed in the form of a usage statement which shows how you specify a typical invocation of the method (and receive its result, if any). The syntax includes:

  • Keywords and placeholder words
  • Punctuation literals (parentheses, colons, etc. that you must specify)
  • Special characters (square brackets, hyphens) that you do not specify because they are part of the syntax structure, not the method content

For example, here is the syntax for the FindNextItem method of the Arraylist class:

%item = al:FindNextItem( selectionCriterion, [Start= number]) Throws ItemNotFound

The FindNextItem method does the following:

  • Accepts two arguments (the second of which is optional — as indicated by the square brackets ([]) — and also named — as indicated by the name and equal sign (=).
  • Takes as input the Arraylist that is the method object (al).
  • May throw the ItemNotFound exception.
  • Otherwise (that is, if successful), returns the item of that method object Arraylist, as indicated by the assignment to %item.

Commas are always required to separate arguments, whether named or not. Trailing commas are not required. Commas after missing arguments are required only if a following un-named argument is specified.

While the target of a function or property is shown as an assignment to a descriptive %variable, the function or property output can also be used in an expression, for example, as the method object in a subsequent method invocation or passed as a method, $function, or complex subroutine argument. In addition, if a function is callable, it may be invoked as a statement, without any target for the result.

The following sections describe additional aspects of the syntax, and Member reference provides further discussion about invoking methods.

Mixed case

Method names are in mixed case with initial and internal capital letters. SOUL keywords and variable name references are also in mixed case. This mixed-case convention is adhered to in text and syntax; it is not strictly adhered to in code examples. For more information about mixed-case User Language, see Mixed-case SOUL.

Method type

The methods are labeled by type, of which there are four:

Functions Methods that produce an output value. Sample syntax:

%outString = string:StringToHex

Subroutines Methods that produce no output value. Sample syntax:

recordset:RemoveRecord( record)

Properties Methods that produce an output value and that can sometimes be set to a value. Sample syntax:

%currentString = httpRequest:URL httpRequest:URL = newString

Constructors Methods that produce a new object instance. Sample syntax:

%doc = [%(XmlDoc):]New

Optional arguments

In syntax, method arguments are required unless otherwise stated. Omitting a mandatory argument results in a compilation error. Optional arguments are enclosed in brackets ([]) in syntax and are described in text with the word "optional."

Named arguments

Some method arguments may be passed using their name; they are specified with a following equal sign (=) in method syntax diagrams. For arguments described as "name allowed" (or "name required"), you may specify (or must specify) the argument name along with the argument value when you invoke the method. You specify such argument name and value pairs in the form: object:methodname(... argName=argValue ...). For example, the Stringlist method RegexCapture has two optional arguments whose names are required if you specify the argument:

sl:RegexCapture( string, regex, [Options= string], [Status= %output])

A "named argument" is declared for a method within the class definition with the NameAllowed or NameRequired keyword.

Callable functions

Many functions that return a result may also be invoked by the keyword Call. The descriptions of such functions say that they are "callable" and display a bracketed %variable and equals sign in syntax. For example:

[%number =] sl:Add( itemList)

The Call keyword is optional for a callable function, so you can invoke it by simply specifying the method object followed by colon (:) and the method name:

%sl:Add('the end')

The definition of a callable function includes the keyword Callable.

Subroutines are always invocable with Call, though a subroutine definition does not and must not include the keyword Callable.

Shared methods

Methods are non-shared unless otherwise identified. Shared methods are denoted by the %(classname): notation preceding the method name in the method syntax, which implies that the method need not operate on a particular object. For example:

%max = %(Stringlist):maxItemLength

Using the class name as above is one way you can invoke the method. You can also employ the %objectVariable: notation used by non-shared, or instance, methods. For example, if %sl is a Stringlist object, the following statement assigns the same value to %max as in the preceding example statement:

%max = %sl:maxItemLength

In this case, %sl indicates the class to which the method belongs, not that the method operates on %sl (which may even be null for a shared method invocation).

For a shared member whose datatype is an object of the member's class, a third type of invocation is probably more common than the preceding two. If assigned to an object variable of the class, the member may be invoked with no method object. The Descending method of the SortOrder class is an example:

%sortOrder = descending(price)

Such a shared member is also known as a virtual constructor or factory method, and this is the syntax commonly used for a Constructor, as described below. The virtual constructor in the preceding example might also simply be called directly as an argument in another method:

%arrayl = %arrayl:sortNew(descending(price))

In this case, the virtual constructor's class is implicitly identified via the SortNew method's argument definition.

Constructors

Methods that produce a new object instance of their class are known generally as "constructors." These include the New method in Janus system classes (a non-shared method whose method type is Constructor), and the shared method virtual constructors (mentioned in "Shared methods" above).

All constructors are recognizable by the [%(classname):] notation preceding the method name in the method syntax. As for a shared method, the class name in the syntax indicates both of the following:

  • A constructor does not operate on a specified method object.
  • The invocation of a constructor requires a context that identifies the class of the object instance that the method produces.

The class name is shown within square brackets (thus, optional) for a constructor, however, because you can always invoke a constructor by assignment to an object variable of its class with no other class identifier, as in:

%myobj = new

The object variable provides the class context.

The invocation of the New constructor, above, is equivalent to using the class name, as in:

%myobj = %(MyClass):new

And both forms of invocation above are equivalent to explicitly specifying a method object instead, although the method object merely identifies the class of the constructor and it is not operated upon:

%myobj = %myclass:new

%myclass above may even be Null.

Although the preceding examples of constructor invocation use assignment statements, you can invoke a constructor with or without a method object or explicit class specification in other contexts that allow its class to be determined, for example as an argument in another method. This class-identifying requirement is not met, for example, in this statement, which is invalid: Print New

The use of constructors is discussed in "Creating object instances".

Exceptions

If a system method may throw one or more exceptions, the method syntax displayed for that method contains the name of the exception(s) below the syntax, preceded by the word Throws. If your use of a method may cause one of these, and you have a reasonable set of actions to perform for it, you can include a Catch for it; otherwise, the exception result is a request cancelling error.

Note: For methods in some classes, it is possible that an exception could be thrown which is not shown in the method's syntax box. A method is susceptible to this if all of these are true:

  • The method is not a Shared method.
  • The syntax of its class's New method includes one or more exceptions (true for several classes).
  • The method object in the invocation is Null, which causes New to be invoked implicitly.
  • The implicit New call throws the exception.

For example, the Run function in the following example can cause a MaxDaemExceeded exception:

begin %daem is object daemon auto new %daem:run('LOGWHO'):print end

The Run invocation above can be wrapped in a Try block, but if the application needs to anticipate this type of implicit exception, it might be better to use an explicit instantiation of the object:

begin %daem is object daemon try %daem = new catch maxDaemExceeded ... end try %daem:run('LOGWHO'):print end

See also