Add import statement

[C3pa]

As we discussed on Discord, I am now submitting an initial version of the import statement documentation. All suggestions are welcome.

Fixes: #15.
Fixes: #11.

I am not sure if this is considered controversial, but adding a folder with multiple of your pattern files to the search paths using Extras > Settings > Folders will allow the user to correctly import their pattern files to other pattern files. If I understand the request/issue correctly, that's also the point of the issue: WerWolv/ImHex-Patterns#269

Edit: I think it also fixes: WerWolv/ImHex#1641 since ImHex won't crash anymore in that issue, and this PR explains how to properly use standard library headers.

[C3pa]

It looks like the build failing isn't related to this PR.

[paxcut]

It is nice to see somebody giving documentation much needed attention. The way it is written it seems like one should never use include so it begs the question of why does include exist? Legacy is not a good reason because valid code from before import existed is now rendered invalid.

1. The explanation on include guards for import statement and include directive is misleading in that it is easy to conclude that import respects pragma once directives and include doesn't respect pragma once directives. I know it doesn't say that exactly but it suggests it and gives no attempt to deny the conclusion so it may cause confusion when users realize that both work equally well.
2. There should be some explanation as to why there are two ways to incorporate contents of files into patterns.
3. It also may be worth mentioning that includes propagate define directives while imports don't.

Why are there two separate pragma once systems? Is it possible for both to use one system or is it necessary to keep them separate? I don't know, but this is potentially going to confuse people so it is probably worth checking into unifying the two systems if possible.

[C3pa]

Hi paxcut! Thanks for your remarks.

1. The explanation on include guards for import statement and include directive is misleading in that it is easy to conclude that import respects pragma once directives and include doesn't respect pragma once directives. I know it doesn't say that exactly but it suggests it and gives no attempt to deny the conclusion so it may cause confusion when users realize that both work equally well.

That's what was my understanding when I wrote this. I thought #include doesn't respect #pragma once, and that was the reason why #includeing one of the standard headers (I've forgotten which one) started giving compiler errors about duplicate declarations.

Because of that, the #include macro seemed inferior to import in every use case. I was motivated to write this by goodwill, I don't know about all the ins and outs of this system, but I wanted to give some basic pointers to people just starting out with pattern language that I had to dig out in Discord chat history.

3. It also may be worth mentioning that includes propagate define directives while imports don't.

Good tip! I didn't know about this. We can mention this.

So, I don't have a picture where's the place for #include. Do you know something more about it? If you are interested I'd be glad if you applied your suggestions directly to this branch. I left allow edits by maintainers checked so I think you are able to commit to this branch.

2. There should be some explanation as to why there are two ways to incorporate contents of files into patterns.

Why are there two separate pragma once systems? Is it possible for both to use one system or is it necessary to keep them separate? I don't know, but this is potentially going to confuse people so it is probably worth checking into unifying the two systems if possible

I don't know enough to answer these.

[paxcut]

ok, Lets start from the beginning from before import was even first discussed let alone implemented. include was the only way to incorporate code from other files. It was fully functional and every system file that needed content from another one used include. pragma once is a directive designed to work with include to avoid multi-inclusions, just as it is for c/c++.

That exact same system (or its equivalent but that's another story) is still in place today completely intact except the part where every system file includes other system files, now they import them. When import was designed and implemented as a language statement it was decided that instead of creating an import guard that functions at the statement level,import would 'borrow' the directive system but due to the differing locations and times where directives and statements are processed they couldn't share the data of what had been already used and what had not. As a consequence of that design decision and the later move of all system files to import left include crippled in many ways.

So how are the two systems similar and how do they differ? I wrote a little blurb about it in discord.If you have problems getting to read my comment or questions after reading it let me know and will try to answer as much as I can. Thanks for listening!

[C3pa]

Thanks for the link @paxcut! I scrolled to the top of the discussion to get more context. I expanded on all the ins and outs I found out about #include and import. Let me know what you think of the latest revision.

[paxcut]

That is very good. You have a talent for expressing the complex in a simple way. Very impressive. There are some things I am not 100% sure how they really work.I know compilation units don't share directives, but as for variables they may be able to share variables defined in the global scope and in pattern language there are no 'local' variables in the global scope. That may seem confusing but all i'm saying is that every variable that's not part of a function or a user-defined type is a global variable. Even variables defined in the global scope of a namespace are also defined elsewhere and there is no scope resolution operator that applies to variables (only for types).

Some experimentation I did clearly shows that if you include or import a file the defines a global variable and try to define it again results in a duplicated definition error. and that the value the variable had in the included file remains the same.

the sentence

 both `#include` directive and `import` statement keeps its own list of files marked with `#pragma once`.

is grammatically incorrect, it should be

 both `#include` directive and `import` statements keep their own list of files marked with `#pragma once`.