|
|
(90 intermediate revisions by 4 users not shown) |
Line 1: |
Line 1: |
| {{Hierarchy header}}
| | Content moved to M204Int, but history preserved here. |
|
| |
| The following sections describe changes in the [[Janus SOAP User Language Interface|Janus SOAP ULI]]
| |
| in this release.
| |
|
| |
| ==New arguments for Record class ToXmlDoc method==
| |
| The <var>[[ToXmlDoc]]</var> method in the <var>Record</var> class has the following new
| |
| arguments:
| |
| <table>
| |
| <tr><th>CodepageTable= <i>bool</i>
| |
| </th><td>This Boolean argument, which defaults to <code>False</code>, specifies whether to use the base codepage translation table when creating the XmlDoc. For more details, see the description of the <var>CodepageTable</var> argument in [[Janus SOAP XmlDoc API V7.8 changes#LoadFromRecord subroutine in XmlDoc and XmlNode classes|LoadFromRecord]].
| |
|
| |
| Note that this argument was actually introduced in version 7.6 of the <var class="product>Sirius Mods</var>.
| |
| </td></tr>
| |
| <tr><th>AllowNull=<i> bool</i>
| |
| </th><td>The value of this Boolean argument, which defaults to <code>False</code>, is copied to the <var>AllowNull</var> property of the <var>XmlDoc</var> created by <var>ToXmlDoc</var>. The <var>XmlDoc</var>'s <var>AllowNull</var> property, in turn, determines whether field values that contain the X'00' character are stored in the <var>XmlDoc</var> with base64 encoding. Such values are base64 encoded if <var>AllowNull</var> is <code>False</code>.
| |
|
| |
| For more information, see the description of the <var>AllowNull=</var> argument in [[Janus SOAP XmlDoc API V7.8 changes#NewFromRecord shared function in XmlDoc class|NewFromRecord]].
| |
|
| |
| Note that this argument was actually introduced in version 7.7 of the <var class="product>Sirius Mods</var>.
| |
| </td></tr></table>
| |
|
| |
| ==Field references in Record class CurrentRecord methods==
| |
| For methods declared with a <var>CurrentRecord</var> attribute, it was the case under <var class="product>Sirius Mods</var> 7.7 that field references were an exception to the following rule:
| |
| <br>
| |
| ''Statements within the method definition, even a <var>CurrentRecord</var> method call, may reference the record without having to be wrapped inside a record <var>For</var> loop.''
| |
|
| |
| Under <var class="product>Sirius Mods</var> 7.8, field references are no longer an exception to this rule.
| |
| You may reference a record field from within a method declared with <var>CurrentRecord</var>
| |
| without being inside a record <var>For</var> loop.
| |
|
| |
| For example, for the field COLOR,
| |
| the <code>For Record currentRecord</code> and <code>End For</code>
| |
| statements containing the
| |
| <code>print COLOR</code> statement in the method definition below
| |
| may be discarded under <var class="product>Sirius Mods</var> 7.8:
| |
| <p class="code">local subroutine (Record in file myproc):printField currentRecord in file myproc
| |
| for record currentRecord
| |
| print COLOR
| |
| end for
| |
| end subroutine
| |
| </p>
| |
|
| |
| ==New exception class: BadJournal==
| |
| The <var>BadJournal</var> exception class reports
| |
| errors in CCAJRNL or CCAJLOG datasets or streams, including naming errors.
| |
| The <var>[[New]]</var> method of the <var>[[Journal class|Journal]]</var> system class is the
| |
| system method that automatically throws a <var>BadJournal</var> exception.
| |
|
| |
| The following example shows a <var>Try</var> and <var>Catch</var> of a <var>Journal</var> class, <var>New</var> method,
| |
| exception. An invalid journal name is specified to generate the <var>BadJournal</var> exception:
| |
| <pre>
| |
| Begin
| |
|
| |
| %sl is object stringlist
| |
| %rc is float
| |
| %journal is object journal
| |
| %bdjrnl is object BadJournal
| |
|
| |
| try printtext {~} is: {%journal = new('OLD~RNL')}
| |
| catch BadJournal to %bdjrnl
| |
| Print 'Failure!!! Reason code is: ' %bdjrnl:reasonCode
| |
| end try
| |
|
| |
| %rc = %sl:appendJournalData( -
| |
| Options='MAXIO=1000 WIDTH=138 ST AA USER', -
| |
| Threads='*', Journal=%journal)
| |
| Print %rc
| |
| Print %sl:count
| |
| %sl:print
| |
|
| |
| End
| |
| </pre>
| |
|
| |
| The Stringlist AppendJournalData method does not cancel if its Journal
| |
| parameter is null.
| |
| The request result shows the reason code (ReasonCode property value)
| |
| stored in the exception object:
| |
| <pre>
| |
| %journal = new('OLD~RNL') is: Failure!!! Reason code is: 1
| |
| 0
| |
| 0
| |
| </pre>
| |
|
| |
| The methods of the BadJournal class are described in the following subsections.
| |
| ===New constructor===
| |
| This constructor generates an instance of a BadJournal exception.
| |
| As shown below, the optional argument of the New method is a setting of
| |
| the ReasonCode property.
| |
|
| |
| ====New constructor syntax====
| |
| [%bdJrnl =] [%(BadJournal):] New(ReasonCode=num)
| |
| ===ReasonCode property===
| |
| This readOnly property returns a numeric reason code that indicates the
| |
| cause of the BadJournal exception.
| |
| ====ReasonCode syntax====
| |
| %rc = %bdJrnl:ReasonCode
| |
|
| |
| Possible reason codes are:
| |
| <dl>
| |
| <dt>1
| |
| <dd>Either the dataset or stream name is invalid, or the journal is invalid.
| |
| <dt>2
| |
| <dd>The dataset or stream is empty.
| |
| <dt>3
| |
| <dd>The journal was created with a different ''Model 204'' version than the
| |
| current Online.
| |
| <dt>4
| |
| <dd>A merged journal is invalid.
| |
| </dl>
| |
|
| |
| ==Enhancement to exception handling: Success blocks==
| |
| Exception Try/Catch support is enhanced in Version 7.8 by the addition of Success blocks.
| |
| In cases where a Try block contains multiple statements, a
| |
| Success block makes it clear in the code which statement is expected to produce
| |
| the exceptions that are being caught.
| |
| They also protect you from an inadvertent exception thrown in an unexpected context.
| |
|
| |
| For example, consider the following scenario.
| |
| You want to try statement <a> and, if no exceptions get Thrown,
| |
| you want to do statements <nowiki><b></nowiki>, <c>, <d>, <e>, and <f>.
| |
| Otherwise, if statement <a> throws an exception,
| |
| you want to do statements <x>, <y>, or <z>, depending on the exception.
| |
|
| |
| You code your Try/Catch block like this:
| |
| <p class="code"><nowiki>try
| |
| <a>
| |
| <b>
| |
| <c>
| |
| <d>
| |
| <e>
| |
| <f>
| |
| catch foo
| |
| <x>
| |
| catch bar
| |
| <y>
| |
| catch whatever
| |
| <z>
| |
| end try
| |
| </nowiki></p>
| |
|
| |
| If statement <a> does indeed throw an exception, statements <nowiki><b></nowiki> through <f>
| |
| do not run, and the appropriate Catch statement takes affect.
| |
| However, if statement <a> does not throw an exception,
| |
| there might be no way to know that statement <nowiki><b></nowiki>, <c>, <d>, <e>, or <f> might
| |
| throw an exception that is one of the exceptions in the subsequent Catch statements.
| |
| Or you might be aware of their capacity to do so,
| |
| but you might not expect an exception from any of them in this context. Prior to
| |
| Version 7.8 of the Sirius Mods, there was
| |
| no good way of preventing the catches to also be in effect for these statements
| |
| as well as for statement <a>.
| |
|
| |
| As of <var class="product>Sirius Mods</var> 7.8, a Success block inside the Try block
| |
| resolves the problem by making it clear that the Catches do not apply to
| |
| statements <nowiki><b></nowiki>, <c>, <d>, <e>, and <f>:
| |
| <pre>
| |
| try
| |
| <a>
| |
| success
| |
| <b>
| |
| <c>
| |
| <d>
| |
| <e>
| |
| <f>
| |
| catch foo
| |
| <x>
| |
| catch bar
| |
| <y>
| |
| catch whatever
| |
| <z>
| |
| end try
| |
| </pre>
| |
|
| |
| A Success block may come before or after the Catch blocks:
| |
| <pre>
| |
| try
| |
| <a>
| |
| catch foo
| |
| <x>
| |
| catch bar
| |
| <y>
| |
| catch whatever
| |
| <z>
| |
| success
| |
| <b>
| |
| <c>
| |
| <d>
| |
| <e>
| |
| <f>
| |
| end try
| |
| </pre>
| |
|
| |
| ==New SelectionCriterion methods: IsNull and IsNotNull==
| |
| These shared methods take no parameters and create a new [[SelectionCriterion]] object.
| |
| The methods provide control for Null objects in the [[collection]] you are searching.
| |
| They also let you determine whether a collection contains items that are objects,
| |
| because they cancel the request if the collection being searched contains
| |
| non-object (intrinsic type) items.
| |
|
| |
| An IsNull criterion selects a collection item if the item is a Null object;
| |
| an IsNotNull criterion selects an item objects if it is not Null.
| |
|
| |
| The syntax of the methods follows:
| |
|
| |
| %selc = IsNull
| |
|
| |
| %selc = IsNotNull
| |
|
| |
| The examples below test a variety of searches against
| |
| arraylist <tt>%al</tt> of objects of class <tt>T</tt>:
| |
| <pre>
| |
| class T
| |
| public
| |
| variable x is float
| |
| end public
| |
| end class
| |
|
| |
| %al is arraylist of object t
| |
| %t is object t
| |
| %t1 is object t
| |
| %t2 is object t
| |
|
| |
| %t1 = null
| |
| %t2 = new
| |
| %al = list(%t1, %t2)
| |
| </pre>
| |
| <ol>
| |
| <li>The Arraylist class [[FindNextItem]] method, which throws an exception
| |
| if its selection criterion
| |
| matches no item, fails in the Try clause below when it tests the Null object item.
| |
| The method's exception is not thrown because the test failure prevents the method
| |
| from completing its search:
| |
| <pre>
| |
| try %t = %al:findNextItem(EQ(x,1))
| |
| printtext found t
| |
| printtext {~} = {%t:x}
| |
| catch itemNotFound
| |
| printText None!
| |
| end try
| |
| </pre>
| |
|
| |
| The result is:
| |
| <pre>
| |
| CANCELLING REQUEST: MSIR.0750: Class ARRAYLIST, function
| |
| FindNextItem: reference to null object in line xx
| |
| </pre>
| |
| To complete this request without cancellation,
| |
| you can use an IsNotNull criterion to bypass Null items:
| |
| <pre>
| |
| try %t = %al:findNextItem(AND(isNotNull, EQ(x,1)))
| |
| printtext found t
| |
| printtext {~} = {%t:x}
| |
| catch itemNotFound
| |
| printText None!
| |
| end try
| |
| </pre>
| |
|
| |
| The search finds no matching items, so the Catch clause above catches the
| |
| method's ItemNotFound exception, and the result is:
| |
| <pre>
| |
| None!
| |
| </pre>
| |
| <li>Instead of bypassing Null items, you might instead want the search to
| |
| include them:
| |
| <pre>
| |
| try %t = %al:findNextItem(OR(isNull, EQ(x,1)))
| |
| printtext found t
| |
| printtext {~} = {%t:x}
| |
| catch itemNotFound
| |
| printText None!
| |
| end try
| |
| </pre>
| |
|
| |
| The Null item is found, but the Try clause PrintText invocation
| |
| of <tt>%t:x</tt> fails, and the result is:
| |
| <pre>
| |
| CANCELLING REQUEST: MSIR.0561: Text output:
| |
| reference to null object in line xx
| |
| </pre>
| |
|
| |
| If you want to search exclusively for the next Null item in a collection,
| |
| you can simply use this:
| |
| <pre>
| |
| %t = %al:findNextItem(isNull)
| |
| </pre>
| |
| <li>To successfully locate the non-Null item in <tt>%al</tt>,
| |
| you could use either of the following method calls in the Try clause:
| |
| <pre>
| |
| %t = %al:findNextItem(isNotNull)
| |
| %t = %al:findNextItem(AND(isNotNull, EQ(x,0)))
| |
| </pre>
| |
|
| |
| Thanks to the change in the EQ criterion in the second call above,
| |
| the result of trying either of these searches is:
| |
| <pre>
| |
| found t
| |
| %t:x=0
| |
| </pre>
| |
| </ol>
| |
|
| |
| ==New intrinsic Float methods: ToDegrees and ToRadians==
| |
| ===ToDegrees===
| |
| This [[Float class|Float]] function converts to angular degrees its floating point argument which is a number of radians.
| |
|
| |
| The syntax of ToDegrees is:
| |
|
| |
| %deg = number:toDegrees
| |
|
| |
| where:
| |
|
| |
| ''%deg'' is a variable to contain the number of degrees of the method object.
| |
|
| |
| ''number'' is a Float value that is the number of radians.
| |
|
| |
| The following example shows the result of several ToDegrees calls:
| |
| begin
| |
| printText {~} = {1:toDegrees}
| |
| printText {~} = {0:toDegrees}
| |
| printText {~} = {0.1:toDegrees}
| |
| printText {~} = {-0.1:toDegrees}
| |
| printText {~} = {3.1415926:toDegrees}
| |
| printText {~} = {$pi:toDegrees}
| |
| end
| |
|
| |
| The result is:
| |
|
| |
| 1:toDegrees = 57.2957795130823
| |
| 0:toDegrees = 0
| |
| 0.1:toDegrees = 5.72957795130823
| |
| -0.1:toDegrees = -5.72957795130823
| |
| 3.1415926:toDegrees = 179.999996929531
| |
| $pi:toDegrees = 180
| |
|
| |
| ===ToRadians===
| |
| This Float function converts to radians its floating point argument which is a number of angular degrees.
| |
|
| |
| The syntax of ToRadians is:
| |
|
| |
| %rad = number:toRadians
| |
|
| |
| where:
| |
|
| |
| ''%rad'' is a variable to contain the number of radians of the method object.
| |
|
| |
| ''number'' is a Float value that is the number of degrees.
| |
|
| |
| The following example shows the result of several ToRadians calls:
| |
| begin
| |
| printText {~} = {57:toRadians}
| |
| printText {~} = {0:toRadians}
| |
| printText {~} = {120:toRadians}
| |
| printText {~} = {-120:toRadians}
| |
| printText {~} = {360:toRadians}
| |
| end
| |
|
| |
| The result is:
| |
|
| |
| 57:toRadians = 0.994837673636768
| |
| 0:toRadians = 0
| |
| 120:toRadians = 2.0943951023932
| |
| -120:toRadians = -2.0943951023932
| |
| 360:toRadians = 6.28318530717959
| |
|
| |
| ==New Collection methods==
| |
| Seven new methods are added to each of the [[collection classes]] in <var class="product>Sirius Mods</var> Version 7.8.
| |
|
| |
| ===The Sum, Average, Variance, and StandardDeviation methods===
| |
|
| |
| These functions have the same syntax and perform mathematical operations:
| |
|
| |
| <dl>
| |
| <dt>Sum
| |
| <dd>Returns the simple sum of the values of the items in the collection.
| |
| <dt>Average
| |
| <dd>Returns the average of the values of the items in the collection.
| |
| <dt>Variance
| |
| <dd>Returns the "mean standard deviation" of the values of the items in the collection.
| |
| From statistics, this is the average of the squares of the deviations of the
| |
| value of each item from the mean of all the items.
| |
| <dt>StandardDeviation
| |
| <dd>Returns the standard deviation, the variation from the mean, of the values of the items in the collection. This is the square root of the collection's variance.
| |
| </dl>
| |
| Here is an example:
| |
|
| |
| b
| |
| %al is arrayList of float
| |
|
| |
| %al = new
| |
| %al:add(5)
| |
| %al:add(3)
| |
| %al:add(8)
| |
|
| |
| print %al:sum
| |
| print %al:average
| |
| print %al:variance
| |
| print %al:standardDeviation
| |
| end
| |
|
| |
| The result is:
| |
|
| |
| 16
| |
| 5.33333333333333
| |
| 4.22222222222222
| |
| 2.05480466765633
| |
|
| |
| The syntax of the methods is:
| |
| %num = %collectionType:methodName( [function] )
| |
|
| |
| Where:
| |
|
| |
| ''%num'' is a float variable to contain the numeric result.
| |
|
| |
| ''%collectionType'' is an [[ArrayList class|ArrayList]], [[NamedArrayList class|NamedArrayList]], [[FloatNamedArrayList class|FloatNamedArrayList]],or [[UnicodeNamedArrayList class|UnicodeNamedArrayList]] object variable.
| |
|
| |
| ''function'' is a function that operates on the type of
| |
| the items in the collection. It may be a [[local method]] or [[method variable]] or a class
| |
| member (variable, property), and it must return an [[intrinsic]] (probably float) value. The
| |
| default ''function'' value is the special identity function, <tt>This</tt>, which simply returns the item value.
| |
|
| |
| The optional ''function'' parameter lets you further manipulate the collection item values
| |
| before performing the requested method's operation.
| |
| If your collection's items are not intrinsic
| |
| values, you must specify a function that can map the item values
| |
| to intrinsic values or the method will fail.
| |
|
| |
| For example, for a collection that is a list of coordinates, you could
| |
| return the average of their distance from the origin by first applying a local function as the Average method's ''function'' parameter:
| |
|
| |
| b
| |
| class point
| |
| public
| |
| constructor new(%x is float, %y is float)
| |
| variable x is float
| |
| variable y is float
| |
| end public
| |
|
| |
| constructor new(%x is float, %y is float)
| |
| %this:x = %x
| |
| %this:y = %y
| |
| end constructor
| |
| end class
| |
|
| |
| local function (point):distance is float
| |
| return (%this:x * %this:x + %this:y * %this:y):squareRoot
| |
| end function
| |
|
| |
| %al is arrayList of object point
| |
|
| |
| %al = new
| |
| %al:add(new(1,1))
| |
| %al:add(new(3,4))
| |
| %al:add(new(-5,12))
| |
|
| |
| print %al:average(distance)
| |
|
| |
| end
| |
|
| |
| The result is <tt>6.47140452079103</tt>.
| |
|
| |
| ===The CountSubset method===
| |
|
| |
| The CountSubset function returns the number of items in a collection that match a
| |
| specified selection criterion. It is related to the SubsetNew collection mathod, which returns not the count but a collection of the matching items for a specified criterion.
| |
|
| |
| The syntax of the method is:
| |
| %num = %collectionType:CountSubset( criterion )
| |
|
| |
| Where:
| |
|
| |
| ''%num'' is a float variable to contain the numeric result.
| |
|
| |
| ''%collectionType'' is an ArrayList, NamedArrayList, FloatNamedArrayList,or UnicodeNamedArrayList object variable.
| |
|
| |
| ''criterion'' is a [[SelectionCriterion]] object, which is a relational expression that is
| |
| applied to each collection item value to determine whether the value satisfies the expression. This is a required parameter.
| |
|
| |
| As a simple example, for the ArrayList whose items are the odd integers between 0 and 10, and the selection criterion <tt>LT(this, 9))</tt>, CountSubset returns <tt>4</tt>.
| |
|
| |
| ===The MinItem and MaxItem methods===
| |
| The MinItem and MaxItem functions return the minimum and maximum values in a collection. They are related to the Minimum and Maximum collection methods, which return the number or name of the item that has the minimum or maximum value in the collection.
| |
|
| |
| The syntax of these methods is:
| |
| %num = %collectionType:methodName( [function] )
| |
|
| |
| Where:
| |
|
| |
| ''%num'' is a float variable to contain the numeric result.
| |
|
| |
| ''%collectionType'' is an ArrayList, NamedArrayList, FloatNamedArrayList,or UnicodeNamedArrayList object variable.
| |
|
| |
| ''function'' is a function that operates on the type of
| |
| the items in the collection. It may be a [[local method]] or [[method variable]] or a class
| |
| member (variable, property), and it must return an [[intrinsic]] (probably float) value. The
| |
| default ''function'' value is the special identity function, <tt>This</tt>, which simply returns the item value.
| |
|
| |
| The optional ''function'' parameter lets you further manipulate the collection item values
| |
| before performing the requested method's operation.
| |
| If your collection's items are not intrinsic
| |
| values, you must specify a function that can map the item values
| |
| to intrinsic values or the method will fail.
| |
|
| |
| For the ArrayList <tt>%al</tt> whose items are the odd integers between 0 and 10, <tt>%al:maxItem</tt> returns <tt>9</tt>.
| |
|
| |
| ==New StringTokenizer methods==
| |
| Several new methods are added to the <var>[[StringTokenizer class|StringTokenizer]]</var> class in <var class="product>Sirius Mods</var> Version 7.8.
| |
|
| |
| ===The Separators method===
| |
| This readWrite property introduces another class of characters in the
| |
| StringTokenizer to delimit, or separate, tokens. Prior to this version, only <var>[[Spaces (StringTokenizer property)|Spaces]]</var> and <var>[[TokenChars (StringTokenizer property)|TokenChars]]</var> characters were available to separate tokens.
| |
| The new <var>Separators</var> characters are similar to <var>Spaces</var> and <var>TokenChars</var>, but
| |
| in addition to delimiting tokens, <var>Separators</var> characters:
| |
| <ul>
| |
| <li>do not compress to a single separator (like <var>Spaces</var> characters)
| |
| <li>are not themselves tokens (like <var>TokenChars</var> characters), so are not returned by repeated <var>[[NextToken (StringTokenizer function)|NextToken]]</var> calls
| |
| that encounter consecutive <var>Separators</var> characters
| |
| </ul>
| |
|
| |
| The syntax of the method is:
| |
| <p class="syntax"> %string = %tok:Separators
| |
|
| |
| %tok:Separators = %string
| |
| </p>
| |
| Where:
| |
| <dl>
| |
| <dt><i>%string</i>
| |
| <dd>A string variable to contain the returned value of the current
| |
| separator characters or to be set as the new value(s).
| |
| The default value for a new tokenizer instance is the null string.
| |
|
| |
| If you are setting Separators, each character in the separator string is a
| |
| separator, and no character may repeat (except for apostrophe, which may be doubled).
| |
| <dt><i>%tok</i>
| |
| <dd>A StringTokenizer object variable.
| |
|
| |
| </dl>
| |
| Separators provide a way to handle consecutive occurrences of the same token delimiter character, for example, in a comma-separated value (csv) file, where they indicate a missing value.
| |
| As an example, the adjacent separators in the token string below
| |
| are detected and returned as nulls by the <var>NextToken</var> method:
| |
| <p class="pre"> b
| |
| %toke is object StringTokenizer
| |
| %toke = new(separators=',;')
| |
| %toke:string = '0,1,2,,4,;6'
| |
|
| |
| repeat while %toke:notAtEnd
| |
| printtext {~} = '{%toke:nextToken}'
| |
| end repeat
| |
| end
| |
| </p>
| |
|
| |
| The result is:
| |
| <p class="pre"> %toke:nextToken = '0'
| |
| %toke:nextToken = '1'
| |
| %toke:nextToken = '2'
| |
| %toke:nextToken = <nowiki>''</nowiki>
| |
| %toke:nextToken = '4'
| |
| %toke:nextToken = <nowiki>''</nowiki>
| |
| %toke:nextToken = '6'
| |
| </p>
| |
|
| |
| Separators override default and explicitly defined <var>Spaces</var> characters.
| |
| For example, if the only change to the example above is that the tokenizer string is <code>"please, don't go"</code>,
| |
| the result is:
| |
| <p class="pre"> %toke:nextToken = 'please'
| |
| %toke:nextToken = 'don't go'
| |
| </p>
| |
|
| |
| The blank after <code>don't</code> does not act as a token delimiter.
| |
|
| |
| '''Note:''' Separators do '''not''' override explicitly defined <var>TokenChars</var> characters. If both separators and token characters are defined, all such characters act as token delimiters.
| |
|
| |
| ===The CompressSpaces, FoldDoubledQuotes, and QuotesBreak methods===
| |
| These readWrite properties all return or set a boolean value.
| |
|
| |
| ====The CompressSpaces property====
| |
| <var>CompressSpaces</var> compresses the intermediate spaces in a string of whitespace characters.
| |
| For example, consider the following <code>%toke</code> <var>StringTokenizer</var> string, defined with a blank as the whitespace character and with comma as a non-token [[Janus SOAP ULI V7.8 changes#Separators|separator]] character:
| |
| <p class="pre"> this, is a compression , example
| |
| </p>
| |
| Without compression, repeated calls of <code>%toke:NextToken</code> strip the leading and trailing whitespace and select the following tokens:
| |
| <p class="pre"> this
| |
| is a compression
| |
| example
| |
| </p>
| |
| Without compression, that is, with <var>CompressSpaces</var> set to <code>True</code>, the result is:
| |
| <p class="pre"> this
| |
| is a compression
| |
| example
| |
| </p>
| |
| <var>CompressSpaces</var> compresses a token's intermediate whitespace
| |
| to a single whitespace character. If multiple whitespace
| |
| characters are defined, the first character in the <var>Spaces</var> string is the character to which intermediate whitespace is compressed. For example, if <code>Spaces='X '</code>, the token
| |
| 'foot ball' will compress to 'footXball'.
| |
|
| |
| The <var>CompressSpaces</var> default value is <code>False</code>.
| |
|
| |
| '''Note:''' <var>CompressSpaces</var> affects
| |
| processing only when one or more <var>Separators</var> characters are set, because otherwise a
| |
| token cannot contain internal whitespace.
| |
|
| |
| ====The FoldDoubledQuotes property====
| |
| The practice of doubling an apostrophe ( ' ) to yield a single apostrophe is common in User Language <var>Print</var> statements. For example, the result of <code>Print 'Please, don<nowiki>''</nowiki>t go'</code> is:
| |
| <p class="pre"> Please, don't go</p>
| |
| The doubled, or escaped, apostrophe is implicitly folded to a single apostrophe.
| |
| Similarly, if double quotation marks instead of the apostrophes are used to indicate a quoted string (as is [[V7.8 changes affecting all or multiple products#Double quotation marks for quoted strings|allowed]] as of <var class="product>Sirius Mods</var> version 7.8): <code>Print "Please, don""t go"</code>
| |
| The result is <p class="pre"> Please, don"t go</p>. The escaped double quotation mark is implicitly folded to one double quotation mark.
| |
|
| |
| The <var>StringTokenizer</var>, however, does not perform this implicit folding if it encounters a doubled <var>Quotes</var> character within a quoted region. For example:
| |
| <p class="pre"> b
| |
| %toke is object StringTokenizer
| |
| %toke = new(quotes='"')
| |
| %toke:string = '"Please, don""t go"'
| |
|
| |
| repeat while %toke:notAtEnd
| |
| printtext {~} = '{%toke:nextToken}'
| |
| end repeat
| |
| end
| |
| </p>
| |
| The result of this request is:
| |
| <p class="pre"> %toke:nextToken = 'Please, don'
| |
| %toke:nextToken = 't go'
| |
| </p>
| |
| To provide for cases where you might expect or want implicit folding of a doubled <var>Quotes</var> character, version 7.8 adds the <var>FoldDoubledQuotes</var> property to the <var>StringTokenizer</var> class.
| |
| If the <var>FoldDoubledQuotes</var> property is set to <code>True</code> (this is not the default), the tokenizer considers two adjacent <var>[[Quotes (StringTokenizer property)|Quotes]]</var>
| |
| characters within a quoted region ''that is begun by the same <var>Quotes</var> character'' to be an escape sequence for a single quotation character, and the result of tokenizing <code>%toke:string = '"Please, don""t go"'</code> from the previous request is:
| |
| <p class="pre"> Please, don"t go</p>
| |
|
| |
| The syntax of the <var>FoldDoubledQuotes</var> method is:
| |
| <p class="syntax"> %bool = %tok:FoldDoubledQuotes
| |
|
| |
| %tok:FoldDoubledQuotes = %bool
| |
| </p>
| |
| Where:
| |
| <dl>
| |
| <dt><i>%bool</i>
| |
| <dd>An enumeration object of type Boolean to contain or set the value of FoldDoubledQuotes.
| |
| The default value for a new tokenizer instance is <code>False</code>.
| |
| <dt><i>%tok</i>
| |
| <dd>A StringTokenizer object variable.
| |
|
| |
| </dl>
| |
|
| |
| ==Aliases for class names==
| |
| As of <var class="product>Sirius Mods</var> Version 7.8, you can define an alias name for an existing user class.
| |
| You do so by specifying an <tt>Alias</tt> parameter setting on the existing class declaration. For example,
| |
| you are changing a naming convention for some code, and you want to refer to user-defined class <tt>Blue</tt> by another name, say <tt>Indigo</tt>. Your class declaration would be:
| |
|
| |
| class blue alias indigo
| |
|
| |
| You can then use either the primary class name or the alias when declaring objects of the class:
| |
|
| |
| %foo is object blue
| |
| %bar is object indigo
| |
|
| |
| An object of the alias class is compiled as an object
| |
| of the primary class, and the runtime class of an
| |
| object variable that was defined using an alias is the primary class.
| |
| Consequently, all system messages you receive will specify the primary class.
| |
|
| |
| For example, given the declarations above, if you call method <tt>TouchUp</tt> for an object declared for the Indigo class:
| |
|
| |
| %bar:touchUp
| |
|
| |
| And method TouchUp does not exist in the class, the error message you receive is:
| |
|
| |
| MSIR.0733: Member TOUCHUP not found in class Blue
| |
|
| |
| While this might seem potentially confusing, aliases are intended primarily for migrating class names, so any confusion will be limited to this migration period. In addition, only the owner of a class can declare an alias, so aliases are not likely to proliferate in your site's code.
| |
|
| |
| Should it ever be necessary, you may also specify multiple aliases:
| |
|
| |
| class blue alias indigo and ultramarine and navy
| |
|
| |
| You may declare a user-defined class with an alias name that matches the name of a system class.
| |
|
| |
| ==New common enumeration method: FromString==
| |
| <var class="product>Sirius Mods</var> Version 7.8 adds the FromString shared function as a method common to all system and user-defined enumerations. FromString converts a string argument into a value of the specified enumeration type.
| |
| This is the opposite of an enumeration ToString method, which converts an enumeration value to its String representation.
| |
|
| |
| As an example, consider the following user-defined enumeration:
| |
|
| |
| enumeration Animal
| |
| public
| |
| value cat
| |
| value dog
| |
| value gecko
| |
| value parrot
| |
| end public
| |
| end enumeration
| |
| You can populate an Animal enumeration variable with one of the Animal enumeration values by making a call to FromString:
| |
|
| |
| %pet is enumeration animal
| |
| %pet = fromString('gecko')
| |
| The result of a Print of <tt>%pet</tt> above is <tt>gecko</tt>. In the method call, <tt>fromString</tt> does '''not''' have to be preceded by <tt>%(Animal):</tt> to identify the type of enumeration, because the FromString method is automatically available for any User Language enumeration, system or user-defined.
| |
|
| |
| Only strings that match a value of the particular enumeration type
| |
| can be converted. If a string cannot be converted to an enumeration
| |
| value, FromString throws an [[InvalidValue exception]]:
| |
|
| |
| %pet = fromString('alien')
| |
|
| |
| *** 1 CANCELLING REQUEST: MSIR.0750: Class Animal, function
| |
| FromString: InvalidValue exception: ALIEN is not a valid enumeration
| |
| value in line 84, procedure ENUM, file MYPROC
| |
|
| |
| {{Hierarchy footer}}
| |