Linked List Syntax

I'm confused...

To use Lists, most examples use:

abc:TList = CreateList()
ListAddLast abc, [object]
Print CountList(abc)

But there appears to be a more elegant (imho) way of doing this:

abc:TList = New TList
abc.AddLast [object]
Print abc.Count

The TList help file doesn't appear to mention the TList's methods! What gives? Where are these methods documented? How can I find out what methods an object has?

Also, how do I erase all items in an instance of a TList object in one go? Do I simply "Release abc" (in the example above)?

[Edit]In answer to the above final question, there appears to be a .Clear method on the TList object. But where are these documented?[/Edit]

Thanks

I don't think they are. The global API seems to be documented but the member functions aren't. I assume that's going to change at some point...

According to Marks worklog it sounds like he considers the documentation as-is to be pretty much final.

I seriously hope that's not true. The documentation is barely scratching the under belly of "adequate" at the moment.

I have to agree WarrenM. Whilst the documentation is far, far better than the (incomplete) BlitzBlus documenation, it's more of an overview at the moment IMHO. There's simply not enough detail!

Warren - I agree with you totally.

It's my biggest (only really) gripe at the moment. I've been a big fan of Blitz since the first PC version came along. Though I gave up my day job, I was a software engineer for 12 years and its fair to say I consider myself a pretty competant programmer.

As it stands, I don't see how the less experienced guys will have much hope of figuring thing out. The supplied docs barely touch on some topics,if at all. I've had to rely on trawling through the module source several times already which really isnt an acceptable option.

Less experienced programmers won't touch OO as well so the help actually should do a good job and module creation etc is no non-experienced job as well.

I myself am happy that I have protean with its module viewer, but I am creating a treepad based object help but that will take quite some time ...


to come back to topic

the clear is documented as clearlist( list:TList )

It's not even OO that's the problem. It's everything. Most commands come with a 1 line description and, maybe, a short source code sample that shows the most basic functionality of that command. That's hardly enough to serve as documentation for a programming language.

you can look for yourself in the mods directory. Cool thing about BMAX is that it is written in BMAX.

' LIST METHODS
strict
global n$ 
global list$
global mylist:Tlist
Global this_func = 1
Global link_count
Global this_link:Tlink
Global total_funcs = 5
global listfunction$
Local timer
Const WAIT_TIME = 25


Global GH = 640 ; Global GW = 480 ; Global GD = 0
Graphics( GH,GH,GD )

GLobal a$[] = ["one","two","three","four"]
mylist:Tlist = ListFromArray(a$)

For n$ = EachIn mylist
	list$ = list$ + n$ + " "
Next

listfunction$ = "ListFromArray"
Repeat
cls
	timer:-1
	If timer < 0 Then timer = 0
	
	
	
	If Mousedown(1) And timer = 0
	 	changefunction()
		timer = WAIT_TIME
	endif
	
	SetScale 1,1
	SetColor 255,255,255
	DrawText "Click Mouse",MouseX(),MouseY()-48
	SetColor 255,255,255
	DrawText this_func,MouseX(),MouseY()-32
	SetColor 255,255,0
	DrawText listfunction$,MouseX(),MouseY()-16
	SetScale 1.5,1.5
	SetColor 255,0,0
	DrawText list$,MouseX(),MouseY()

flip
Until KeyHit(KEY_ESCAPE)

Function changefunction()
	
	
	this_func:+1
	If this_func > total_funcs Then this_func = 1
	
	Select this_func
		Case 1
			mylist:Tlist = ListFromArray(a$)
			listfunction$ = "Mylst.ListFromArray(Array)"

		Case 2
			
			this_link:Tlink = ListFindLink(mylist,"three")
			mylist.insertbeforelink("2-1/2",this_link)
			listfunction$ = "Mylist.InsertBeforeLink(object,link--'three')"
		Case 3
			this_link:Tlink = ListFindLink(mylist,"three")
			mylist.insertafterlink("3-1/2",this_link)
			listfunction$ = "Mylist.InsertBeforeLink(object,link--'three')"

		Case 4
			mylist:Tlist = ListFromArray(a$)
			listfunction$ = "Mylist.ListFromArray(Array)"

			mylist.remove("three")
			listfunction$ = "remove('three')"

		Case 5
			mylist:Tlist = ListFromArray(a$)
			link_count = mylist.count()
			listfunction$ = "Mylist.count() = "+link_count

			
			

	End Select
	
	list$ = ""
	For n$ = EachIn mylist
			list$ = list$ + n$ + " "
	Next


End Function

as far as Documentation, Mr Sibly has often admitted that he *Strongly Dislikes* doing the docs. As a result it appears that he implemented the BBDOCS system to make it simpler to do on the fly documentation.

BMAX docs are 10X better than Blitz3D docs were at launch.

I think Skidracer is working on alot of the docs at the moment as well, so while we probably won't get "war and peace", we'll likely have pretty good docs to start out with (remember folks, this is beta!)

source <> documentation

source > documentation (in many cases)

Classic example, this is the complete documentation of the collision stuff:

CollideImage:Object[](image:TImage,x,y,frame,collidemask%,writemask%,id:Object=Null)   

Pixel accurate collision testing between transformed Images.

The collidemask specifies any layers to test for collision with. The writemask specifies which if any collision layers the image is added to in it's currently transformed state. The id specifies an object to be returned to future CollideImage calls when collisions occur.

Hardly what I'd call comprehesive documentation...

Yes it's true, you can learn a lot from good example source code. But in this case none of the supplied examples are even commented at all, and users are having to rely on trawling through the source of the BlitzMax modules themselves.

I do agree. BlitzMAX needs much better DOCS!

Really no point cranking out huge docs on a beta, though. Things are subject to change.

I'd be willing to forego better docs to get my hands on the 3D module. :)

Mark's to do list:
1. pub
2. do docs
3. finish 3D module
4. pub

This is only true if you don't value your time.

Bradford6, are you really suggesting the doc doesn't need improving because the source is delivered?
I doubt the 'novice' programmer and those who want to concentrate on game creation will be happy to trawl through the products source code. The alternative is Bmax is moving it's target audience.
Even the samples are poorly commented.
I realise it's a beta and that blitz documentation has never been a strong point. However, the trend appears to be to cater for those migrating from existing Blitz levels.

OK,OK, I think the docs need to be better, but I think the opportunity cost for creating them right now is to high (i.e Mark could be coding the 3D module!)

drudging through source code is not fun and it IS time consuming but... take a look at the following:

Function CollideQuad:Object[](pquad:TQuad,collidemask%,writemask%,id:Object=Null) 
	Local	result:Object[]
	Local	p:TQuad,q:TQuad
	Local	i,j,count

	p=pquad				'CreateImageQuad(image,frame,x,y)
' check for collisions
	For i=0 To 31
		If collidemask & (1 Shl i)
			q=quadlayer[i]
			While q
				If QuadsCollide(p,q)
					If count=Len(result) result=result[..((count+4)*1.2)]
					result[count]=q.id
					count:+1
				EndIf				
				q=q.link
			Wend		
		EndIf
	Next
' write to layers	
	For i=0 To 31
		If writemask & (1 Shl i)
			If freequads
				q=freequads
				freequads=q.link
			Else
				q=New TQuad
			EndIf
			q.id=p.id;	'TODO:optimize with memcpy?
			q.mask=p.mask;
			q.frame=p.frame
			MemCopy q.xyuv,p.xyuv,64
			q.minx=p.minx;q.miny=p.miny;q.maxx=p.maxx;q.maxy=p.maxy;
			q.link=quadlayer[i]
			quadlayer[i]=q
		EndIf
	Next
' return result
	Return result[..count]
End Function

not only does it make the function clearer, it also gives us more information about the status of the function
'TODO:optimize with memcpy?
not to mention that it is written rather well.

(once again, in case I failed to mention it, I do agree that BMAX needs better docs)

I don't think mark should do them though... He should only clarify to whomever DOES do them, points that arise or are unclear to the documenter.

Who wants to step forward to do it? :)

tonyg,
I am simply suggesting that the Opportunity cost is high for creation of the DOCS right now.

as you'll recall, Opportunity cost is the hidden cost of any decision. basically when you choose to do something, you are choosing NOT to do several other valuable things.

in this case I think that the decision to code BlitzMAX, fix bugs and release 1.0 on Win32 and Linux is a more valuable use of time than improving the docs.

Hi Bill,
I do agree.
However, I think it's simply that we have a different view on the importance of documentation.
In fact, IMO, doc should be created and updated in parallel to the product.
BlitzMax is being marketed as 'easy to use'. If, on release, the target audience do not find it easy to use (for whatever reason but, perhaps, due to poor docs) it will get poor feedback.

These "beta" documents are the same as those that shipped with the full MAC release.

Bradford6 wrote:


The beta status of the Win32 version has nothing to do with the docs, they are the same for the full release on OSX, and according to Mark..

Marks Worklog wrote:

tonyg:

Well I'm hardly a novice and I'm certain not happy to do that either..

And just because I feel the need to be anal, it's "all intents and purposes".

Perhaps, though I doubt all Mac users would share the sentiment. However, you'll recall that you initially included the 3d engine in the list of things that were more time-valuable than finishing the documentation. I'd argue that waiting until the 3d engine is finished before finishing the docs for a product people have already paid for could have quite a large "hidden" cost in people going elsewhere for a properly documented language and not even still being here when BRL want to sell the 3d engine.

I'm sure it's fun to dig around in the source, figuring things out by yourself, and there was a time when I would have been doing just that, but as Warren points out, there's a rather large "opportunity cost" of our own for those of us who are using Blitz as a full or part time "job" to effectively document the language ourselves.

So far, I'd say about 25% of what I've learned of BlitzMax has come from the docs and the other 75% has been from eager forum members and my own investigations. It really ought to be the other way around.

Really?

I don't think I can even once claim to have used a programming language that was so well documented that 75% of all the information you would ever need could be found in it's documentation.

For as long as I've been programming (20+ years), personal improvement has always been a case of sharing your experiences with your friends and co-workers, and listening to their experiences. Reading books account for roughly 15% of what you can learn about programming. The other 85% you have to learn by actually programming.

It's less about learning and more about finding the information I need when I hit the "help" button. Right now, 90% of the time, it doesn't pan out. That ratio needs improving.

I agree. Really.

Agreed - perhaps some of the people closely involved with BlitzMax could add to the bare bones descriptions.

Also, moving from Blitz to BlitzMax is tricky enough without changing methodologies as well (OOP). Some straight conversions of examples could be useful - as OOP is optional.

And yes I still don't know what the best way to do types in BlitzMax is (one of the most important aspects of Blitz I think).

I DO AGREE that some of the docs need improving (e.g: collisions as someone mentioned), but I think it's a bit harsh to go trawling through modules and expect the internals (like list.addlast) to be documented. Don't get me wrong, it's nice stuff to know, but it's not a neccessity, and i think it would just confuse the issue for people with less experience.

We're only trawling through the internals because the documentation isn't giving us answers.

I'm sure, but I didn't say all the information I would ever need, did I? I said all the information I've needed in the first week of learning. In other words, the most basic new features.




No argument, but in the first week of playing with it, and to be honest, it's been no more than an hour here and there, so a week makes it sound a lot more impressive than it really is, I've got nowhere near to touching the 85% you learn by programming. I'm just trying to pick up the very basic stuff, and so far I'm doing most of that using your samples, the module source and these forums.




Well none of the new stuff is a necessity, I suppose, but yes, I do think that the important internals ( List.AddLast is a good example ) need some documentation. Heck, at the very least, a list of the internals, sorted into fields, methods and functions. Even if there was no explanation, it would be some help to be able to double F1 on TList and see a list of the internals. I dread to think what people with less experience will make of the docs.

Before Blitz3D (before I had ever heard of it and used it) I programmed in VB 6.0 and found everything I currently know, inside the docs (MSDN).

I don't know any website where I have posted a single questions about VB.

It's not that I can program everything, but I can find my way around the docs (MSDN).
Mt first intro to VB was nothing more than my friend explaining how to draw a button, which routine was executed when it was clicked upon, how to set the Caption (in code) and that was basically it.

Now I'm even using custom types, classes and separate OCX-components (NTPort) in VB, without any help from anyone else.

I evenly created an almost complete (haven't finished it yet) interface program for controlling selfmade hardware, which is connected to the printerport.
Theoretically I can switch on/off about 4 billion lights individually.
Practically it wouldn't be possible, because it would require a very big PCB (printer circuit board).
But the software has the ability to do it.
It's slow (serial data transfer on the parallel port), but very stable.

And all this without help from anyone.

But that's not the point here.



But the docs for BMax don't really explain everything clearly (and especially for a newbie to programming).
BMax is a BASIC language and can be used by complete programming newbies, but I don't think they can find their way to start off quickly with these docs.

I know that BMax is quite new, and that the docs are not complete yet, but it cannot be that the docs are finished.
In my opinion, if a programming language has not sufficient documentation, and a beginner has to walk through tons of sourcecode to understand the functionality of a command (or even to find if a certain command or functionality exists), they will be scared off and find another language that has enough docs to get them started programming the game/app they want to create.

No offence Mark, but some commands definately need better docs, which explain not only the basic functionality, but also has samples which also explain more advanced functionality.

In the B3D docs, there's almost an entire A4-sized page, describing WHAT a user-defined type is and how to use it, with a practical example.

In the BMac docs, this stated what a user-defined type is:


And what follows, is the syntax, what stuff can be placed inside a type and what those things are that you can place there.

I doubt that will do for a newbie.

So which is it then? Did you learn everything you know about VB from MSDN or not?

Who is saying they're finished?

Anyway, I agree, the docs need to document the classes -_- I made a OOPified bank class that calls all the bank functions, only to find out the TBank class is already oopified and the standard functions actually call the methods. Now I'm working on adding stuff like PokeString, PokeArray, PokeBit, PokeData...

No it doesn't. Isn't the English language wonderful?

Of the 17 or so definitions of finished, it's amazing that people automatically assume the worst case scenario. Or the one that fits their perception best.

It seems than when Mark says the documentation is finished, everyone immediately assumes despite the fact that one of the steps of syncronizing modules is updating documentation that the documentation is in it's ultimate (ultimate here is used in it's original meaning of definitively last, not the buzzword that translates as cool) form.

People must not have done a whole lot of software development, which is interesting considering that this forum is exclusive to software developers.

If anyone is interested in a rational interprentation, I interpreted the "finished" statement in his worklog as meaning "All commands are now covered".

All things considered, I think my interprentation is closest to the truth.

WOW good nickname Flameduck!

Perhaps your interpretation is what mark means, but it is not what he said. I have seen the documentation stuff, and seen it used inside the modules.

What the...

you've left me speachless... nearly ;)

http://www.google.com/search?hl=en&lr=&client=firefox-a&rls=org.mozilla:en-US:official&oi=defmore&q=define:finished

I think goods applies to BlitzMax :P.

Sure. he's ended the process of writing

applies

completly different

LOL. I suppose he did bring the docs to ruin ;P

Applies

Lol. google define fart

Metal allergies? whoah!

In other words, you are completly utterly wrong in every way, except:

True, but this could just be for minor changes like fixes of false docs or spelling. Or for the completly new modules where it takes the source, parses out the docs and creates html files.

BTW:

And you must not have done much speaking in english which is interesting, considering this is an english forum.

And the only reason you are attempting to use such a ridiculous excuse is that you are attempting to mask your mistake:Mark has, infact, using the exact word "finished":He even admits to not being a good doc-er. And, supporting my interpretation says he is scanning for typos.

Really??? I'll get my coat then.

I'm sure someone, somewhere could write an interesting thesis all about your logic there Flameduck.. :)

How do you figure that, seeing as you're the one doing the flaming.

Only in my dreams.

http://dictionary.reference.com/search?q=Finished

Most certainly applies here.

Also applies here.

Again applies well here.

Let me introduce you to a kind of development that was conceived about 20 years ago, and has been used extensively since then. It's called itterative development, and involves completeing a product one small bit at a time in a fixed timeboxed environment, and then going back and reitterating over what you've done already to improve on it.

Traditionally these are called phases or steps and one such phase is considered finished once time runs out, regardless of the actual state of your software and documentation.

Thus when something has reached it's final or desired state, that doesn't mean it's in it ultimate form, just that it's in the state that it's supposed to at the end of the phase (traditionally called milestones).

Just because you say it, doesn't make it so.

Yes. It could be for a lot of things, and your wild guesses are not fact, so please stop presenting them as such.

How do you figure that? In the future I would ask that you refrain from personal attacks, and instead comply to the rules of the forum.

I profusely appologise for leaving out the word "definitively". I realise that since it's appearently a requirement to speak fluent English in order to post on this forum, such a transgression cannot go unpunished.

Yes. But he used it in a different context then me. You know this ofcourse, since even I understand this, and my English is obviously inferior to yours, so I wonder why you, with your clearly superior English even bother to argue the case?

Which is probably the motivation for including document updates as part of syncmods.

Except your position was that the updates where only for typos, and that the docs where in it's definitive last form. So it doesn't support your position at all. Exactly what is your position anyway?

To determine this please pick one of the following:
1) It is my position that the docs will never be improved or updated, they are definitively finished, and will not be updated ever, even for spellling mistakes as Mark is already finished with this.
2) It is my position that the docs will only be updated for spelling mistakes and new modules, but that existing documentation will remain the same.
3) It is my position that the docs, and all aspects of the documentation will be updated regularilly, based on feedback, like they where for all previous Blitz Research products.

Why? Your English seems perfectly fine.

Really??? I'll get my coat then.

Now we're arguing the definition of the word "finished".

You go, girl!

Lock this one... it's turned into a bad episode of Seinfeld...

Well we *were* having a perfectly sensible conversation on the subject..

Thanks, Mikkel!

I have very limited programming experience. I fiddled on a very basic level with C64 BASIC, qBASIC, and at college I made some very simple database programs in Turbo Pascal.

Until I discovered Blitz3D, my skills were limited to loops, simple conditional statements and not much else...
Blitz3D gave me the ability to code simple games, graphical demos and some weird mathematical stuff like springs using Hookes Law, simple 2D physics, per-pixel plasma effects, particle systems.

I would say that this knowledge came perhaps 50% from the docs and tutorials supplied with Blitz3D, the remainder provided by the community.

The docs supplied gave me the necessary grounding to justify the investment of time (and money) in purchasing and learning Blitz3D.
Without the support provided by the docs in those first few weeks, I would not have purchased the product.

As a 'newbie' I consider the docs supplied with BlitzMax inadequate, at best. Without the experience of Blitz3D behind me, I would be unwilling to purchase BlitzMax. Even with that experience, I still need to ask the community for help with things that I was perfectly comfortable with in B3D.

I just *really* hope that someone from BRL is reading this and taking it on board...

FlameDuck, are you familiar with the fictional character Humpty Dumpty at all?

Lol. flameduck is the most irrational person i have ever heard. He is arguing by stating facts that are actually AGAINST his argument. The first three definitions do agree. They agree with my point of view. Not yours.

Yes, it does agree with my argument. Your just adding flowers to your argument's grave.

[qupte]Yes. It could be for a lot of things, and your wild guesses are not fact, so please stop presenting them as such.[/quote]Look who's talking guesser boy:

AAAHAAHHAAHAHAHAH I used your insult against yourself. hell. you should recognise it:
I've programmed for 6 years.

In fact you edited it out of your post. Because you know you are wrong and wish to frame me as some sort of "bad guy". It is clear that this existed at one time because tonyg also quoted a piece of this insult.

You have done stuff like this before, Flameduck. It's no secret that you like argueing about totally pointless topics, and meanwhile making yourself sound completly foolish yet very zealous in defending very odd and clearly wrong ideas.

I'd probably pick 2, however, I would like to help blitz research out with the documentation, making the end result a 3. BTW, atleast while I was there the docs were pretty static. Sure everyonce in a while a pack that added a few commands or introduced a new organization system, but no wide re-doing of all the documentation, as seems to be needed.

I'd go for 3.

There are some glaring holes. The CollideImage command I accept is very poor and it's my fault.

BRL.mod Globals, Consts, Types and Methods obviously need to be included in the documentation.

The docs as they stand were a massive undertaking but in order to pull something together for initial release with the available resources the concise defintitions and example code that accurately demonstrates the behavior of each command was an OK compromise.

I agree, skid.

The documentation is good.

We can use 90% of BlitzMAX's capabilities with the current docs. Sure, they can be better but for a 1.0 (MAC) and beta (Win/Linux), The docs are fine.

If some of the people quit complaining about the docs and actually played around with this fun new language, they might be much better off.

experimentation and self discovery are the BEST (and most fun) way to learn a new language.

Most beginners have something in common, they want to create a fully operational X (x = Zelda, Half-Life 2, Doom 3, Halo 2, The Sims, Etc) in 3 days.

Sometimes reality hits them quickly, other times it takes several months. a Single, amateur programer simply cannot create a Triple A game (that took a team of 100 people 3 years.)

I look forward to better docs, bugfixes and overall improvements and add-ons (Maplet 2, anyone?) but There is so much to learn right now that worrying about the relatively few holes in the current docs seems like a monumental waste of time.

Did/does releasing the beta help with the docs?
On one hand it helps highlight shortfalls. On the other, so many people are trying so many things with the beta it could be an avalanche of feedback.
From the people I see posting there's quite a few talented coders who can work out the commands or workaround anything that seems to be missing. I AM worried about those people who will choose BlitzMax without programming experience (either blitz related or not).
Either they won't get past playing with any demo release or they'll buy it and be unhappy.
On yet another hand (that's 3 hands I think ;) maybe the sales of Bmx to experienced programmers/blitzers is enough.... maybe?

Really? Check out the help for LoadImageFont. "Well, I know I've got all the info -I- need! Rock on!"

What if you didn't buy the product to 'play around' but to make games/applications as easily as possible?
I don't program for a living and the spare time I DO get to program is precious. I don't really want to be 'experimenting' and wasting time on 'self discovery'(although I agree it can be fun). I want the product to say "These are the commands available to you and this is how you use them".
The blurb on the Blitzmax product page says...
"Easy to use 2D command set
BlitzMax includes the Max2D module which contains a set of very easy to use 2D commands. Max2D is based on OpenGL, allowing for advanced effects such as realtime blending, rotation and scaling".
... and I agree. The product looks fantastic and builds on B2D (which I also believe is fantastic).
BUT... how does a novice programmer pick-up this package and get programming without each command being documented
properly. *IF* there are plans to update the doc for Win32 release then OK. However if, as some believe, the existing doc is to be cleaned, then I don't think it will be adequate.
The way all the Blitzses have been packaged is very much like you suggest... "We'll give you the basics but you'll have to work the rest out for yourself or rely on the communities to do it for you".

Thats good to hear, skid. Mark does, however say diffferently in is worklog.