= Cues = cue: a signal for action cue: a thing said or done that serves as a signal to an actor or other performer to enter or to begin their speech or performance. The '''cue''' keyword is used on some selected methods to indicate to the compiler that these methods are special, implement a 'special' behaviour or concept and will be treated specially to the system. Cues supported include (or will include): * Initializer - cue init * Destructor (destruction cleanup/Finalizer) - cue finalize * Calculate an objects !HashCode - cue hash as int * Determine comparison operation - cue compare(other) as int * Determine object equality - cue equals(other) as int * Implement enumeration/iteration capability - cue enumerate as T* * Others may be added as needed == Links == See [http://cobra-language.com/forums/viewtopic.php?f=4&t=213 Discussion Posting "Cue"] == Grammar == # as for method definition but 'cue' replaces 'def' {{{ cue [as ] [is ] [has ] [] cue () [as ] [is ] [has ] [] }}} == Discussion == Language systems generally have special hooks at the object level for various purposes such as comparisons, hash codes, enumeration, object construction, initialization and destruction Different languages use differing conventions and names for much the same ideas. The original approach used the C#, VB, .Net naming except that constructors are done through "def init" which had the unfortunate consequence of conflicting with some third party libraries leading to some hacks in the compiler. Purportedly that approach also could not be extended to other backends (such as JVM) as they dont use the same exact method names as .NET. The solution adopted was to introduce a new keyword '''cue''' used (instead of '''def''') on methods that have or may have a special use or meaning and will be translated to the correct voodoo for whatever platform you're on (.NET, JVM, etc.) Cues have some special rules about them, both in general and specific to particular cues: * Cue declarations are exempt from needing "is override" on them. * Most cues cannot be directly invoked external to the cue. Normally however there is a canonical way in cobra to invoke the 'cued' capability or it is invoked invisibly for you in the correct circumstances (hashcode)[[br]] For example [[br]] "a = !ClassName(args)" is the canonical way to construct and invoke an initializer [[br]] "a == b" is the canonical way to compare objects for equality, and [[br]] "for a in collection" is the canonical way to enumerate through the elements of a collection. * One exception to "do not invoke cues directly" is that *within* the declaration of a cue, you can invoke it for purposes of implementation (e.g., base.init, .init, .thing.hash). * A cue alters and adds to your class as needed to implement the cue.[[br]] For example the .enumerate cue when used on .NET will make your class implement IEnumerable and IEnumerable while adding a method for each, for a total of two new methods.[[br]] This provides the capability of using your object in a for loop ("for a in mycollection, ...") and pass it where enumerables are expected ("List(...)"). * Cues cannot necessarily be reflected on by name at run-time as their run-time names may be different by platform (.NET "!GetHashCode" vs. JVM "hashCode"). The intention is to provide implementations of the supported cues in a portable way between platforms and in some cases (like .enumerate) in a more convenient manner. == Initializer == {{{ #!cobra cue init }}} The init cue is used to denote an initializer for a class instance. The initializer code is implicitly invoked on object construction to set the contents of an object instance to an initial state. It doesnt return any value and is not inherited: i.e baseclass initialization must be done with an explicit call to a baseclass or sibling initializer Constructor chaining can be done to another constructor in the same class [[br]] (usually to one with a different number or types of args) [[br]] or to a superclass constructor (using '''base.init''') [[br]] - this call must be the first executable line in the initializer code body. If an init cue is not specified the compiler runtime generates a (default) noArg constructor that does nothing. == Destructor == {{{ #!cobra cue finalize }}} Called implicitly on object destruction (at an indeterminate time).[[br]] Nominally responsible for release of any additional stored resources [[br]] e.g File handles, shared memory descriptors, sockets. But please see the various platform notes (.Net and JVM) on issues with use of [[br]] destructors and finalizers and hints toward use of Disposal Interfaces instead (IDispose). == Hash Code Calculation == {{{ #!cobra cue hash as int }}} Used to calculate a hash code (single unique id) for an object instance. The platform Framework calls this implicitly when needed [[br]] (e.g. hash generation for Dictionary keys). The .hash cue is also an exception to the 'should not call a cue directly' note above.[[br]] It is considered "externally visible" and can be invoked like an ordinary method. === Platform .NET === see Object !GetHashCode == Comparison == {{{ #!cobra cue compare(other) as int }}} Provide a comparison calculation for the ordering of instances of a class, this instance against the provided one. The return value is 0 for equality, negative for .this < other, positive for .this > other === Platform .NET === see IComparable().!CompareTo Method == Object equality == {{{ #!cobra cue equals(other) as int }}} Method used to determine if this instance is equal to another object. [[br]] Nominally called as a result of "a == b" expressions Can be pretty much boilerplate along the following lines {{{ #!cobra cue equals(other [as Object]) as bool if this is other, return true if other inherits return return false }}} === Platform .NET === see Object.equals method == Provide enumeration/iteration capability == {{{ cue enumerate as * }}} This cue provides an implementation of the Enumerable/Iterable pattern for containers such that the class supports the idea of enumeration/iteration.[[br]] i.e so that the cobra construct {{{ for item in }}} works such that {{{item}}} gets each item stored in the object one at a time. It may (probably will) insert additional (boilerplate) code to provide exposure of this capability in the framework approved manner (Enumerator/Iterator) === Platform .NET === see IEnumerable and IEnumerable == Examples == {{{ #!cobra class Customer cue init(name as String) base.init _name = name cue finalize pass # release any held resources (file handles, sockets, ...) get name from var as String cue equals(other) as bool if this is other, return true if other inherits Customer return .name == other.name else return false cue hash as int return .name.hash }}} == Notes == Currently only "cue init" is fully supported While you may specify access modifiers and return types in a cue the implementation may modify, augment or ignore these to conform to the platform requirements or restrictions