Getting started with OOP for User Language programmers - Revision history

JAL: minor formatting

2016-05-16T19:33:57Z

minor formatting

JAL: /* Named parameters */ remove "Sirius"

2016-05-16T19:18:24Z

Named parameters: remove "Sirius"

← Older revision		Revision as of 19:18, 16 May 2016
Line 132:		Line 132:

	===Named parameters===		===Named parameters===
	The ~~Sirius~~ object-oriented ~~<var class="product">User Language</var>~~ implementation has support for named parameters, parameters that can be specified by name, rather than position. While, strictly speaking, this has nothing to do with OO programming (in fact, few OO languages support it — Java and VB.Net do not) named parameters are used in many ~~Sirius~~ methods, so it is important to understand them. To specify a value for a named parameter, simply specify the name, followed by an equals sign (<tt>=</tt>), followed by the value. For example, the <var>Right</var> and <var>Left</var> String functions have a <var>Pad</var> named parameter that indicates the pad character to be used if the input string is shorter than the requested length:		The SOUL object-oriented implementation has support for named parameters, parameters that can be specified by name, rather than position. While, strictly speaking, this has nothing to do with OO programming (in fact, few OO languages support it — Java and VB.Net do not) named parameters are used in many SOUL methods, so it is important to understand them. To specify a value for a named parameter, simply specify the name, followed by an equals sign (<tt>=</tt>), followed by the value. For example, the <var>Right</var> and <var>Left</var> String functions have a <var>Pad</var> named parameter that indicates the pad character to be used if the input string is shorter than the requested length:
	<p class="code">%x = %y:right(20, pad='0') </p>		<p class="code">%x = %y:right(20, pad='0') </p>

Line 139:		Line 139:
	<p class="code">%x = %y:right(20, '0') </p>		<p class="code">%x = %y:right(20, '0') </p>

	In functions with large numbers of parameters, the named parameters can also be very useful for eliminating the need for placeholder commas, and for making the function invocations more readable. String and Float methods tend not to have a lot of parameters so named parameters are not heavily used for them, but they <strong>are</strong> used here and there, so it's important to understand them.		In functions with large numbers of parameters, the named parameters can also be very useful for eliminating the need for placeholder commas, and for making the function invocations more readable. String and Float methods tend not to have a lot of parameters so named parameters are not heavily used for them, but they <strong>are</strong> used here and there, so it is important to understand them.

	==Stringlists==		==Stringlists==

MCosta: /* Collections */

2015-12-10T20:21:30Z

Collections

← Older revision		Revision as of 20:21, 10 December 2015
Line 377:		Line 377:
	<p class="code">%cost is floatNamedArraylist of float		<p class="code">%cost is floatNamedArraylist of float
	...		...
	for %i from 1 to %cost:~~countries~~		for %i from 1 to %cost:count
	print %cost:nameByNumber(%i) with ': ' with %cost:itemByNumber(%i)		print %cost:nameByNumber(%i) with ': ' with %cost:itemByNumber(%i)
	end for </p>		end for </p>

ELowell at 23:48, 10 November 2014

2014-11-10T23:48:31Z

← Older revision		Revision as of 23:48, 10 November 2014
Line 26:		Line 26:
	</ul>		</ul>

	Fortunately, there ~~'''~~is~~'''~~ a way you can learn object-oriented programming and apply the principles on-the-job from day one!		Fortunately, there <strong>is</strong> a way you can learn object-oriented programming and apply the principles on-the-job from day one!

	One requirement for this is to work at a site where <var class="product">[[SOUL]]</var> (thus <var class="product">Model 204</var> V7.5 or higher) is available (or where at least some of the other Janus products, such as <var class="product">Janus Web Server</var> or <var class="product">Janus Sockets</var>, are available).		One requirement for this is to work at a site where <var class="product">[[SOUL]]</var> (thus <var class="product">Model 204</var> V7.5 or higher) is available (or where at least some of the other Janus products, such as <var class="product">Janus Web Server</var> or <var class="product">Janus Sockets</var>, are available).
Line 86:		Line 86:
	This code illustrates the fact that you don't have to convert an entire procedure (or request) to mixed case to take advantage of mixed case <var class="product">SOUL</var>. Obviously though, in the long-term, it is a good goal to aim for relatively consistent casing in all your code. In the short term however, some inconsistency will have to be tolerated to get to the point where most or all <var class="product">SOUL</var> code is in mixed case. Certainly, any new procedures should be written completely in mixed case.		This code illustrates the fact that you don't have to convert an entire procedure (or request) to mixed case to take advantage of mixed case <var class="product">SOUL</var>. Obviously though, in the long-term, it is a good goal to aim for relatively consistent casing in all your code. In the short term however, some inconsistency will have to be tolerated to get to the point where most or all <var class="product">SOUL</var> code is in mixed case. Certainly, any new procedures should be written completely in mixed case.

	This example also demonstrates that you don't have to learn anything new to enter <var class="product">User Language</var> in mixed case (~~'''~~all~~'''~~ statements still work the same way), so there is no excuse not to start.		This example also demonstrates that you don't have to learn anything new to enter <var class="product">User Language</var> in mixed case (<strong>all</strong> statements still work the same way), so there is no excuse not to start.

	==Object-oriented syntax==		==Object-oriented syntax==
Line 154:		Line 154:
	In this example, the <code>Print</code> statement would end up printing "Now is the winter" even though the <code>$listAdd</code> added the line to <code>%list</code>.		In this example, the <code>Print</code> statement would end up printing "Now is the winter" even though the <code>$listAdd</code> added the line to <code>%list</code>.
	Both <code>%list</code> and <code>%list2</code> point to the same $list (object) and so, it is not surprising that what is added via <code>%list</code> can be seen via <code>%list2</code>. It is clear, too, that <code>%list</code> and <code>%list2</code> must be '''pointers''' to $list objects and cannot be the objects, themselves, since a <var>Float</var> value couldn't possibly hold the contents of a $list.		Both <code>%list</code> and <code>%list2</code> point to the same $list (object) and so, it is not surprising that what is added via <code>%list</code> can be seen via <code>%list2</code>. It is clear, too, that <code>%list</code> and <code>%list2</code> must be '''pointers''' to $list objects and cannot be the objects, themselves, since a <var>Float</var> value couldn't possibly hold the contents of a $list.
	An experienced UL programmer might raise an eyebrow at the line that contains the <code>$listAdd</code> in the above example. <var>$listAdd</var> is a '''function''', so it returns a value. But the <code>$listAdd</code> is not on the right side of an assignment. What gives? Well, the result of many $functions is usually "uninteresting" to the UL code, so it seems silly to have to find a variable to which to assign it. So the Sirius Mods allows ~~'''~~certain~~'''~~ $functions to be invoked without assigning its result to anything. This causes the $function to behave more like a subroutine as subroutines are called without obtaining a return value from the subroutine. It is this blurring of the distinction between functions and subroutines that leads to the OO term '''method''', which is a convenient way of referring to either.		An experienced UL programmer might raise an eyebrow at the line that contains the <code>$listAdd</code> in the above example. <var>$listAdd</var> is a '''function''', so it returns a value. But the <code>$listAdd</code> is not on the right side of an assignment. What gives? Well, the result of many $functions is usually "uninteresting" to the UL code, so it seems silly to have to find a variable to which to assign it. So the Sirius Mods allows <strong>certain</strong> $functions to be invoked without assigning its result to anything. This causes the $function to behave more like a subroutine as subroutines are called without obtaining a return value from the subroutine. It is this blurring of the distinction between functions and subroutines that leads to the OO term '''method''', which is a convenient way of referring to either.

	So when you were using $lists, you were using object-oriented programming capabilities, even though you might not have realized it. However, you were ~~'''~~not~~'''~~ using object-oriented syntax to access the $list objects, so the benefits of a pure object-oriented facility were not available to you. Now, you might just say "Hold on, didn't you say strings are also objects?" Indeed they are. However, they're objects that can't be changed once they're set (so-called '''immutable''' objects) — you can't really change a string that's been assigned to a variable, you can only assign a new string to that variable. Most objects are not immutable, though of course, strings and numbers are <i>heavily</i> used, so they have importance disproportionate to their number. Nevertheless, the thing that distinguishes OO languages from non-OO languages is the presence of changeable (non-immutable) objects, so $lists can be viewed as a step toward object-oriented programming.		So when you were using $lists, you were using object-oriented programming capabilities, even though you might not have realized it. However, you were <strong>not</strong> using object-oriented syntax to access the $list objects, so the benefits of a pure object-oriented facility were not available to you. Now, you might just say "Hold on, didn't you say strings are also objects?" Indeed they are. However, they're objects that can't be changed once they're set (so-called '''immutable''' objects) — you can't really change a string that's been assigned to a variable, you can only assign a new string to that variable. Most objects are not immutable, though of course, strings and numbers are <i>heavily</i> used, so they have importance disproportionate to their number. Nevertheless, the thing that distinguishes OO languages from non-OO languages is the presence of changeable (non-immutable) objects, so $lists can be viewed as a step toward object-oriented programming.

	The pure object-oriented equivalent of $lists are called '''Stringlists'''. And, using a <var>Stringlist</var> is very similar to using a $list. To illustrate, let's take the above example and convert it to using <var>Stringlists</var>:		The pure object-oriented equivalent of $lists are called '''Stringlists'''. And, using a <var>Stringlist</var> is very similar to using a $list. To illustrate, let's take the above example and convert it to using <var>Stringlists</var>:
Line 167:		Line 167:
	print %list2:item(1) </p>		print %list2:item(1) </p>

	Your first reaction might be an understandable "So what?" Well, let's take a look at what we've accomplished. First, we've made it much clearer what's in <code>%list</code> and <code>%list2</code>: references to <var>Stringlists</var>. This prevents accidents such as someone accidentally incrementing the value of a %list — the following would ~~'''~~not~~'''~~ be allowed:		Your first reaction might be an understandable "So what?" Well, let's take a look at what we've accomplished. First, we've made it much clearer what's in <code>%list</code> and <code>%list2</code>: references to <var>Stringlists</var>. This prevents accidents such as someone accidentally incrementing the value of a %list — the following would <strong>not</strong> be allowed:
	<p class="code">%list is object stringlist		<p class="code">%list is object stringlist
	...		...
Line 210:		Line 210:
	On this latter point, it is worth mentioning that because <var>Stringlists</var> are true objects, they correct the flakiness that can occur with $lists when the same <var>$listNew</var> (or other $list-creating statement) is executed multiple times. Because the same <var>$listNew</var> statement always returns the same $list identifier (number), situations where a <var>$listNew</var> is excuted multiple times can be buggy or confusing. Executing the same <var>New</var> operation for <var>Stringlists</var> multiple times, on the other hand, returns distinct <var>Stringlist</var> references and so eliminates the bugginess or confusion inherent in the $list equivalent.		On this latter point, it is worth mentioning that because <var>Stringlists</var> are true objects, they correct the flakiness that can occur with $lists when the same <var>$listNew</var> (or other $list-creating statement) is executed multiple times. Because the same <var>$listNew</var> statement always returns the same $list identifier (number), situations where a <var>$listNew</var> is excuted multiple times can be buggy or confusing. Executing the same <var>New</var> operation for <var>Stringlists</var> multiple times, on the other hand, returns distinct <var>Stringlist</var> references and so eliminates the bugginess or confusion inherent in the $list equivalent.

	It is worth emphasizing that a <var>Stringlist</var> object variable does ~~'''~~not~~'''~~ contain the <var>Stringlist</var> object any more than a variable used to hold a $list identifier contains the $list itself. In both cases, the variable contains a '''reference''' to the underlying object. So assigning one <var>Stringlist</var> object variable to another does not create a copy of the object (it simply copies the reference to the underlying object), just as assigning a $list identifier from one variable to another does not copy the $list itself. Although there is a <var>Copy</var> function for <var>Stringlists</var>:		It is worth emphasizing that a <var>Stringlist</var> object variable does <strong>not</strong> contain the <var>Stringlist</var> object any more than a variable used to hold a $list identifier contains the $list itself. In both cases, the variable contains a '''reference''' to the underlying object. So assigning one <var>Stringlist</var> object variable to another does not create a copy of the object (it simply copies the reference to the underlying object), just as assigning a $list identifier from one variable to another does not copy the $list itself. Although there is a <var>Copy</var> function for <var>Stringlists</var>:
	<p class="code">%list is object stringlist		<p class="code">%list is object stringlist
	%list2 is object stringlist		%list2 is object stringlist
Line 329:		Line 329:
	end for </p>		end for </p>

	In addition to eliminating the need for the <code>%ncost</code> variable, this eliminates the chance of a bug where <code>%ncost</code> doesn't accurately reflect the count of items on the <var>Arraylist</var>. Of course, if you have a ~~'''~~lot~~'''~~ of references to <code>%ncost</code>, you might prefer not to fix them all up, in spite of the benefits. In this case, you could simply leave the incrementing of <code>%ncost</code> in the loop that populates the <var>Arraylist</var> or, if you're compulsive about performance, set it after the loop:		In addition to eliminating the need for the <code>%ncost</code> variable, this eliminates the chance of a bug where <code>%ncost</code> doesn't accurately reflect the count of items on the <var>Arraylist</var>. Of course, if you have a <strong>lot</strong> of references to <code>%ncost</code>, you might prefer not to fix them all up, in spite of the benefits. In this case, you could simply leave the incrementing of <code>%ncost</code> in the loop that populates the <var>Arraylist</var> or, if you're compulsive about performance, set it after the loop:
	<p class="code">o: for each occurrence of cost		<p class="code">o: for each occurrence of cost
	%cost:add(value in o)		%cost:add(value in o)

ELowell: /* Collections */

2014-11-10T23:44:11Z

Collections

← Older revision		Revision as of 23:44, 10 November 2014
Line 233:		Line 233:
	Collections are essentially object-oriented replacements for traditional Model 204 arrays, but, as you'll see, with considerably more functionality.		Collections are essentially object-oriented replacements for traditional Model 204 arrays, but, as you'll see, with considerably more functionality.

	Model 204 arrays, unlike $lists, are most certainly <i>not</i> objects in the OO sense, because <var>Array</var> variables are not references to array objects, they are the arrays themselves. There is no way to have two variables referencing the same array (except in the special case of arrays being passed as parameters), and arrays are created at compile-time, unlike objects (and $lists) which are created at run-time. In addition to making arrays non-OO, these restrictions can be problematic for applications:		Model 204 arrays, unlike $lists, are most certainly <strong>not</strong> objects in the OO sense, because <var>Array</var> variables are not references to array objects, they are the arrays themselves. There is no way to have two variables referencing the same array (except in the special case of arrays being passed as parameters), and arrays are created at compile-time, unlike objects (and $lists) which are created at run-time. In addition to making arrays non-OO, these restrictions can be problematic for applications:
	<ul>		<ul>
	<li>Application coders must determine ahead of time what the largest number of array items will be and allocate space for them, at compile time. This is both:		<li>Application coders must determine ahead of time what the largest number of array items will be and allocate space for them, at compile time. This is both:
Line 255:		Line 255:
	Probably, the first thing that jumps out at you is the fact that we don't have to declare (and, in fact, can't) the maximum number of items to be allowed in the <var>Arraylist</var>. This means that <var>Arraylists</var> will only use as much space as is needed for the data at hand, and they will not add a lot to server size requirements for the odd cases where an <var>Arraylist</var> happens to have a lot of items. In fact, collection items are stored in CCATEMP on an as-needed basis, with only the currently referenced item being stored in the server. So, collections have very small server footprints.		Probably, the first thing that jumps out at you is the fact that we don't have to declare (and, in fact, can't) the maximum number of items to be allowed in the <var>Arraylist</var>. This means that <var>Arraylists</var> will only use as much space as is needed for the data at hand, and they will not add a lot to server size requirements for the odd cases where an <var>Arraylist</var> happens to have a lot of items. In fact, collection items are stored in CCATEMP on an as-needed basis, with only the currently referenced item being stored in the server. So, collections have very small server footprints.

	One appealing aspect of using an <var>Arraylist</var> is that, by and large, references to <var>Arraylist</var> items are ~~'''~~identical~~'''~~ to references to <var>Array</var> items. That is, to set <code>%x</code> to the third item in either an <var>Array</var> or <var>Arraylist</var>, one can simply do:		One appealing aspect of using an <var>Arraylist</var> is that, by and large, references to <var>Arraylist</var> items are <strong>identical</strong> to references to <var>Array</var> items. That is, to set <code>%x</code> to the third item in either an <var>Array</var> or <var>Arraylist</var>, one can simply do:

	<p class="code">%x = %numbers(3) </p>		<p class="code">%x = %numbers(3) </p>
Line 281:		Line 281:

	The problem we hit immediately is that the <var>Array</var> version of code never explicitly created the array — the array is created at compile-time. <var>Arraylists</var>, on the other hand, being objects need to be created at run-time — the OO term for this being [http://en.wikipedia.org/wiki/Instantiation_%28computer_science%29 instantiation]. This is identical to the requirement that a $list be created with a <var>$listNew</var>. Not having created an instance of the <var>Arraylist</var>, we will get a [http://en.wikipedia.org/wiki/Null_pointer#Null_pointer null pointer] error in our first reference to the object. We can fix this problem one of two ways. One way is to simply create a new <var>Arraylist</var> instance before using it:		The problem we hit immediately is that the <var>Array</var> version of code never explicitly created the array — the array is created at compile-time. <var>Arraylists</var>, on the other hand, being objects need to be created at run-time — the OO term for this being [http://en.wikipedia.org/wiki/Instantiation_%28computer_science%29 instantiation]. This is identical to the requirement that a $list be created with a <var>$listNew</var>. Not having created an instance of the <var>Arraylist</var>, we will get a [http://en.wikipedia.org/wiki/Null_pointer#Null_pointer null pointer] error in our first reference to the object. We can fix this problem one of two ways. One way is to simply create a new <var>Arraylist</var> instance before using it:
	<p class="code>%cost is arraylist of float		<p class="code">%cost is arraylist of float
	%ncost is float		%ncost is float
	...		...
Line 301:		Line 301:
	While in many instances this is a bad idea (since it can become unclear in the code where an object will be first created or where it's first intended to be created), experience has shown that, at least for collections, the use of <code>Auto New</code> usually works out fairly well. This is especially the case for applications where an <var>Array</var> was changed to an <var>Arraylist</var>.		While in many instances this is a bad idea (since it can become unclear in the code where an object will be first created or where it's first intended to be created), experience has shown that, at least for collections, the use of <code>Auto New</code> usually works out fairly well. This is especially the case for applications where an <var>Array</var> was changed to an <var>Arraylist</var>.

	But we hit a second problem with the above code: an attempt to set item number <code>%ncost</code> in the <var>Arraylist</var> in the above example will almost cause request cancellation, because that item won't be there, yet. This is really no different from the <var>Array</var> code where, if you tried to add a 21'st item to the array, you would get a request cancellation because the array was declared to have 20 items. However, because the array is created at compile-time with 20 entries, one <i>can</i> simply set items 1 through 20. When switching the code to use an <var>Arraylist</var>, the code will have to be changed, somewhat:		But we hit a second problem with the above code: an attempt to set item number <code>%ncost</code> in the <var>Arraylist</var> in the above example will almost cause request cancellation, because that item won't be there, yet. This is really no different from the <var>Array</var> code where, if you tried to add a 21'st item to the array, you would get a request cancellation because the array was declared to have 20 items. However, because the array is created at compile-time with 20 entries, one <strong>can</strong> simply set items 1 through 20. When switching the code to use an <var>Arraylist</var>, the code will have to be changed, somewhat:
	<p class="code">%cost is arraylist of float auto new		<p class="code">%cost is arraylist of float auto new
	%ncost is float		%ncost is float
Line 323:		Line 323:
	end for </p>		end for </p>

	But, this is unnecessary. One nice thing about collections is you <i>always</i> have a <var>Count</var> function that returns the number of items in the collection so the above code could simply be written as:		But, this is unnecessary. One nice thing about collections is you <strong>always</strong> have a <var>Count</var> function that returns the number of items in the collection so the above code could simply be written as:
	<p class="code">for %i from 1 to %cost:count		<p class="code">for %i from 1 to %cost:count
	%x = %cost(%i)		%x = %cost(%i)
Line 356:		Line 356:

	Generally, the most useful aspect of <var>FloatNamedArraylists</var> is the first of these items (as it is in our example), but the second can be useful on occasion, too. Using a <var>FloatNamedArraylist</var>, we can now repair the above example:		Generally, the most useful aspect of <var>FloatNamedArraylists</var> is the first of these items (as it is in our example), but the second can be useful on occasion, too. Using a <var>FloatNamedArraylist</var>, we can now repair the above example:
	<p class="code>%cost is floatNamedArraylist of float auto new		<p class="code">%cost is floatNamedArraylist of float auto new
	...		...
	o: for each occurence of product.no		o: for each occurence of product.no
Line 363:		Line 363:

	But, this still isn't quite right. While one can set a <var>FloatNamedArraylist</var> item whether or not it currently has an explicitly set value, by default you cannot retrieve a value of an item that was never set. Since the assignment statement above first retrieves this current value of the item being updated, a request canceling error is guaranteed the first time it's executed. Fortunately, with the addition of a simple method call, the problem can be fixed:		But, this still isn't quite right. While one can set a <var>FloatNamedArraylist</var> item whether or not it currently has an explicitly set value, by default you cannot retrieve a value of an item that was never set. Since the assignment statement above first retrieves this current value of the item being updated, a request canceling error is guaranteed the first time it's executed. Fortunately, with the addition of a simple method call, the problem can be fixed:
	<p class="code>%cost is floatNamedArraylist of float auto new		<p class="code">%cost is floatNamedArraylist of float auto new
	...		...
	%cost:useDefault = true		%cost:useDefault = true
	o: for each occurence of product.no		o: for each occurence of product.no
	%cost(product.no) = %cost(product.no) + cost(occurrence in o)		%cost(product.no) = %cost(product.no) + cost(occurrence in o)
	end for ,/p>		end for </p>

	This setting of <code>UseDefault</code> to <code>True</code> means that a reference to an unset item number will return a default value which, for a <var>FloatNamedArraylist</var> is, of course, zero (though it could be set to something else, if needed). In fact, a <var>FloatNamedArraylist</var> provides a lower impact way of converting an <var>Array</var> to a collection than does an <var>Arraylist</var>. A <var>FloatNamedArraylist</var> with <code>UseDefault</code> set to <code>True</code> acts exactly like an <var>Array</var> with essentially no limit on the number of items and no cost for unused item numbers. So, if you had a <var>FloatNamedArraylist</var> with used item numbers 1, 500, and 9999, the <var>FloatNamedArraylist</var> would use no more space than if the used item numbers were 1, 2, and 3. This is what's known as a [http://en.wikipedia.org/wiki/Sparse_array sparse array]. Still, even though a <var>FloatNamedArraylist</var> provides a simpler migration from an <var>Array</var>, it is recommended that in the common case where the array/collection items are sequentially added, an <var>Arraylist</var> be used, as this provides a more natural way of representing the data, even though it might be a ~~'''~~little~~'''~~ more work.		This setting of <code>UseDefault</code> to <code>True</code> means that a reference to an unset item number will return a default value which, for a <var>FloatNamedArraylist</var> is, of course, zero (though it could be set to something else, if needed). In fact, a <var>FloatNamedArraylist</var> provides a lower impact way of converting an <var>Array</var> to a collection than does an <var>Arraylist</var>. A <var>FloatNamedArraylist</var> with <code>UseDefault</code> set to <code>True</code> acts exactly like an <var>Array</var> with essentially no limit on the number of items and no cost for unused item numbers. So, if you had a <var>FloatNamedArraylist</var> with used item numbers 1, 500, and 9999, the <var>FloatNamedArraylist</var> would use no more space than if the used item numbers were 1, 2, and 3. This is what's known as a [http://en.wikipedia.org/wiki/Sparse_array sparse array]. Still, even though a <var>FloatNamedArraylist</var> provides a simpler migration from an <var>Array</var>, it is recommended that in the common case where the array/collection items are sequentially added, an <var>Arraylist</var> be used, as this provides a more natural way of representing the data, even though it might be a <strong>little</strong> more work.

	Hopefully, you'll have noticed something unusual in the above code: while <code>UseDefault</code> <i>looks</i> like a function or subroutine invocation, it's actually being set. This is something called a '''property''', though it can also be thought of as a variable, too (much as images have variables that can be set). In any case, objects can have properties or variables with values that can be set or retrieved. The syntactic magic that allows the above <code>True</code> might also catch your attention. A UL programmer would guess that it's a field reference, but it's not — it's simply a boolean value. Hopefully, it seems natural enough that, for now, you're willing to accept and understand its meaning it without fully understanding the syntax.		Hopefully, you'll have noticed something unusual in the above code: while <code>UseDefault</code> <strong>looks</strong> like a function or subroutine invocation, it's actually being set. This is something called a '''property''', though it can also be thought of as a variable, too (much as images have variables that can be set). In any case, objects can have properties or variables with values that can be set or retrieved. The syntactic magic that allows the above <code>True</code> might also catch your attention. A UL programmer would guess that it's a field reference, but it's not — it's simply a boolean value. Hopefully, it seems natural enough that, for now, you're willing to accept and understand its meaning it without fully understanding the syntax.

	As a last note about <var>FloatNamedArraylists</var>, it is possible to loop through only the items that have actually be set in the request. For example, the following prints the index and value for all set <var>FloatNamedArraylist</var> items in <code>%cost</code>:		As a last note about <var>FloatNamedArraylists</var>, it is possible to loop through only the items that have actually be set in the request. For example, the following prints the index and value for all set <var>FloatNamedArraylist</var> items in <code>%cost</code>:

ELowell: /* The magic Item method */

2014-11-10T23:34:32Z

The magic Item method

← Older revision		Revision as of 23:34, 10 November 2014
Line 401:		Line 401:
	In converting an <var>Array</var> to a collection, it's critical that a collection item can be referenced in a syntactically identical way to an <var>Array</var>, namely with <code>%array(<i>subscript</i>)</code>. Not only is this incredibly useful for such a conversion, but it seems very logical and natural; so much so, that one might not give it a second thought.		In converting an <var>Array</var> to a collection, it's critical that a collection item can be referenced in a syntactically identical way to an <var>Array</var>, namely with <code>%array(<i>subscript</i>)</code>. Not only is this incredibly useful for such a conversion, but it seems very logical and natural; so much so, that one might not give it a second thought.

	However, in the object-oriented paradigm, the contents of an an object are ~~'''~~always~~'''~~ accessed by a method or variable name — in <var class="product">SOUL</var> via <code><object>:<member></code> syntax. So, what gives? Well, for collection objects, because the most common operation for a collection and the whole reason for the collection's existance is the ability to extract individual items from the collection, there is a default method if one is not specified explicitly: the <var>Item</var> method. This means that if <code>%foo</code> is an <var>Arraylist</var>, <code>%foo(4)</code> is functionally identical to <code>%foo:item(4)</code>. Which one is used is largely a matter of taste though, again, the fact that <code>%foo(4)</code> seems so natural suggests that there is generally no particularly good reason to explicitly specify <code>Item</code>.		However, in the object-oriented paradigm, the contents of an an object are <strong>always</strong> accessed by a method or variable name — in <var class="product">SOUL</var> via <code><object>:<member></code> syntax. So, what gives? Well, for collection objects, because the most common operation for a collection and the whole reason for the collection's existance is the ability to extract individual items from the collection, there is a default method if one is not specified explicitly: the <var>Item</var> method. This means that if <code>%foo</code> is an <var>Arraylist</var>, <code>%foo(4)</code> is functionally identical to <code>%foo:item(4)</code>. Which one is used is largely a matter of taste though, again, the fact that <code>%foo(4)</code> seems so natural suggests that there is generally no particularly good reason to explicitly specify <code>Item</code>.

	In addition to collections, certain "collection-like" objects such as <var>Stringlists</var> can also use the implied <var>Item</var> method. <var>Stringlists</var> are not, strictly speaking, collections, since they cannot be made up of arbitrary datatypes (they have no <var>Of</var> clause on their declarations). However, for most purposes, they behave very much like an <var>Arraylist</var> of strings, so they are collection-like. As such, if <code>%sl</code> is a <var>Stringlist</var> object, <code>%sl(%i)</code> is functionally identical to <code>%sl:item(%i)</code>.		In addition to collections, certain "collection-like" objects such as <var>Stringlists</var> can also use the implied <var>Item</var> method. <var>Stringlists</var> are not, strictly speaking, collections, since they cannot be made up of arbitrary datatypes (they have no <var>Of</var> clause on their declarations). However, for most purposes, they behave very much like an <var>Arraylist</var> of strings, so they are collection-like. As such, if <code>%sl</code> is a <var>Stringlist</var> object, <code>%sl(%i)</code> is functionally identical to <code>%sl:item(%i)</code>.

ELowell: /* Object-oriented syntax */

2014-11-10T23:33:40Z

Object-oriented syntax

ELowell at 23:23, 10 November 2014

2014-11-10T23:23:33Z

← Older revision		Revision as of 23:23, 10 November 2014
Line 156:		Line 156:
	An experienced UL programmer might raise an eyebrow at the line that contains the <code>$listAdd</code> in the above example. <var>$listAdd</var> is a '''function''', so it returns a value. But the <code>$listAdd</code> is not on the right side of an assignment. What gives? Well, the result of many $functions is usually "uninteresting" to the UL code, so it seems silly to have to find a variable to which to assign it. So the Sirius Mods allows '''certain''' $functions to be invoked without assigning its result to anything. This causes the $function to behave more like a subroutine as subroutines are called without obtaining a return value from the subroutine. It is this blurring of the distinction between functions and subroutines that leads to the OO term '''method''', which is a convenient way of referring to either.		An experienced UL programmer might raise an eyebrow at the line that contains the <code>$listAdd</code> in the above example. <var>$listAdd</var> is a '''function''', so it returns a value. But the <code>$listAdd</code> is not on the right side of an assignment. What gives? Well, the result of many $functions is usually "uninteresting" to the UL code, so it seems silly to have to find a variable to which to assign it. So the Sirius Mods allows '''certain''' $functions to be invoked without assigning its result to anything. This causes the $function to behave more like a subroutine as subroutines are called without obtaining a return value from the subroutine. It is this blurring of the distinction between functions and subroutines that leads to the OO term '''method''', which is a convenient way of referring to either.

	So when you were using $lists, you were using object-oriented programming capabilities, even though you might not have realized it. However, you were '''not''' using object-oriented syntax to access the $list objects, so the benefits of a pure object-oriented facility were not available to you. Now, you might just say "Hold on, didn't you say strings are also objects?" Indeed they are. However, they're objects that can't be changed once they're set (so-called '''immutable''' objects) — you can't really change a string that's been assigned to a variable, you can only assign a new string to that variable. Most objects are not immutable, though of course, strings and numbers are ''heavily'' used, so they have importance disproportionate to their number. Nevertheless, the thing that distinguishes OO languages from non-OO languages is the presence of changeable (non-immutable) objects, so $lists can be viewed as a step toward object-oriented programming.		So when you were using $lists, you were using object-oriented programming capabilities, even though you might not have realized it. However, you were '''not''' using object-oriented syntax to access the $list objects, so the benefits of a pure object-oriented facility were not available to you. Now, you might just say "Hold on, didn't you say strings are also objects?" Indeed they are. However, they're objects that can't be changed once they're set (so-called '''immutable''' objects) — you can't really change a string that's been assigned to a variable, you can only assign a new string to that variable. Most objects are not immutable, though of course, strings and numbers are <i>heavily</i> used, so they have importance disproportionate to their number. Nevertheless, the thing that distinguishes OO languages from non-OO languages is the presence of changeable (non-immutable) objects, so $lists can be viewed as a step toward object-oriented programming.

	The pure object-oriented equivalent of $lists are called '''Stringlists'''. And, using a <var>Stringlist</var> is very similar to using a $list. To illustrate, let's take the above example and convert it to using <var>Stringlists</var>:		The pure object-oriented equivalent of $lists are called '''Stringlists'''. And, using a <var>Stringlist</var> is very similar to using a $list. To illustrate, let's take the above example and convert it to using <var>Stringlists</var>:
Line 323:		Line 323:
	end for </p>		end for </p>

	But, this is unnecessary. One nice thing about collections is you ''always'' have a <var>Count</var> function that returns the number of items in the collection so the above code could simply be written as:		But, this is unnecessary. One nice thing about collections is you <i>always</i> have a <var>Count</var> function that returns the number of items in the collection so the above code could simply be written as:
	<p class="code">for %i from 1 to %cost:count		<p class="code">for %i from 1 to %cost:count
	%x = %cost(%i)		%x = %cost(%i)

ELowell at 23:14, 10 November 2014

2014-11-10T23:14:09Z

ELowell: /* Object-oriented syntax */

2014-11-10T23:07:03Z

Object-oriented syntax

← Older revision		Revision as of 19:33, 16 May 2016
Line 7:		Line 7:
	<li>You're tired of feeling inferior to object-oriented programmers because they speak a language that you don't understand but which sure as heck sounds impressive.		<li>You're tired of feeling inferior to object-oriented programmers because they speak a language that you don't understand but which sure as heck sounds impressive.

	<li>~~You use [[Sirius Software]] products and Sirius has announced that all new~~ <var class="product">User Language</var> functionality will use object-oriented syntax.		<li>New <var class="product">User Language/SOUL</var> functionality will use object-oriented syntax.

	<li>"Object-oriented" looks better on your resume than "User Language."		<li>"Object-oriented" looks better on your resume than "User Language."
Line 89:		Line 89:

	==Object-oriented syntax==		==Object-oriented syntax==
	The most pernicious difference between OO languages and procedural languages such as <var class="product">User Language</var> (called "UL" from here on) is the syntax. And the biggest syntactic difference between OO and UL is how functions and subroutines are invoked. Let's start with functions. All UL programmers know how to invoke a function.		The most pernicious difference between OO languages and procedural languages such as <var class="product">User Language</var> (called "UL" from here on) is the syntax. And the biggest syntactic difference between OO and UL is how functions and subroutines are invoked. Let's start with functions. All User Language programmers know how to invoke a function.

	First, functions are called $functions (dollar-functions) or £functions (pound-functions) in the UK. $functions (except ~~some of the Sirius $functions~~) <strong>always</strong> return a value so must ~~either~~ be on the right side of an assignment, input to a subroutine or other $function call, or inside some UL expression. The following example, has a $~~substr~~ in all three contexts:		First, functions are called $functions (dollar-functions) or £functions (pound-functions) in the UK. $functions (except a very few) <strong>always</strong> return a value, so they must be on the right side of an assignment, input to a subroutine or other $function call, or inside some User Language expression. The following example, has <var>[[$Substr]]</var> in all three contexts:
	<p class="code">%x = $substr(%y, 3, 10)		<p class="code">%x = $substr(%y, 3, 10)
	call clever($substr(%y, %start, %len))		call clever($substr(%y, %start, %len))
	%z = $substr(%y, %len, 1) + 10		%z = $substr(%y, %len, 1) + 10
	</p>		</p>
	As the above example shows, and all UL programmers know, a $function can be followed by the $function arguments (inputs) in parentheses with multiple arguments separated by commas.		As the above example shows, and all User Language programmers know, a $function can be followed by the $function arguments (inputs) in parentheses with multiple arguments separated by commas.

	OO functions, on the other hand, use a syntax where a function invocation consists of the thing (object, if you will) that the function is operating on specified <strong>before</strong> the function name, followed by its arguments inside parentheses. Many $functions have OO equivalents and $~~substr~~ is no exception: its OO equivalent is called <var>[[Substring (String function)\|Substring]]</var>. The following illustrates the use of the OO <var>Substring</var> function by replacing "$substr" in the previous example with "substring":		OO functions, on the other hand, use a syntax where a function invocation consists of the thing (object, if you will) that the function is operating on specified <strong>before</strong> the function name, followed by its arguments inside parentheses. Many $functions have OO equivalents and <var>$Substr</var> is no exception: its OO equivalent is called <var>[[Substring (String function)\|Substring]]</var>. The following illustrates the use of the OO <var>Substring</var> function by replacing "$substr" in the previous example with "substring":
	<p class="code">%x = %y:substring(3, 10)		<p class="code">%x = %y:substring(3, 10)
	call clever(%y:substring(%start, %len))		call clever(%y:substring(%start, %len))
Line 104:		Line 104:
	</p>		</p>

	While this might look strange to a <var class="product">User Language</var> programmer, it uses the most common OO syntax so can honestly be called OO programming. So, if you find any "$substr" call in your system and change it to use <var>Substring</var> (moving the first argument before a <code>:substring</code>), you have now done some OO coding. It's that easy!		While this might look strange to a <var class="product">User Language</var> programmer, it uses the most common OO syntax so can honestly be called OO programming. So, if you find any <code>$substr</code> call in your system and change it to use <var>Substring</var> (moving the first argument before a <code>:substring</code>), you have now done some OO coding. It's that easy!

	To further add to your bona fides as an object oriented programmer, don't call <var>Substring</var> a function, but call it a '''method'''. In addition, don't call <code>%y</code> just a string, call it a '''string object'''. Now you're ready for something more advanced. Say "I applied the <var>Substring</var> method to the <var>String</var> object". Repeat until it feels natural to say it. Congratulations, you're well on your way to becoming an OO programmer and, maybe even a guru. If you're curious about what you just said:		To further add to your bona fides as an object oriented programmer, don't call <var>Substring</var> a function, but call it a '''method'''. In addition, don't call <code>%y</code> just a string, call it a '''string object'''. Now you're ready for something more advanced. Say "I applied the <var>Substring</var> method to the <var>String</var> object". Repeat until it feels natural to say it. Congratulations, you're well on your way to becoming an OO programmer and, maybe even a guru. If you're curious about what you just said:
	<ul>		<ul>
	<li>Method is just a fancy word that means function or subroutine or any other called code that does something.		<li>Method is just a fancy word that means function or subroutine or any other called code that does something. </li>
	<li>Object is just a fancy word for a "thingy."		<li>Object is just a fancy word for a "thingy." </li>
	</ul>		</ul>
	Now, of course, there are many functions available other than just <var>Substring</var>. The functions that operate on strings are called '''Intrinsic String methods'''. You can find a list of the methods at [[List of String methods]]. There are also functions that operate on numbers. The list of these can be found at [[List of Float methods]].		Now, of course, there are many functions available other than just <var>Substring</var>. The functions that operate on strings are called '''Intrinsic String methods'''. You can find a list of the methods at [[List of String methods]]. There are also functions that operate on numbers. The list of these can be found at [[List of Float methods]].
Line 142:		Line 142:

	==Stringlists==		==Stringlists==
	The object-oriented extensions to <var class="product">User Language</var> use [[$lists]]. Most sites that <i>can</i> use $lists, <i>do</i> use $lists, because many [[List of $functions\|~~Sirius~~ $functions]] require them as input or outputs, and because they are just generally useful.		The object-oriented extensions to <var class="product">User Language</var> use [[$lists]]. Most sites that <i>can</i> use $lists, <i>do</i> use $lists, because many [[List of $functions\|$functions]] require them as input or outputs, and because they are just generally useful.
	$lists are essentially objects because an object is a container for information that is accessed via a reference variable, and multiple reference variables can refer to the same object ($list). For example:		$lists are essentially objects because an object is a container for information that is accessed via a reference variable, and multiple reference variables can refer to the same object ($list). For example:
	<p class="code">%list is float		<p class="code">%list is float
Line 154:		Line 154:
	In this example, the <code>Print</code> statement would end up printing "Now is the winter" even though the <code>$listAdd</code> added the line to <code>%list</code>.		In this example, the <code>Print</code> statement would end up printing "Now is the winter" even though the <code>$listAdd</code> added the line to <code>%list</code>.
	Both <code>%list</code> and <code>%list2</code> point to the same $list (object) and so, it is not surprising that what is added via <code>%list</code> can be seen via <code>%list2</code>. It is clear, too, that <code>%list</code> and <code>%list2</code> must be '''pointers''' to $list objects and cannot be the objects, themselves, since a <var>Float</var> value couldn't possibly hold the contents of a $list.		Both <code>%list</code> and <code>%list2</code> point to the same $list (object) and so, it is not surprising that what is added via <code>%list</code> can be seen via <code>%list2</code>. It is clear, too, that <code>%list</code> and <code>%list2</code> must be '''pointers''' to $list objects and cannot be the objects, themselves, since a <var>Float</var> value couldn't possibly hold the contents of a $list.
	An experienced UL programmer might raise an eyebrow at the line that contains the <code>$listAdd</code> in the above example. <var>$listAdd</var> is a '''function''', so it returns a value. But the <code>$listAdd</code> is not on the right side of an assignment. What gives? Well, the result of many $functions is usually "uninteresting" to the UL code, so it seems silly to have to find a variable to which to assign it. So ~~the Sirius Mods~~ allows <strong>certain</strong> $functions to be invoked without assigning its result to anything. This causes the $function to behave more like a subroutine as subroutines are called without obtaining a return value from the subroutine. It is this blurring of the distinction between functions and subroutines that leads to the OO term '''method''', which is a convenient way of referring to either.		An experienced UL programmer might raise an eyebrow at the line that contains the <code>$listAdd</code> in the above example. <var>$listAdd</var> is a '''function''', so it returns a value. But the <code>$listAdd</code> is not on the right side of an assignment. What gives? Well, the result of many $functions is usually "uninteresting" to the User language code, so it seems silly to have to find a variable to which to assign it. So SOUL allows <strong>certain</strong> $functions to be invoked without assigning its result to anything. This causes the $function to behave more like a subroutine as subroutines are called without obtaining a return value from the subroutine. It is this blurring of the distinction between functions and subroutines that leads to the OO term '''method''', which is a convenient way of referring to either.

	So when you were using $lists, you were using object-oriented programming capabilities, even though you might not have realized it. However, you were <strong>not</strong> using object-oriented syntax to access the $list objects, so the benefits of a pure object-oriented facility were not available to you. Now, you might just say "Hold on, didn't you say strings are also objects?" Indeed they are. However, they're objects that can't be changed once they're set (so-called '''immutable''' objects) — you can't really change a string that's been assigned to a variable, you can only assign a new string to that variable. Most objects are not immutable, though of course, strings and numbers are <i>heavily</i> used, so they have importance disproportionate to their number. Nevertheless, the thing that distinguishes OO languages from non-OO languages is the presence of changeable (non-immutable) objects, so $lists can be viewed as a step toward object-oriented programming.		So when you were using $lists, you were using object-oriented programming capabilities, even though you might not have realized it. However, you were <strong>not</strong> using object-oriented syntax to access the $list objects, so the benefits of a pure object-oriented facility were not available to you. Now, you might just say "Hold on, didn't you say strings are also objects?" Indeed they are. However, they're objects that can't be changed once they're set (so-called '''immutable''' objects) — you can't really change a string that's been assigned to a variable, you can only assign a new string to that variable. Most objects are not immutable, though of course, strings and numbers are <i>heavily</i> used, so they have importance disproportionate to their number. Nevertheless, the thing that distinguishes OO languages from non-OO languages is the presence of changeable (non-immutable) objects, so $lists can be viewed as a step toward object-oriented programming.

← Older revision		Revision as of 23:33, 10 November 2014
Line 91:		Line 91:
	The most pernicious difference between OO languages and procedural languages such as <var class="product">User Language</var> (called "UL" from here on) is the syntax. And the biggest syntactic difference between OO and UL is how functions and subroutines are invoked. Let's start with functions. All UL programmers know how to invoke a function.		The most pernicious difference between OO languages and procedural languages such as <var class="product">User Language</var> (called "UL" from here on) is the syntax. And the biggest syntactic difference between OO and UL is how functions and subroutines are invoked. Let's start with functions. All UL programmers know how to invoke a function.

	First, functions are called $functions (dollar-functions) or £functions (pound-functions) in the UK. $functions (except some of the Sirius $functions) <b>always</b> return a value so must either be on the right side of an assignment, input to a subroutine or other $function call, or inside some UL expression. The following example, has a $substr in all three contexts:		First, functions are called $functions (dollar-functions) or £functions (pound-functions) in the UK. $functions (except some of the Sirius $functions) <strong>always</strong> return a value so must either be on the right side of an assignment, input to a subroutine or other $function call, or inside some UL expression. The following example, has a $substr in all three contexts:
	<p class="code">%x = $substr(%y, 3, 10)		<p class="code">%x = $substr(%y, 3, 10)
	call clever($substr(%y, %start, %len))		call clever($substr(%y, %start, %len))
Line 98:		Line 98:
	As the above example shows, and all UL programmers know, a $function can be followed by the $function arguments (inputs) in parentheses with multiple arguments separated by commas.		As the above example shows, and all UL programmers know, a $function can be followed by the $function arguments (inputs) in parentheses with multiple arguments separated by commas.

	OO functions, on the other hand, use a syntax where a function invocation consists of the thing (object, if you will) that the function is operating on specified <b>before</b> the function name, followed by its arguments inside parentheses. Many $functions have OO equivalents and $substr is no exception: its OO equivalent is called <var>[[Substring (String function)\|Substring]]</var>. The following illustrates the use of the OO <var>Substring</var> function by replacing "$substr" in the previous example with "substring":		OO functions, on the other hand, use a syntax where a function invocation consists of the thing (object, if you will) that the function is operating on specified <strong>before</strong> the function name, followed by its arguments inside parentheses. Many $functions have OO equivalents and $substr is no exception: its OO equivalent is called <var>[[Substring (String function)\|Substring]]</var>. The following illustrates the use of the OO <var>Substring</var> function by replacing "$substr" in the previous example with "substring":
	<p class="code">%x = %y:substring(3, 10)		<p class="code">%x = %y:substring(3, 10)
	call clever(%y:substring(%start, %len))		call clever(%y:substring(%start, %len))
Line 114:		Line 114:

	Now, while congratulating yourself on your new-found skills, you might have a gnawing feeling that you really haven't accomplished a lot, as much as you have learned. So what have you accomplished? Is OO syntax really better than what you're used to? At first blush, it would seem worse, as the traditional $function call is more like English, where verb (function name) precedes the object (first parameter), as opposed to the OO syntax, where the order is reversed. For example, one would say "get the substring of %y" not "%y get the substring," so		Now, while congratulating yourself on your new-found skills, you might have a gnawing feeling that you really haven't accomplished a lot, as much as you have learned. So what have you accomplished? Is OO syntax really better than what you're used to? At first blush, it would seem worse, as the traditional $function call is more like English, where verb (function name) precedes the object (first parameter), as opposed to the OO syntax, where the order is reversed. For example, one would say "get the substring of %y" not "%y get the substring," so
	<code>%x = $substr(%y, 2, 3)</code> ~~'''~~seems~~'''~~ more natural than		<code>%x = $substr(%y, 2, 3)</code> <strong>seems</strong> more natural than
	<code>%x = %y:substring(2, 3)</code>.		<code>%x = %y:substring(2, 3)</code>.
	While this might be true, it's easy enough to get used to the second form — in many languages the object comes before the verb.		While this might be true, it's easy enough to get used to the second form — in many languages the object comes before the verb.
Line 139:		Line 139:
	<p class="code">%x = %y:right(20, '0') </p>		<p class="code">%x = %y:right(20, '0') </p>

	In functions with large numbers of parameters, the named parameters can also be very useful for eliminating the need for placeholder commas, and for making the function invocations more readable. String and Float methods tend not to have a lot of parameters so named parameters are not heavily used for them, but they <b>are</b> used here and there, so it's important to understand them.		In functions with large numbers of parameters, the named parameters can also be very useful for eliminating the need for placeholder commas, and for making the function invocations more readable. String and Float methods tend not to have a lot of parameters so named parameters are not heavily used for them, but they <strong>are</strong> used here and there, so it's important to understand them.

	==Stringlists==		==Stringlists==

← Older revision		Revision as of 23:14, 10 November 2014
Line 91:		Line 91:
	The most pernicious difference between OO languages and procedural languages such as <var class="product">User Language</var> (called "UL" from here on) is the syntax. And the biggest syntactic difference between OO and UL is how functions and subroutines are invoked. Let's start with functions. All UL programmers know how to invoke a function.		The most pernicious difference between OO languages and procedural languages such as <var class="product">User Language</var> (called "UL" from here on) is the syntax. And the biggest syntactic difference between OO and UL is how functions and subroutines are invoked. Let's start with functions. All UL programmers know how to invoke a function.

	First, functions are called $functions (dollar-functions) or £functions (pound-functions) in the UK. $functions (except some of the Sirius $functions) ~~'''~~always~~'''~~ return a value so must either be on the right side of an assignment, input to a subroutine or other $function call, or inside some UL expression. The following example, has a $substr in all three contexts:		First, functions are called $functions (dollar-functions) or £functions (pound-functions) in the UK. $functions (except some of the Sirius $functions) <b>always</b> return a value so must either be on the right side of an assignment, input to a subroutine or other $function call, or inside some UL expression. The following example, has a $substr in all three contexts:
	<p class="code">%x = $substr(%y, 3, 10)		<p class="code">%x = $substr(%y, 3, 10)
	call clever($substr(%y, %start, %len))		call clever($substr(%y, %start, %len))
Line 142:		Line 142:

	==Stringlists==		==Stringlists==
	The object-oriented extensions to <var class="product">User Language</var> use [[$lists]]. Most sites that ''can'' use $lists, ''do'' use $lists, because many [[List of $functions\|Sirius $functions]] require them as input or outputs, and because they are just generally useful.		The object-oriented extensions to <var class="product">User Language</var> use [[$lists]]. Most sites that <i>can</i> use $lists, <i>do</i> use $lists, because many [[List of $functions\|Sirius $functions]] require them as input or outputs, and because they are just generally useful.
	$lists are essentially objects because an object is a container for information that is accessed via a reference variable, and multiple reference variables can refer to the same object ($list). For example:		$lists are essentially objects because an object is a container for information that is accessed via a reference variable, and multiple reference variables can refer to the same object ($list). For example:
	<p class="code">%list is float		<p class="code">%list is float
Line 177:		Line 177:
	%list = %list2 <span style="color:red;"><==Invalid</span> </p>		%list = %list2 <span style="color:red;"><==Invalid</span> </p>

	While this might not seem that useful, it can be much more useful in complex applications with lots of different kinds of objects — except for strings and numbers, only object variables of the same ''class'' can be assigned to each other. "Wait a minute, what's a class?" you say. A '''class''' is simply a name for objects with identical characteristics. In this case, all <var>Stringlists</var> have a similar structure and have a fixed set of things you can do with them (like $lists). The distinction between a class and individual objects is the same as in normal usage — my blue Subaru is an object in the class of cars.		While this might not seem that useful, it can be much more useful in complex applications with lots of different kinds of objects — except for strings and numbers, only object variables of the same "class" can be assigned to each other. "Wait a minute, what's a class?" you say. A '''class''' is simply a name for objects with identical characteristics. In this case, all <var>Stringlists</var> have a similar structure and have a fixed set of things you can do with them (like $lists). The distinction between a class and individual objects is the same as in normal usage — my blue Subaru is an object in the class of cars.

	In any case, beyond the protection of accidental assignment mismatches, what else has using an OO <var>Stringlist</var> instead of a traditional $list bought us? Well, compare:		In any case, beyond the protection of accidental assignment mismatches, what else has using an OO <var>Stringlist</var> instead of a traditional $list bought us? Well, compare:
Line 184:		Line 184:
	<p class="code">%list:add('Now is the winter') </p>		<p class="code">%list:add('Now is the winter') </p>

	In the former, when the UL compiler hits the <code>$listAdd</code>, it has no idea that it's working with a $list. So, to distinguish <code>$listAdd</code> from other functions that might be doing an add of something to something, the word ''list'' has to be used as a qualifier in the $function name — it would not do to have the $function called simply <code>$add</code>. But, with the OO syntax, the compiler first hits the <code>%list</code> so now "knows" that whatever follows must be something specific to a <var>Stringlist</var>. So it is sufficient to use the function name <code>Add</code> because it can only mean the <var>Add</var> that applies to <var>Stringlists</var>, not to other classes. This means the following:		In the former, when the UL compiler hits the <code>$listAdd</code>, it has no idea that it's working with a $list. So, to distinguish <code>$listAdd</code> from other functions that might be doing an add of something to something, the word "list" has to be used as a qualifier in the $function name — it would not do to have the $function called simply <code>$add</code>. But, with the OO syntax, the compiler first hits the <code>%list</code> so now "knows" that whatever follows must be something specific to a <var>Stringlist</var>. So it is sufficient to use the function name <code>Add</code> because it can only mean the <var>Add</var> that applies to <var>Stringlists</var>, not to other classes. This means the following:
	<ul>		<ul>
	<li>The OO statements tend to be shorter, because the extra qualifiers on the function names are unnecessary. This is often true even when the OO statements use longer, more meaningful function names than the non-OO equivalents.		<li>The OO statements tend to be shorter, because the extra qualifiers on the function names are unnecessary. This is often true even when the OO statements use longer, more meaningful function names than the non-OO equivalents.
Line 220:		Line 220:
	<p class="note"><b>Note:</b> <var>Stringlists</var> are no more or less efficient than $lists; in fact, they share most of the same underlying code. </p>		<p class="note"><b>Note:</b> <var>Stringlists</var> are no more or less efficient than $lists; in fact, they share most of the same underlying code. </p>

	Also, all <var>Stringlist</var> methods are ~~'''~~longstring capable~~'''~~. That is, they a accept and return <var>[[Longstrings\|Longstring]]</var> values (strings longer than 255 bytes). For historic reasons, the $list API contains a mix of longstring-capable and non-longstring-capable functions. Many of the non-longstring-capable $functions have extra parameters to deal with the fact that, while $list items could be longer than 255 bytes, they could only be processed 255 bytes at a time. The <var>Stringlist</var> API, written well after longstrings became available, didn't need to deal with any of these issues. This means that the $list API is considerably more complicated than the <var>Stringlist</var> API, without providing ''any'' additional functionality. This is just another reason to use the <var>Stringlists</var> in lieu of $lists.		Also, all <var>Stringlist</var> methods are <b>longstring capable</b>. That is, they a accept and return <var>[[Longstrings\|Longstring]]</var> values (strings longer than 255 bytes). For historic reasons, the $list API contains a mix of longstring-capable and non-longstring-capable functions. Many of the non-longstring-capable $functions have extra parameters to deal with the fact that, while $list items could be longer than 255 bytes, they could only be processed 255 bytes at a time. The <var>Stringlist</var> API, written well after longstrings became available, didn't need to deal with any of these issues. This means that the $list API is considerably more complicated than the <var>Stringlist</var> API, without providing <i>any</i> additional functionality. This is just another reason to use the <var>Stringlists</var> in lieu of $lists.

	So, in keeping with the theme of this page the recommendations are:		So, in keeping with the theme of this page the recommendations are:
Line 233:		Line 233:
	Collections are essentially object-oriented replacements for traditional Model 204 arrays, but, as you'll see, with considerably more functionality.		Collections are essentially object-oriented replacements for traditional Model 204 arrays, but, as you'll see, with considerably more functionality.

	Model 204 arrays, unlike $lists, are most certainly ''not'' objects in the OO sense, because <var>Array</var> variables are not references to array objects, they are the arrays themselves. There is no way to have two variables referencing the same array (except in the special case of arrays being passed as parameters), and arrays are created at compile-time, unlike objects (and $lists) which are created at run-time. In addition to making arrays non-OO, these restrictions can be problematic for applications:		Model 204 arrays, unlike $lists, are most certainly <i>not</i> objects in the OO sense, because <var>Array</var> variables are not references to array objects, they are the arrays themselves. There is no way to have two variables referencing the same array (except in the special case of arrays being passed as parameters), and arrays are created at compile-time, unlike objects (and $lists) which are created at run-time. In addition to making arrays non-OO, these restrictions can be problematic for applications:
	<ul>		<ul>
	<li>Application coders must determine ahead of time what the largest number of array items will be and allocate space for them, at compile time. This is both:		<li>Application coders must determine ahead of time what the largest number of array items will be and allocate space for them, at compile time. This is both:
Line 301:		Line 301:
	While in many instances this is a bad idea (since it can become unclear in the code where an object will be first created or where it's first intended to be created), experience has shown that, at least for collections, the use of <code>Auto New</code> usually works out fairly well. This is especially the case for applications where an <var>Array</var> was changed to an <var>Arraylist</var>.		While in many instances this is a bad idea (since it can become unclear in the code where an object will be first created or where it's first intended to be created), experience has shown that, at least for collections, the use of <code>Auto New</code> usually works out fairly well. This is especially the case for applications where an <var>Array</var> was changed to an <var>Arraylist</var>.

	But we hit a second problem with the above code: an attempt to set item number <code>%ncost</code> in the <var>Arraylist</var> in the above example will almost cause request cancellation, because that item won't be there, yet. This is really no different from the <var>Array</var> code where, if you tried to add a 21'st item to the array, you would get a request cancellation because the array was declared to have 20 items. However, because the array is created at compile-time with 20 entries, one ''can'' simply set items 1 through 20. When switching the code to use an <var>Arraylist</var>, the code will have to be changed, somewhat:		But we hit a second problem with the above code: an attempt to set item number <code>%ncost</code> in the <var>Arraylist</var> in the above example will almost cause request cancellation, because that item won't be there, yet. This is really no different from the <var>Array</var> code where, if you tried to add a 21'st item to the array, you would get a request cancellation because the array was declared to have 20 items. However, because the array is created at compile-time with 20 entries, one <i>can</i> simply set items 1 through 20. When switching the code to use an <var>Arraylist</var>, the code will have to be changed, somewhat:
	<p class="code">%cost is arraylist of float auto new		<p class="code">%cost is arraylist of float auto new
	%ncost is float		%ncost is float
Line 372:		Line 372:
	This setting of <code>UseDefault</code> to <code>True</code> means that a reference to an unset item number will return a default value which, for a <var>FloatNamedArraylist</var> is, of course, zero (though it could be set to something else, if needed). In fact, a <var>FloatNamedArraylist</var> provides a lower impact way of converting an <var>Array</var> to a collection than does an <var>Arraylist</var>. A <var>FloatNamedArraylist</var> with <code>UseDefault</code> set to <code>True</code> acts exactly like an <var>Array</var> with essentially no limit on the number of items and no cost for unused item numbers. So, if you had a <var>FloatNamedArraylist</var> with used item numbers 1, 500, and 9999, the <var>FloatNamedArraylist</var> would use no more space than if the used item numbers were 1, 2, and 3. This is what's known as a [http://en.wikipedia.org/wiki/Sparse_array sparse array]. Still, even though a <var>FloatNamedArraylist</var> provides a simpler migration from an <var>Array</var>, it is recommended that in the common case where the array/collection items are sequentially added, an <var>Arraylist</var> be used, as this provides a more natural way of representing the data, even though it might be a '''little''' more work.		This setting of <code>UseDefault</code> to <code>True</code> means that a reference to an unset item number will return a default value which, for a <var>FloatNamedArraylist</var> is, of course, zero (though it could be set to something else, if needed). In fact, a <var>FloatNamedArraylist</var> provides a lower impact way of converting an <var>Array</var> to a collection than does an <var>Arraylist</var>. A <var>FloatNamedArraylist</var> with <code>UseDefault</code> set to <code>True</code> acts exactly like an <var>Array</var> with essentially no limit on the number of items and no cost for unused item numbers. So, if you had a <var>FloatNamedArraylist</var> with used item numbers 1, 500, and 9999, the <var>FloatNamedArraylist</var> would use no more space than if the used item numbers were 1, 2, and 3. This is what's known as a [http://en.wikipedia.org/wiki/Sparse_array sparse array]. Still, even though a <var>FloatNamedArraylist</var> provides a simpler migration from an <var>Array</var>, it is recommended that in the common case where the array/collection items are sequentially added, an <var>Arraylist</var> be used, as this provides a more natural way of representing the data, even though it might be a '''little''' more work.

	Hopefully, you'll have noticed something unusual in the above code: while <code>UseDefault</code> ''looks'' like a function or subroutine invocation, it's actually being set. This is something called a '''property''', though it can also be thought of as a variable, too (much as images have variables that can be set). In any case, objects can have properties or variables with values that can be set or retrieved. The syntactic magic that allows the above <code>True</code> might also catch your attention. A UL programmer would guess that it's a field reference, but it's not — it's simply a boolean value. Hopefully, it seems natural enough that, for now, you're willing to accept and understand its meaning it without fully understanding the syntax.		Hopefully, you'll have noticed something unusual in the above code: while <code>UseDefault</code> <i>looks</i> like a function or subroutine invocation, it's actually being set. This is something called a '''property''', though it can also be thought of as a variable, too (much as images have variables that can be set). In any case, objects can have properties or variables with values that can be set or retrieved. The syntactic magic that allows the above <code>True</code> might also catch your attention. A UL programmer would guess that it's a field reference, but it's not — it's simply a boolean value. Hopefully, it seems natural enough that, for now, you're willing to accept and understand its meaning it without fully understanding the syntax.

	As a last note about <var>FloatNamedArraylists</var>, it is possible to loop through only the items that have actually be set in the request. For example, the following prints the index and value for all set <var>FloatNamedArraylist</var> items in <code>%cost</code>:		As a last note about <var>FloatNamedArraylists</var>, it is possible to loop through only the items that have actually be set in the request. For example, the following prints the index and value for all set <var>FloatNamedArraylist</var> items in <code>%cost</code>:

← Older revision		Revision as of 23:07, 10 November 2014
Line 89:		Line 89:

	==Object-oriented syntax==		==Object-oriented syntax==
	The most pernicious difference between OO languages and procedural languages such as <var class="product">User Language</var> (called ''UL'' from here on) is the syntax. And the biggest syntactic difference between OO and UL is how functions and subroutines are invoked. Let's start with functions. All UL programmers know how to invoke a function.		The most pernicious difference between OO languages and procedural languages such as <var class="product">User Language</var> (called "UL" from here on) is the syntax. And the biggest syntactic difference between OO and UL is how functions and subroutines are invoked. Let's start with functions. All UL programmers know how to invoke a function.

	First, functions are called $functions (dollar-functions) or £functions (pound-functions) in the UK. $functions (except some of the Sirius $functions) '''always''' return a value so must either be on the right side of an assignment, input to a subroutine or other $function call, or inside some UL expression. The following example, has a $substr in all three contexts:		First, functions are called $functions (dollar-functions) or £functions (pound-functions) in the UK. $functions (except some of the Sirius $functions) '''always''' return a value so must either be on the right side of an assignment, input to a subroutine or other $function call, or inside some UL expression. The following example, has a $substr in all three contexts:
Line 98:		Line 98:
	As the above example shows, and all UL programmers know, a $function can be followed by the $function arguments (inputs) in parentheses with multiple arguments separated by commas.		As the above example shows, and all UL programmers know, a $function can be followed by the $function arguments (inputs) in parentheses with multiple arguments separated by commas.

	OO functions, on the other hand, use a syntax where a function invocation consists of the thing (object, if you will) that the function is operating on specified ~~'''~~before~~'''~~ the function name, followed by its arguments inside parentheses. Many $functions have OO equivalents and $substr is no exception: its OO equivalent is called <var>[[Substring (String function)\|Substring]]</var>. The following illustrates the use of the OO <var>Substring</var> function by replacing ''$substr'' in the previous example with ''substring'':		OO functions, on the other hand, use a syntax where a function invocation consists of the thing (object, if you will) that the function is operating on specified <b>before</b> the function name, followed by its arguments inside parentheses. Many $functions have OO equivalents and $substr is no exception: its OO equivalent is called <var>[[Substring (String function)\|Substring]]</var>. The following illustrates the use of the OO <var>Substring</var> function by replacing "$substr" in the previous example with "substring":
	<p class="code">%x = %y:substring(3, 10)		<p class="code">%x = %y:substring(3, 10)
	call clever(%y:substring(%start, %len))		call clever(%y:substring(%start, %len))
Line 104:		Line 104:
	</p>		</p>

	While this might look strange to a <var class="product">User Language</var> programmer, it uses the most common OO syntax so can honestly be called OO programming. So, if you find any ''$substr'' call in your system and change it to use <var>Substring</var> (moving the first argument before a <code>:substring</code>), you have now done some OO coding. It's that easy!		While this might look strange to a <var class="product">User Language</var> programmer, it uses the most common OO syntax so can honestly be called OO programming. So, if you find any "$substr" call in your system and change it to use <var>Substring</var> (moving the first argument before a <code>:substring</code>), you have now done some OO coding. It's that easy!

	To further add to your bona fides as an object oriented programmer, don't call <var>Substring</var> a function, but call it a '''method'''. In addition, don't call <code>%y</code> just a string, call it a '''string object'''. Now you're ready for something more advanced. Say "I applied the <var>Substring</var> method to the <var>String</var> object". Repeat until it feels natural to say it. Congratulations, you're well on your way to becoming an OO programmer and, maybe even a guru. If you're curious about what you just said:		To further add to your bona fides as an object oriented programmer, don't call <var>Substring</var> a function, but call it a '''method'''. In addition, don't call <code>%y</code> just a string, call it a '''string object'''. Now you're ready for something more advanced. Say "I applied the <var>Substring</var> method to the <var>String</var> object". Repeat until it feels natural to say it. Congratulations, you're well on your way to becoming an OO programmer and, maybe even a guru. If you're curious about what you just said:
Line 121:		Line 121:
	<p class="code">%x = %y:substring(%start, %len):toUpper:unspace </p>		<p class="code">%x = %y:substring(%start, %len):toUpper:unspace </p>

	This reads rather nicely, left to right: take ''%y'', get a substring, convert to uppercase, and remove extra blanks. The traditional version doesn't read nearly as nicely:		This reads rather nicely, left to right: take "%y", get a substring, convert to uppercase, and remove extra blanks. The traditional version doesn't read nearly as nicely:
	<p class="code">%x = $unspace($upcase($substr(%y, %start, %len)))</p>		<p class="code">%x = $unspace($upcase($substr(%y, %start, %len)))</p>

Line 139:		Line 139:
	<p class="code">%x = %y:right(20, '0') </p>		<p class="code">%x = %y:right(20, '0') </p>

	In functions with large numbers of parameters, the named parameters can also be very useful for eliminating the need for placeholder commas, and for making the function invocations more readable. String and Float methods tend not to have a lot of parameters so named parameters are not heavily used for them, but they ~~'''~~are~~'''~~ used here and there, so it's important to understand them.		In functions with large numbers of parameters, the named parameters can also be very useful for eliminating the need for placeholder commas, and for making the function invocations more readable. String and Float methods tend not to have a lot of parameters so named parameters are not heavily used for them, but they <b>are</b> used here and there, so it's important to understand them.

	==Stringlists==		==Stringlists==