Previous Entry Share Next Entry
Release 0.3.19
querki
jducoeur wrote in querki_project
This was a big release, for no real reason except that I kept working instead of releasing.

The overall theme is prep for the Alpha release, which I'm trying to get done before the end of the month. There are several small new features further down, but the main feature is:

Documentation

Big, laborious, pain in the ass, but it's time to get serious about it.

Documented All Properties and Methods: all of the System-level Properties and Methods now have the Property Summary meta-Property set, and most have Property Details. It isn't a fully-detailed manual yet, but it should be enough reference documentation for folks to begin using these things. (And for some of the serious programmers to sit down and read through them all -- I'm sure that I'm not the only person who does that).

The actual Documentation Space (which isn't written quite yet) will mostly be auto-generated from the code. But to support that, there were a bunch of tweaks:

Fixed _allProps: previously, this had always displayed the Properties of the Space you are currently looking at. Fixed it to actually show the Properties of the Space specified in the QL expression.

Added _oid: each Thing in Querki has a unique Object ID, or OID -- if you see a name like ".1z93j4", that's an OID. Unlike names, OIDs are unique across the entire system, so they are helpful for being able to refer to something without worrying about name collisions. (As we go along, a lot more systems will use them under the hood.) The _oid method simply produces the OID of the received Thing.

Added _kind: everything in Querki is a Thing, but each is one of several well-defined Kinds: Property, Type, Collection, Space, Attachment or simply Thing. These are usually referred to by numbers (1 to 6); _kind tells you what Kind this Thing is.

Added _currentSpace: this produces the Space that you are actually looking at in the browser right now, as opposed to _space. (Which produces the Space that contains the received Thing.) It's a subtle distinction, but sometimes important when you're doing App programming.

Added _is: this is essentially the object-identity version of equals -- more or less what "==" means in many languages. We need this method to use inside _if() clauses; I suspect it'll turn out to be pretty routine. (Note that this tests *identity*. We'll probably add "_isa" later, to test whether this Thing inherits from a particular Model.)

Fixed _section to work with one-liners: _section is one of the most-useful methods in Querki -- it receives a List, and formats a Header and Details to match that. Previously, however, it always introduced an extra newline between the Header and Details -- fine if you're creating a bullet list with a big bold header, but bad if you want everything on one line, with the Header at the front. This now works, and usually does the right thing: by the nature of QText/Markdown syntax, it'll usually wind up simply working as intended.

Fixed links with underscores: due to the quirks of Markdown, and the way the Actuarius library (which we're using under the hood) interprets it, saying something like this:
[[_myThingy]]
would often produce weirdly broken results when it was a plain Thing and you're trying to link to it. That's because, in Markdown, surrounding something with underscores turns it into italics, and that expression winds up becoming "[_myThingy](_myThingy)" for the Markdown processing. So instead of seeing the link you expected, you would see [myThingy](myThingy). To fix this, I rearranged the parser so that it doesn't try to interpret Markdown inside of one of these link expressions. (This is ambiguous in the description of Markdown, but *I* think it's correct.)

Backslash-escaping of the main QL delimiters: mainly useful for documenting QL expressions, when you don't want to use the somewhat tempermental _code() method. You can now use a single backslash before "", [[, ]], ____ or __, to keep it from being interpreted as QL. (That is, this is how you tell QText, "No, really -- this is just text", for these things that are otherwise meaningful.)

Other Enhancements

Added the _count Method: this is one I've been wanting for *ages*; I'm honestly not sure why it took so long for me to get around to it. Simple and immensely useful: it receives any Collection, and produces the number of elements in that Collection. It's especially helpful in list headers. (I suddenly realize that the wedding isn't quite as big as I thought it was.)

Introduced Space Evolution: purely an internal matter, but deathly important. One of the oddities of Querki is that it uses a *vast* number of SQL tables. Like, an insane number -- several for each Space. This has a lot of benefits, ranging from security to scalability, but it does mean that when we upgrade, it is seriously infeasible to tweak all those tables at once.

So we're stealing a leaf from Play's book, and implementing a formal Evolution mechanism instead. Each Space is tagged with a version, as is the code. Each code version includes a module that describes the table changes needed to work with that version. When you load a Space, Querki checks whether it is up-to-date; if not, it runs through each of those changes until the Space is ready to roll with the current code.

This will be generally useful going forward, but to begin with, I used it to implement:

The _modTime Method: all Things in Querki now have a last-modified timestamp, as previously mentioned. For the time being I am not implementing creation-time stamps -- the usefulness is less obvious, so I'm more cautious about spending those bytes on every Thing -- but you can now use _modTime to produce the time that any given Thing was last changed. That, in turn, means that we added:

The Date and Time Type: this Type is currently focused on _modTime, but will gradually become more powerful. Internally, it is a Querki layer over Joda-time, the consensus standard for date and time management in the JVM, and I expect that we will eventually expose most or all of Joda's functionality in Querki. (Although I suspect that most of it will eventually be in an App, so as not to pollute the namespace too much.) In the nearish term, I expect to add support for editing, eg, Dates using a standard calendar control. I strongly encourage y'all to think about what you'd like to have in DateTime, and we can schedule features appropriately.

_sort Enhancements: in order to *use* _modTime effectively, we clearly want to be able to sort on timestamps. So the _sort method has been heavily upgraded. Previously, it simply sorted the received Things by Display Name, and that's still the default, but you can now give it an optional parameter. This phrase receives each element of the list in turn, and returns the value to sort on. So you can now say something like:
[[Thingy._instances -> _sort(_modTime)]]
to sort all of the Thingies by modification Time.

To make that more flexible, we provided two more ways to affect a List:

_desc modifier:_sort expects its parameter to return a value, and it sorts based on the Type of that value. But it always sorts ascending, from smallest to biggest. Sometimes, that's exactly wrong -- you want it the other way around. So you can use _desc to reverse the *sort order* of a given value's Type. In other words, where the above example would sort the Thingies from oldest to newest, this:
[[Thingy._instances -> _sort(_desc(_modTime))]]
sorts from newest to oldest.

_reverse: while I was experimenting with this, I implemented the _reverse method. This is very simple and obvious, but likely to be pretty useful: it takes a List and reverses its order. It actually is *not* the best way to reverse the order of a _sort (since there may be issues if you have multiple sort keys), but it's still a good utility function, so I left it in.


Whew -- yeah, big release. But now I can begin to implement the Documentation Space itself. And then on to Users and Invitations, which are designed and ready to start implementation...
Tags:

?

Log in

No account? Create an account