www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - `update` and `require` properties for AA

reply Vasniktel <vasniktel gmail.com> writes:
Hello everyone.
I am wondering about `update` and `require` properties of AAs 
which are mentioned to be present here: 
https://dlang.org/spec/hash-map.html#properties
However, this code doesn't compile:
```
import std.stdio;
void main()
{
     class C{}
	int[C] aa;

	auto a = aa.require("a", new C());
}
```
Notice that this is the very code from the specification.
Compiler says: "Error: no property require for type int[C]".
The same situation with `update` property.
So, I'm wondering is this a bug of some kind or just the spec 
isn't updated.

Thank you.
Jun 26 2018
parent reply Mike Franklin <slavo5150 yahoo.com> writes:
On Tuesday, 26 June 2018 at 07:05:44 UTC, Vasniktel wrote:
 Hello everyone.
 I am wondering about `update` and `require` properties of AAs 
 which are mentioned to be present here: 
 https://dlang.org/spec/hash-map.html#properties
 However, this code doesn't compile:
 ```
 import std.stdio;
 void main()
 {
     class C{}
 	int[C] aa;

 	auto a = aa.require("a", new C());
 }
 ```
 Notice that this is the very code from the specification.
 Compiler says: "Error: no property require for type int[C]".
 The same situation with `update` property.
 So, I'm wondering is this a bug of some kind or just the spec 
 isn't updated.

 Thank you.
I think the documentation gets published prematurely. The new methods for the associative arrays should come in the next release, scheduled for July 1st. https://dlang.org/changelog/pending.html#require_update Mike
Jun 26 2018
next sibling parent Vasniktel <vasniktel gmail.com> writes:
On Tuesday, 26 June 2018 at 07:25:09 UTC, Mike Franklin wrote:
 I think the documentation gets published prematurely.  The new 
 methods for the associative arrays should come in the next 
 release, scheduled for July 1st.  
 https://dlang.org/changelog/pending.html#require_update

 Mike
Wow, thanks a lot. I have forgotten to check future releases :)
Jun 26 2018
prev sibling parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Tue, Jun 26, 2018 at 07:25:09AM +0000, Mike Franklin via Digitalmars-d wrote:
[...]
 I think the documentation gets published prematurely.  The new methods
 for the associative arrays should come in the next release, scheduled
 for July 1st.  https://dlang.org/changelog/pending.html#require_update
[...] Seriously, we need to start implementing versioned docs on dlang.org. T -- If lightning were to ever strike an orchestra, it'd always hit the conductor first.
Jun 26 2018
next sibling parent reply Timoses <timosesu gmail.com> writes:
On Tuesday, 26 June 2018 at 15:51:00 UTC, H. S. Teoh wrote:
 On Tue, Jun 26, 2018 at 07:25:09AM +0000, Mike Franklin via 
 Digitalmars-d wrote: [...]
 I think the documentation gets published prematurely.  The new 
 methods for the associative arrays should come in the next 
 release, scheduled for July 1st.  
 https://dlang.org/changelog/pending.html#require_update
[...] Seriously, we need to start implementing versioned docs on dlang.org. T
Doesn't it already offer it? Here https://dlang.org/spec/hash-map.html in the very top right corner you can diverge from master. However it seems a bit bugged that when selecting something else than master, it suddenly prints master again, and there is no way to get back to master. Looks a bit broken. Wouldn't it be better to reflect the latest published version of the docs there as a default??
Jun 26 2018
next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Tue, Jun 26, 2018 at 04:17:03PM +0000, Timoses via Digitalmars-d wrote:
 On Tuesday, 26 June 2018 at 15:51:00 UTC, H. S. Teoh wrote:
[...]
 Seriously, we need to start implementing versioned docs on dlang.org.
[...]
 Doesn't it already offer it?
 
 Here https://dlang.org/spec/hash-map.html
 in the very top right corner you can diverge from master.
Ah, I must have missed that button!
 However it seems a bit bugged that when selecting something else than
 master, it suddenly prints master again, and there is no way to get
 back to master. Looks a bit broken.
 
 Wouldn't it be better to reflect the latest published version of the
 docs there as a default??
Yeah, the default docs should be the latest published version, not git master. Most visitors to the website wouldn't be running git master, so it's a bit strange (and very confusing!) to use that by default. Phobos docs already have phobos-prerelease/ for git master and phobos/ for the current release; the language spec pages need to do something similar. T -- What are you when you run out of Monet? Baroque.
Jun 26 2018
prev sibling parent Seb <seb wilzba.ch> writes:
On Tuesday, 26 June 2018 at 16:17:03 UTC, Timoses wrote:
 Doesn't it already offer it?

 Here https://dlang.org/spec/hash-map.html
 in the very top right corner you can diverge from master.
 However it seems a bit bugged that when selecting something 
 else than master, it suddenly prints master again, and there is 
 no way to get back to master. Looks a bit broken.
Well, it takes you to the exact snapshot of the page of your selected version: https://github.com/dlang/docarchives.dlang.io That's why if you select anything before 2.079 at the spec pages, it won't even show the version chooser as it was introduced a bit before the 2.079 release (the Phobos documentation has had the button for a bit longer). We can probably fix this by injecting a bit of custom JavaScript in the old snapshots that detects the current version and adds a "correct" version chooser button, but it's not on my priority list and no one else has bothered/cared enough about it either.
Jun 26 2018
prev sibling parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 6/26/18 11:51 AM, H. S. Teoh wrote:
 On Tue, Jun 26, 2018 at 07:25:09AM +0000, Mike Franklin via Digitalmars-d
wrote:
 [...]
 I think the documentation gets published prematurely.  The new methods
 for the associative arrays should come in the next release, scheduled
 for July 1st.  https://dlang.org/changelog/pending.html#require_update
[...] Seriously, we need to start implementing versioned docs on dlang.org.
We do. But stable right now is in beta, so the docs are going to reflect what will soon be released. What we probably should do is have a "released" branch for the docs. Or just answer the odd question every once in a while on the forums :) -Steve
Jun 26 2018
parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 6/26/18 12:48 PM, Steven Schveighoffer wrote:
 On 6/26/18 11:51 AM, H. S. Teoh wrote:
 On Tue, Jun 26, 2018 at 07:25:09AM +0000, Mike Franklin via 
 Digitalmars-d wrote:
 [...]
 I think the documentation gets published prematurely.  The new methods
 for the associative arrays should come in the next release, scheduled
 for July 1st.  https://dlang.org/changelog/pending.html#require_update
[...] Seriously, we need to start implementing versioned docs on dlang.org.
We do. But stable right now is in beta, so the docs are going to reflect what will soon be released. What we probably should do is have a "released" branch for the docs. Or just answer the odd question every once in a while on the forums :)
Oh wait, this is the dlang.org repository. Yeah, so in answer to a few questions here: 1. The dlang.org repository is backwards -- master generates the docs for the default dlang.org. I've brought this up before, still don't understand why we don't use stable for the latest dlang.org. 2. No, the new hash-map methods will not be in 2.081 releasing on July 1st, because that merge was more recent than the date 2.081 was branched for release (6/17). -Steve
Jun 26 2018
next sibling parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Tue, Jun 26, 2018 at 12:54:11PM -0400, Steven Schveighoffer via
Digitalmars-d wrote:
[...]
 1. The dlang.org repository is backwards -- master generates the docs
 for the default dlang.org. I've brought this up before, still don't
 understand why we don't use stable for the latest dlang.org.
Probably because we want to keep phobos-prerelease up-to-date with git master? The only sane way to do this IMO is to make the dlang.org makefiles generate multiple versions of the docs, thereby acting as the authoritative source for all dlang.org pages. This means released specs need to be archived separately (e.g., by copying to spec/${version}/* and linking stuff there). I just checked the versioned docs with the button on the upper right of the page... it links to dlang.io, which IMO is a bad idea, not because of dlang.io itself but because we're basically relying on an external URL to contain what we assume it might contain. IMO it's better to keep all versions of the docs in a single repo (dlang.org) so that things can be updated/refreshed from a single source, in keeping with SSOT. Doing it that way then lets us do things like fix typos in older docs without unnecessary complications.
 2. No, the new hash-map methods will not be in 2.081 releasing on July
 1st, because that merge was more recent than the date 2.081 was
 branched for release (6/17).
[...] That makes it even the more confusing. :-/ T -- Valentine's Day: an occasion for florists to reach into the wallets of nominal lovers in dire need of being reminded to profess their hypothetical love for their long-forgotten.
Jun 26 2018
parent reply Seb <seb wilzba.ch> writes:
On Tuesday, 26 June 2018 at 17:12:37 UTC, H. S. Teoh wrote:
 On Tue, Jun 26, 2018 at 12:54:11PM -0400, Steven Schveighoffer 
 via Digitalmars-d wrote: [...]
 1. The dlang.org repository is backwards -- master generates 
 the docs for the default dlang.org. I've brought this up 
 before, still don't understand why we don't use stable for the 
 latest dlang.org.
Probably because we want to keep phobos-prerelease up-to-date with git master?
FWIW the docs in the release archives are built from stable. The reason is that both stable _and_ master are built on dlang.org, so historically no one was interested in doing release management for the docs.
 The only sane way to do this IMO is to make the dlang.org 
 makefiles generate multiple versions of the docs, thereby 
 acting as the authoritative source for all dlang.org pages.
It already takes 20 minutes to do a full build of all dlang.org HTML pages. Doing it for old versions is a REALLY bad idea as you are susceptible to - more random failures (e.g. DUB registry being down) - it will take hours for each build - it won't be possible to do it in a CI for each PR due to the large time required, which means the deployment could be broken without us knowing - resources might be offline or change (e.g. currently it fetches the RSS from the DBlog for the frontpage indexes, this already broke the build a few times) - building all versions will fail due to newer dependencies or OS-level changes (e.g. -fPIC, glibc changes, ...)
 This means released specs need to be archived separately (e.g., 
 by copying to spec/${version}/* and linking stuff there).

 I just checked the versioned docs with the button on the upper 
 right of the page... it links to dlang.io, which IMO is a bad 
 idea, not because of dlang.io itself but because we're 
 basically relying on an external URL to contain what we assume 
 it might contain.  IMO it's better to keep all versions of the 
 docs in a single repo (dlang.org) so that things can be 
 updated/refreshed from a single source, in keeping with SSOT.  
 Doing it that way then lets us do things like fix typos in 
 older docs without unnecessary complications.
Ehm the docarchives are simple a snapshot of each version (that's why the "Improve this page" doesn't work or the "Version" button says it's stable even though it's 2.076 (or there isn't even a version button at all). Anyhow, I'm pretty sure that we don't want to put all the HTML files into the main dlang.org git repo. It's about 5 GB extracted. The repo is here and part of the official D GitHub organization https://github.com/dlang/docarchives.dlang.io I don't see any problem of hosting it there, after all, the content never changes. There hasn't been much interest in it so far, so I doubt that moving things will make this any better.
Jun 26 2018
parent reply Jacob Carlborg <doob me.com> writes:
On 2018-06-27 01:22, Seb wrote:
 On Tuesday, 26 June 2018 at 17:12:37 UTC, H. S. Teoh wrote:
 On Tue, Jun 26, 2018 at 12:54:11PM -0400, Steven Schveighoffer via
 Digitalmars-d wrote: [...]
 1. The dlang.org repository is backwards -- master generates the docs
 for the default dlang.org. I've brought this up before, still don't
 understand why we don't use stable for the latest dlang.org.
Probably because we want to keep phobos-prerelease up-to-date with git master?
FWIW the docs in the release archives are built from stable. The reason is that both stable _and_ master are built on dlang.org, so historically no one was interested in doing release management for the docs.
 The only sane way to do this IMO is to make the dlang.org makefiles
 generate multiple versions of the docs, thereby acting as the
 authoritative source for all dlang.org pages.
It already takes 20 minutes to do a full build of all dlang.org HTML pages. Doing it for old versions is a REALLY bad idea as you are susceptible to - more random failures (e.g. DUB registry being down) - it will take hours for each build - it won't be possible to do it in a CI for each PR due to the large time required, which means the deployment could be broken without us knowing - resources might be offline or change (e.g. currently it fetches the RSS from the DBlog for the frontpage indexes, this already broke the build a few times) - building all versions will fail due to newer dependencies or OS-level changes (e.g. -fPIC, glibc changes, ...)
An alternative would be to specify for each symbol when it was introduced. A simple way would be to just add it to the documentation. Or it could be added as a UDA, this would be more flexible. If the current docs now which version itself is it could add an option to filter out symbols for a given version. Having it as a UDA could also give other future advantages. For example, when building applications on macOS, Apple recommends always using the latest SDK even when deploying to older version of the OS. Symbols are annotated with in which version of the OS they were introduced. Then the compiler will give an error/warning if using a symbol without the proper guards and deploying to an older version of the OS. Not sure if this would be interesting to us but it shows using a UDA could have advantages. -- /Jacob Carlborg
Jun 27 2018
parent Seb <seb wilzba.ch> writes:
On Wednesday, 27 June 2018 at 13:41:46 UTC, Jacob Carlborg wrote:
 On 2018-06-27 01:22, Seb wrote:
 On Tuesday, 26 June 2018 at 17:12:37 UTC, H. S. Teoh wrote:
 On Tue, Jun 26, 2018 at 12:54:11PM -0400, Steven 
 Schveighoffer via
 Digitalmars-d wrote: [...]
 1. The dlang.org repository is backwards -- master generates 
 the docs
 for the default dlang.org. I've brought this up before, 
 still don't
 understand why we don't use stable for the latest dlang.org.
Probably because we want to keep phobos-prerelease up-to-date with git master?
FWIW the docs in the release archives are built from stable. The reason is that both stable _and_ master are built on dlang.org, so historically no one was interested in doing release management for the docs.
 The only sane way to do this IMO is to make the dlang.org 
 makefiles
 generate multiple versions of the docs, thereby acting as the
 authoritative source for all dlang.org pages.
It already takes 20 minutes to do a full build of all dlang.org HTML pages. Doing it for old versions is a REALLY bad idea as you are susceptible to - more random failures (e.g. DUB registry being down) - it will take hours for each build - it won't be possible to do it in a CI for each PR due to the large time required, which means the deployment could be broken without us knowing - resources might be offline or change (e.g. currently it fetches the RSS from the DBlog for the frontpage indexes, this already broke the build a few times) - building all versions will fail due to newer dependencies or OS-level changes (e.g. -fPIC, glibc changes, ...)
An alternative would be to specify for each symbol when it was introduced. A simple way would be to just add it to the documentation. Or it could be added as a UDA, this would be more flexible. If the current docs now which version itself is it could add an option to filter out symbols for a given version. Having it as a UDA could also give other future advantages. For example, when building applications on macOS, Apple recommends always using the latest SDK even when deploying to older version of the OS. Symbols are annotated with in which version of the OS they were introduced. Then the compiler will give an error/warning if using a symbol without the proper guards and deploying to an older version of the OS. Not sure if this would be interesting to us but it shows using a UDA could have advantages.
If someone wants to build sth like this, this should be easily doable without attributes as we have DMD's json Output for each phobos version: https://github.com/dlang/docarchives.dlang.io/blob/master/archives/v2.080.0/docs-latest.json Ddox uses this file to generate its entire documentation, so just iterating over the json files and checking in which json file a specific symbol stops to appear shouldn't be too hard to automate. The harder bit is to integrate this aggregated information with the actual docs, but in the worst case we can always fallback to a bit of JavaScript (and we have a custom preprocessor for ddoc too). Of course an aggregator could also edit Phobos directly, s.t. all this work doesn't need to be done by hand...
Jun 27 2018
prev sibling parent Seb <seb wilzba.ch> writes:
On Tuesday, 26 June 2018 at 16:54:11 UTC, Steven Schveighoffer 
wrote:
 On 6/26/18 12:48 PM, Steven Schveighoffer wrote:
 On 6/26/18 11:51 AM, H. S. Teoh wrote:
 On Tue, Jun 26, 2018 at 07:25:09AM +0000, Mike Franklin via 
 Digitalmars-d wrote:
 [...]
 I think the documentation gets published prematurely.  The 
 new methods
 for the associative arrays should come in the next release, 
 scheduled
 for July 1st.  
 https://dlang.org/changelog/pending.html#require_update
[...] Seriously, we need to start implementing versioned docs on dlang.org.
We do. But stable right now is in beta, so the docs are going to reflect what will soon be released. What we probably should do is have a "released" branch for the docs. Or just answer the odd question every once in a while on the forums :)
Oh wait, this is the dlang.org repository. Yeah, so in answer to a few questions here: 1. The dlang.org repository is backwards -- master generates the docs for the default dlang.org. I've brought this up before, still don't understand why we don't use stable for the latest dlang.org.
It's actually not so difficult to change, you just need to ping Vladimir who is in charge of dlang.org's deployment and then we should set `stable` as default GitHub branch. As mentioned, stable is already used for the released docs in the official archives/installer and Martin already does the entire merging/branching off for dlang.org. Though I'm pretty sure that if we are going to change this, people are going to confused and try to make changes to master and wonder why they don't end up on dlang.org We typically don't have many changes like this one that have to be delayed for one version and in this case in the past we simply tagged the PR as "don't merge before X". Anyway, if we want to go this route, we probably want to have a way to preview the upcoming spec on dlang.org (e.g. spec-prerelease).
Jun 26 2018