[Iamb-dev-internal] IAMB $stree API, version 2E-10

[Ken R. <kr...@qx...>]

> KEN, HEY KEN, is api-vaporware-0.01 coming out soon? :)

It's now mistware; fire away. :-)

I hope that I have understood what Matt is asking for this time.
Last time was more than a bit off.

Well, I worked on typing it out, and am really quite embarrassed
at how small it really is. Once I got rid of all the calls that
shouldn't have been there in the first place, there wasn't much
left.

-- Ken

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

API for $stree methods for IAMB
+++++++++++++++++++++++++++++++

Definitions (since I found myself using terminology inconsistently)


Thread: An article that has no ancestor together with all its
descendants.

Root article: a top-level article in a forum. Also called the root of a
thread.
(The root is a single article; a thread is potentially many more.)

Subthread: Any article in the thread, together with its descendants.
(Note that the thread is also, by abuse of terminology, a subthread.)

Flat mode: (This is what I have gathered; I could be way off here.)
A printed listing or display of all bodies of the articles in a
subthread
that (somehow) allows you to understand how all the articles were
connected.

Genealogy: A list of article IDs that starts with the root article ID
and continues to the article ID, each ID being an immediate descendant
of the previous ID. An alternative is the reverse order.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

General observations:

1. I am assuming here that I am only dealing with the $stree itself.
There are no calls affecting users, database stuff (not even the
consistency call that I leave for Matt's daemon to run), or objects
other than the $stree string itself. That is, the $stree calls
reflect only what other calls have done. You would create (plant)
a stree as a part of the process of starting a new thread. The
$stree call itself does none of that. (I was way out of bounds
in the previous API.)

2. I am assuming that the $stree will be an blessed string in the
appropriate thread class.

3. I have dropped all the iamb_dev prefixes as unnecessarily
pedantic. We all know that this is the development branch.

4. I have gone with the idea of using gardening metaphors for the names
of the calls: you plant a new stree; prune or graft a branch; a new
article is called a bud; etc. Am I just being silly? These can be
changed to more standard terminology very easily.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++



-Call: $stree = plant stree( ARTICLE = $ArticleID );
-Input parameters: $ArticleID = ID of root article
-Return value(s): $stree = the newly created stree
-Description: It is assumed that the article has already been added
to the database, and therefore has an ID. The initial $stree looks
like "[$ArticleID]". The call should also bless the $stree into the
appropriate thread class.


-Call: $branch = $stree -> prune( ARTICLE = $ArticleID );
-Input parameters: $articleID = ID of subthread article to delete
-Return value(s): $branch = the pruned part, suitable for grafting
elsewhere
-Description: This call should delete all the articles in a given thread
or subthread from the $stree. The removed string goes into $branch.


-Call: $stree -> graft( BRANCH = $branch, GRAFTPOINT = $ArticleID );
-Input parameters: $branch = branch to be added
		   $ArticleID = ID of article onto which the branch
			is grafted
-Description: This call inserts a subthread into thread. The intention
is that the prune + graft combination allows a rather flexible means of
low-level manipulation of the $stree, moving subthreads around.


-Call: $stree -> bud ( NEWARTICLE = $newArticleID, PARENT =
$parentArticleID );
-Input parameters: $newArticleID = ID of article to add to $stree
		   $parentArticleID = ID of article to which the new
			responded
-Description: This call manipulates $stree to add the new article ID
at the correct point.


-Call: @siblings = $stree -> siblings ( ARTICLE = $ArticleID );
-Input parameters: $ArticleID = ID of article to find siblings for
-Return value(s): @siblings = array of article IDs of siblings of an
article
-Description: This call searches the $stree and returns an array of
the article IDs that have the same immediate ancestor as $articleID.
I'm not sure why this is useful, but I expect that it could be.


-Call: @ancestors = $stree -> heritage( ARTICLE = $ArticleID );
-Input parameters: $articleID = ID of article for which to find
ancestors
-Return value(s): @ancestors = array of article IDs of ancestors back to
			the forum root.
-Description: This call searches the $stree of article IDs and returns
the genealogy of the article. The order is yet to be determined, but it
seems that the easiest one is to put first the immediate ancestor and
last the root article. The question is whether or not the reverse order
is more useful.


-Call: $level = $stree -> branch_level( ARTICLE = $ArticleID );
-Input parameters: $ArticleID = ID of article to determine indentation
			level for
-Return value: $level = how many generations from the root article this
			article is
-Description: This would be useful to have for some flat mode stuff, and
could be done by simply counting ancestors, but a more efficient
algorithm
exists for just finding $level. Again, this call might never be used,
but
then again, it might.


-Call: ($before, $after) = $stree -> dissect( ARTICLE = $ArticleID );
-Input parameters: $ArticleID = ID of article to split $stree at
-Return values: $before = part of $stree string strictly prior to
			(not including) the $ArticleID
		$after = part of $stree string that follows $ArticleID
-Description: This call would split $stree at $ArticleID into two
substrings, $before and $after. It would be called by
$stree -> bud(), $stree -> prune(), and $stree -> graft(), so it is
worth writing once separately.