66 replies to this topic

[plastikglass]

Nice example corrupt but replace "CD" by "Album", noobs (new generation) will don't know what is a compact disk , like floppy disk icon for save a file, or an abacus for a calculator...
Abstract concept for variable and object is a "box" with things inside (method, interface, properties, data,... ) as "socket" for some programs... we need to do a general documentation about general programmation with ahk example, hard work...

I know what a CD is...

[jethrow]

I did a quick rough draft for possible Array Documentation. I based it on the Variable Documentation, and I was thinking it could go either before or after the Expressions Documentation.

I used the though process of starting with regular arrays (Lexikos used simple arrays), and then showing associative arrays. This creates some duplicate documentation that could probably be refined - perhaps have an array section with subcategories of simple arrays & associative arrays. Also, I may have been too wordy at points. I am open to modifications.

Additionally, the underlined items would need links.

[sinkfaze]

Nice basic roadmap. This part is worthy of greater emphasis:

*Note: Arrays only use expression syntax. For example, the equal sign operator(=) will not work.

I think it's missing some explanation in using Object() itself; even though it's obviously not preferred to the JSON syntax, it's worthwhile to at least explain its existence and usage to demonstrate why the JSON notation is preferred.

Also, I think the MaxIndex()/MinIndex() portion is worthy of a common source of confusion note since MaxIndex() will not always reflect the maximum number of items in an array, and within an associative array MaxIndex()/MinIndex() doesn't exist at all.

Additionally, in the Arrays vs Associative Arrays I think you should show how the same array (in effect) is built using both notations.

MyArray := ["Item1","Item2","Item3"]
MyAssociativeArray := {1:"Item1", 2:"Item2", 3:"Item3"}

Lastly, I think the for-loop should either be in a separate section and deal with both types of arrays there or be presented in both sections as a means of enumerating an array.

Otherwise, you navigated the jungle much better than most of us could.

Just my $0.02.

[fragman]

Is it desirable to introduce this split between arrays and objects? After all, arrays are just objects with integer keys.

[jethrow]

I made some updates to the possible Array Documentation.

Is it desirable to introduce this split between arrays and objects?

I believe so. I would say arrays are a regular/newbie concept, whereas objects (particularly custom objects) are an advanced topic. I may have just made some programmers cringe, but I propose: picture an object ... ... ... I'd bet 10 different people - particularly non-programmers - would have 10 different pictures come to mind. An object is an abstract concept - the base for building other things. In contrast, arrays are pretty-strait forward. Plus, the AHK Documentation already has Arrays.

I think it's missing some explanation in using Object() itself; even though it's obviously not preferred to the JSON syntax ...

I would partially propose the previous explanation, but you are referring to the Array & Object functions vs using brackets. IMO, since we are just introducing arrays at this point, lets stick with the preferred syntax. The user can always find the Array/Object function later.

... the MaxIndex()/MinIndex() portion ...

I wanted to present a regular array as being a 1-based, continous, numerical indeces object. Once the user can grasp that, I believe they can start modifying arrays however they want. At that point, Min/MaxIndex() hopefully would logically make sense - especially considering that they are named Min/MaxIndex() rather than just using count or length.

Additionally, in the Arrays vs Associative Arrays I think you should show how the same array (in effect) is built using both notations ... ... ... Lastly, I think the for-loop should ... be presented in both sections as a means of enumerating an array.

Done

[fragman]

Is it desirable to introduce this split between arrays and objects?

I believe so. I would say arrays are a regular/newbie concept, whereas objects (particularly custom objects) are an advanced topic. I may have just made some programmers cringe, but I propose: picture an object ... ... ... I'd bet 10 different people - particularly non-programmers - would have 10 different pictures come to mind. An object is an abstract concept - the base for building other things. In contrast, arrays are pretty-strait forward. Plus, the AHK Documentation already has Arrays.

I'm fairly sure I can't think of this many, but I consider myself a programmer, so point taken. It really goes over my head how the basic concept of an object can be difficult if one already knows how variables work. In the end it's just a container for more variables at its most basic level. This is a good analogon to directories in a file system which hopefully every beginning AHK-scripter understands.

You're right on the last point, users are probably more familiar with the concept of arrays due to the pseudo-arrays. This only accounts for old users though and pseudo-syntax can also be used for pseudo-objects.

By the way, I've always seen it as a problem that the integrated array functions were designed to support non-contiguous arrays. The use cases for them are very little in comparison to contiguous arrays and the lack of a function that returns the real count of items in an array instead of the one with the highest index (and "" otherwise) is a common source for bugs. I have resorted to overwriting the MaxIndex() function in the array class that I use to avoid this.

[Lexikos]

Array scope and names: Arrays have the same scope and use the same naming conventions as Variables.

I think that if a user starts out believing that MyArray is an array, it will be difficult to comprehend why after doing MyArray2 := MyArray or passing it to a non-ByRef parameter, modifying one array affects "the other array". MyArray isn't an array; it contains one. Arrays don't have names or scoping rules. You don't declare them, but create and assign them to a variable.

MyArray := [a,b,c] is equivalent to assigning a list to a variable. Surely that isn't difficult to understand?

I would say arrays are a regular/newbie concept, whereas objects (particularly custom objects) are an advanced topic.

I agree, and that is why I listed them separately on the front page.

[jethrow]

I made some updates to the possible Array Documentation, including a short section on Multi-Dimensional arrays.

I'm fairly sure I can't think of this many ...

I mean 10 different people might each think of something different. One person might think of a car, another a book, and yet another an instance of a class. The confusion lies in that fact that these are all accurate images of an object.

MyArray isn't an array; it contains one. Arrays don't have names or scoping rules. You don't declare them, but create and assign them to a variable.

I thought about this when I was initially writing the documentation, but I wanted to keep the concept simple. I suppose accuracy is important as well. I hopefully rephrased it to be simple, but accurate.


EDIT: I suppose the image of MyTable isn't technically accurate since MyTable[1,2] & MyTable[2,1] don't exist ...

[sinkfaze]

Alternatively, since the array starts with index 1 and doesn’t have any missing indices...

Since you went to trouble of adding this line to the proposed documentation, might it now be worthwhile to add that common source of confusion snippet about what MinIndex()/MaxIndex() means?

[sinkfaze]

This question in Support prompted me to give this a bump.

Is it worth including something in the proposed object documentation re-write about what a statement like test_object["a", "b", "c1"] := "content2" actually means?

As the OP in that thread had yet to discover, test_object["a", "b", "c1"] := "content2" does not change what is assigned to 'b' (which in his case caused a failure). So what the above code is really saying is that if 'b' does not exist or if 'b' exists and is an object then it will create key 'c1' with value "content2" within object 'b'.

[fragman]

Sure, those possible issues should be addressed. I refrain from using such assignments without explicit initialization to avoid any possible errors as a precaution anyway.

[guest3456]

Since AutoHotkey Basic is ANSI-only, simply using the ANSI version of AutoHotkey_L is sufficient to avoid any Unicode-related compatibility issues.

this line should be given more attention imo, even bold the whole thing, but even that is not enough since its stuck near the bottom. perhaps copy it at the top of the page too.

[CodeEater]

+1

[Lexikos]

guest3456, thanks for the suggestion. I've changed the introduction on that page and made a couple of other minor changes. Please take a look.

[guest3456]

i like the note in green, much better. i think the wording can be changed to have everything be a little clearer, cause most beginners probably don't know the diff between unicode/ansi.

your text:

Although many scripts written for AutoHotkey Basic do not require changes to run on AutoHotkey_L, some may function incorrectly due to necessary differences between the two versions. As the most problematic differences only affect advanced functionality like DllCall, most users do not need to be concerned.

Note: Some of the most common problems are caused by changes required to support Unicode text, and can be avoided by simply using the ANSI version of AutoHotkey_L.

my suggestions:

Most scripts written for AutoHotkey Basic do not require changes to run on AutoHotkey_L. Some may function incorrectly due to the necessary differences between the two versions, and those issues are described on this page. As the most problematic differences only affect advanced functionality like DllCall, the majority of users do not need to be concerned. In any case, help isn't far away in the forums.

Note: Beginners should simply choose the ANSI version when downloading AutoHotkey_L, to avoid most of the common compatibility issues. See Unicode vs ANSI below for an advanced explanation.

then in the Unicode vs ANSI section, first have a paragraph to mention how Unicode supports many more characters and foreign languages, and how its recommended to have new scripts use Unicode, but that the ANSI recommendation is to ensure backwards compat. then you can have your technical details that are already there

maybe this should probably be the default option? suppose AHK_L actually becomes standard and Basic is deprecated. if AHK is to maintain its heritage for targetting non-programmers (which it seems poly wants), i think most beginners have no idea about unicode/ansi, and those who specifically do, will know better to download the correct version. for the newbies, just make the decision for them in order to maintain as much backward compatibiltiy as possible

just my opinion, coming from a hobby coder who had to learn about unicode/ansi differences a year or two ago when trying to understand this AHK_L stuff