Commonly used Propeller methods: Need some feedback.

Oldbitcollector (Jeff)

I'm working on a document of commonly used methods. I could use some feedback on these and if anyone else sees some I missed.

Thanks
OBC

---

An object’s prefix name is flexible, and is defined at the time the object is called in the OBJ section of the main program. The examples used in this document with use the name “myobject”.


START

The .start method is found in most objects as it is used to launch the object into one of the Propeller’s additional cogs. It also commonly passes I/O or configuration information to the object as well.

myobject.start(9600)
myobject.start(12)
myobject.start(my_variable,my_variable2)


STOP

The .stop method is the opposite of .start. It stops the object and frees the cog.


STR

The .str method can be found in various display and communications objects.
It is commonly used for displaying text or the contents of a variable.

myobject.str(string(“Display a line of text”))
myobject.str(string(“Display a line of text with a carrage return”,13))
myobject.str(my_multibyte_variable)




DEC

The .dec method can be found in various display and communication objects.
It is commonly used for displaying the decimal value of a variable.

myobject.dec(my_variable)


HEX

The .hex method can be found in various display and communication objects.
It is commonly used for displaying the hexadecimal value of a variable.
The secondary data (2 in the example) defines the number places to calculate.

myobject.hex(my_variable,2)


BIN

The .bin method can be found in various display and communication objects.
It is commonly used for displaying the binary value of a variable.
The secondary data (8 in the example) defines the number of digits to calculate.

myobject.bin(my_variable,8)


OUT (or TX)

The .out (sometimes called, .tx) method can be found in various display and communication objects. It is commonly used for displaying the variable. In the case of a video driver, the display will act on the contents of the variable instead of displaying the number itself. .out($08) sends a backspace, instead of displaying an “8”.


NEWLINE

The .newline method can be found in various display and communication objects. It is used to send a carriage return to the device.

Duane Degn

I think the PST object uses CHAR instead of OUT or TX.

I see INIT a lot in objects. It's mainly used to setup varibles in an object that don't use thier own cog. Some objects require a call to INIT before calling START.

Microcontrolled

I've never seen the .newline command used, as most use .out($0D) or .out(13) to specify a new line. If this is aimed at beginner programmers you also might want to note that Decimal, Hexadecimal, and Binary are all just different ways of writing the same thing, not different formats all together. When I started programming it took me a while to figure this out.
Also, if you have a variable array you want to display with .str, you don't use the "string" command, you just use the pointer
myobj.str(@variableArray)
OR
myobj.str(@variableArray[x])
with "x" being the variable to start with.

Oldbitcollector (Jeff)

@Microcontrolled.

Good points both! I'll make the adjustment on that str variable entry. Duh!
Hence the reason for a second set of eyes. Thanks


@Duane

Will add the INIT entry under START -- Thanks

localroger

It's probably worth at least noting that while you will have to deal with tv.hex, serial.hex, vga.hex, etc. because those methods are traditionally packed with similar objects, by the time you get four or five of those objects in RAM it's a considerable waste of redundant code and you still don't have a fixed-width decimal output or any way to parse incoming numeric values. It would be better all around if the character objects just supported TX and blocking and non-blocking RX and left the rest of that cruft to a universal string library. Of course that would be a little harder for the n00bs to use but it would be a lot more efficient and powerful.(As an implementation hint you can use local array variables as temporary strings; just because they're long-aligned doesn't mean you can't do byte[@localvar+offset]. Of course you can't return such values to the caller but you can make the caller pass you a buffer in which to return the result.

Dave Hein

I think it is good to tell newbies that START and STOP are the standard method names for starting and stopping cogs. However, the other method names are mostly used for for console I/O and serial I/O. It might be useful to have a table that lists the various methods supported by these I/O objects.

I agree with localroger about the TX, DEC, HEX and other routines. I am amazed that experienced Spin programmers print "formatted" output by intermixing calls to STR, TX, DEC, HEX and so on. I think most people do it so that their programs support the lowest common denominator of serial/video/VGA driver. It would be nice if we could start using some standard formatted I/O routines.

Oldbitcollector (Jeff)

Because this material is based at introductory levels, perhaps it would be worth mentioning BST's ability to remove unused methods upon compile?

OBC