Discoverable documentation

[cathalgarvey]

Without being able to put my finger on it, I also found the documentation on Cobra a bit fragmented and confusing. In some areas, this is sort of an assumption that you are already familiar with C# syntax(1), in others it's the absence of certain type references(2), and in others it's assuming that I know Cobra primitives like usage of the print statement (3)(4)

So I'm not necessarily sold on "all on one page", as I think that'd be cluttered. But a reference document that separates but links to a useful builtin reference for C# (where still required) and Cobra primitives, a relevant library reference for C# (even a link to offsite Mono/.NET documentation) and Cobra stdlib, and perhaps a description of what you can and can't do in Cobra that you might like to do; you can pass references to methods in Cobra, but can you assign a method reference to a class variable on the fly? Can you dynamically generate classes, is there such a thing as a "class factory"? How about nested classes?

(1) List syntax (List<of whatever>), references to C# types like IDictionary (but I learned by accident that there's also "Dictionary", so what's the difference between that an IDictionary? Cobra assumes I know this already..), etc.
(2) like non-string byte arrays; in Python, these are "bytes", in Cobra apparently it's "uint8[](length)"; is there a dynamic or literal way to do bytes, like the b'' syntax in Python?
(3) Which I found documented on the wiki, but not in the samples beyond the total basic and obvious literal usage.
(4) Is there a rationale for why print is a literal? I find that major difference between Py2 and Py3 to be a huge selling point for Py3: I can inject a reference to a conditional shim function in Py3 for a "debug" mode and then litter my code with normal print statements, later deactivating them with a single line.. or passing "print" around as an argument, because it's a function. Why did Cobra go with print-as-statement when the Python guys decided that was a big mistake, and most people seemed to agree?

[hopscc]

Fair enough critique.

1) The assumption isnt that you are familar with C# syntax but that you are familiar or can research use of the .Net library (which C# uses)
and that cobra also uses ( for the CLR backend).

Its noted that Cobra doesnt implement its own library (libraries) but uses the platform one ( .Net ).

Since these libraries are already way more well documented than anyone doing any cobra doc will ever get to it seems retrograde to
redoc these (yet again, badly).

2) The Typing system falls out from .Net and naming decisions made ( or not made/aliased) in Cobra
.Net uses uint8 for unsigned 8 bit values ( called bytes elsewhere - sbytes in the C# compiler ) so therefore so does cobra.... it may be nice to have an alias for this ( I hacked one in for my own use but you'd need to convince Chuck thats its a worthwhile augmentation.
Use of 'byte' in cobra will currently tell you that thats unknown and to use uint8 instead..

I dont think theres a tagged literal form for bytes/uint8s - perhaps there should be - b'ymmv\x08\x07\x00'
Support for byte twiddling isnt perhaps as comprehensive as other languages OTOH perhaps it doesnt need to be...


Note that beyond the doc and sample code another source of 'seeing whats possible' is the test suite code examples

Assign method ref to class variables - yes (normal typing rules)
Dynamically generate classes - via reflection ( i.e through .Net).
The compiler is a available as a library so another option would be to
generate source code and invoke the compiler lib on it then load and use the resulting assembly - some partial examples in the test suite
Class factory is a concept - you can implement that in your code, the compiler doesnt do anything special to aid or disable this.
Nested classes - yes cobra supports those - just declare a class in an existing one - This hasnt been used very much so there may well be issues not hit yet.

Unfortunately theres rather a large universe of what anyone might like to do that Cobra may or may not do for you - the doc barely and incompletely covers what cobra specifically does/supports

3) re print - it seems that 99% of the use of print is the basic and obvious literal use..
The wiki doc is supposed to at least mention the other possibilities

4) I cant comment to the statement vs expression choice - Chuck can probably shed some light on this

note that you can always turn a statement into a expression ( function call ) by wrapping it if thats what you want..

class PrintAsFn
    
    sig Pfn(a as vari Object) 

    def printfn(args as vari Object)
        for a in args, print a,'' stop
        print
    
    def main
        xPrint as Pfn = ref .printfn
        #.....
        x = 'foo'
        y = 999
        xPrint(x, y)

[cathalgarvey]

Thanks for the answers! I know I can wrap print, but then you could wrap it in Python too. It's just, from my perspective, an odd decision to go back to statement after one of the "prototype languages" that inspired Cobra deemed it important enough to form part of a backwards-incompatible upgrade. And, in my experience, that change was a damned good one, too.

I guess I was just griping that I agree the documentation currently is too fragmented and sucks somewhat. I did however enjoy Cobra enough to overcome this.

Can I put this post down as my personal vote for a print function and (more importantly) a bytes literal or class-alias?

[hopscc]

I think you'll find that cobra predated python3.

documentation currently is too fragmented and sucks somewhat

Same as all doc.

my personal vote for a print function and (more importantly) a bytes literal or class-alias

Yah sure
Voting is all very well but it generally gets a more immediate/concrete result if its accompanied by one/all of
- rationale/description discussion of why feature desirable/useful
( sometimes done as an enhancement ticket perhaps along with forum discussion)
- Implementation code
- tests
- doc (wiki mods after patch applied)

The mid two are usually done as a patch to the compiler source

[nerdzero]

Hey, do you guys think http://cobra-language.com/trac/cobra/wi ... axHilights and http://cobra-language.com/trac/cobra/wi ... aInOnePage should be combined into a single page?

[hopscc]

Maybe, though I'm still waiting to see if 'allOfCobraInOnePage' develops/completes into the one shot panacea its champion/writer envisaged was the required/missing doc solution...