atbind(3)

🎀 atbind(3) 🎀

okay so this is the page for atbind, part of the AtFS Toolkit Library bestie, and it's literally all about version binding. Version binding = picking one unique version out of a named history, and this whole module is the machinery that does it. It's giving ✨library internals✨ but like, in the most slay way possible.

---

✨ NAME ✨

atBindVersion, atBindSet, atBindCache, atBindNoMsg, atScanBinding, atBindTrace, atBindExpandMacro, atBindOptions, atBindModeOption, atBindSetArgv, atBindUsage — version binding 💅

---

🌸 SYNOPSIS 🌸

#include <atfs.h>
#include <atfstk.h>

Af_key*atBindVersion (char *name, *binding);

Af_set*atBindSet (char *pattern, char *binding, int bindMode);

Af_set*atBindCache (char *pattern, *binding);

int  atBindNoMsg;

int  atScanBinding (char *binding, char **resultStr, int *resultGen, int
*resultRev, time_t *resultDate);

int  atBindTrace;

char *(*atBindExpandMacro)(char *inputString);

int  atBindOptions (int argc, char **argv, int newArgc, char
*(*newArgv[]));

int  atBindModeOption;

int  atBindSetArgv (int *argc, char *(*argv[]));

void atBindUsage (char *extraText);

---

💖 DESCRIPTION 💖

🌈 atBindVersion

atBindVersion does a version binding, which is the fancy way of saying: it selects a unique version out of a named history. It expects name to be either a string shaped like historyName[binding] or just a plain name, no drama.

If a version bind directive (binding) is sitting in brackets after the history name, then bestie, the second argument is ignored. If it's not in brackets, then the second argument gets taken as the version bind directive. And if there's no binding at all? Then atBindVersion does the default binding — which can be explicitly defined by afBindOptions (see below), or else it just grabs the most recent version (by modification/saving date). There's a whole list of version bind directive forms further down. 👇

atBindVersion returns the appropriate version key when the bind operation leads to a unique version selection, otherwise NULL. No unique pick, no key, periodt.

🦋 atBindSet

atBindSet works just like atBindVersion, except the first argument can be a name pattern (a sh(1) pattern, to be precise) instead of a single unique file name. It uses the af_histories call (manual page af_history(3)) to generate a list of history names from that pattern. Then it runs a version binding for each name, with a version bind directive given either in square brackets or as the binding argument (same rules as above, bestie).

atBindSet returns a set of version keys holding all the versions it found, or a NULL pointer if something went wrong. 😭

Another option of atBindSet is nonunique version selection within a history — in that case, multiple versions from a single history can end up in the result set. In detail, atBindSet supports four options:

• AT_BIND_UNIQUE — behaves like atBindVersion for each name generated from pattern. Generates no error condition in case of nonunique or empty selection. chill about it 💅
• AT_BIND_SET — (default) does not require uniqueness. If more than one version from a history meets the binding specifications, all of those versions get included in the result set.
• AT_BIND_LAST — selects the last version (by modification/saving date) from the binding hit set of each history. The resulting hit set contains at most one version of each history involved in the bind operation.
• AT_BIND_LASTSAVED — similar to AT_BIND_LAST but it ignores busy versions.

🎀 atBindCache

atBindCache tries to bind versions from the derived object cache. It expects a pattern and binding argument similar to atBindSet. yes, same energy, different cache ✨

💜 atBindNoMsg

The atBindNoMsg switch lets you suppress the output of version binding rules generated by predicates like 'msg`` or 'confirm``. You do that by setting atBindNoMsg to TRUE. Initially it's set to FALSE.

Here's the important bit: when you're evaluating a 'confirm`` predicate (where user input is expected) and atBindNoMsg` is set true, the version binding algorithm proceeds without halting, as if the user had accepted the default input. iconic behaviour tbh.

🔥 atScanBinding

atScanBinding scans the version bind directive binding. It returns the binding type, which is one of:

• AT_BIND_ALIAS — a version alias (symbolic name). Example: foo[release-2]. The alias name is returned in resultStr, and it lives in allocated memory.
• AT_BIND_CACHEKEY — a unique identifier for cached objects. It's automatically generated for each cached object and consists of three numbers (like foo.o[739564427.16390.22]).
• AT_BIND_DATE — a date specification. (see stMktime (manual page sttime(3)) for a list of valid date formats) Examples: foo[Jan 8, 1993], foo[8.1.93]. The date is returned in resultDate.
• AT_BIND_DEFAULT — default binding. This is the case when either an empty binding was given or something like foo[].
• AT_BIND_RULE — version bind Rule. Example: foo[bind_rule:]. A rule may also take the form foo[bind_rule(arg1,arg2,...argN):], which additionally passes the given arguments to the bind rule evaluation. The rule name returned in resultStr lives in allocated memory.
• AT_BIND_VNUM — version number. Example: foo[1.2]. The resulting generation and revision number are returned in resultGen and resultRev.

One important issue bestie: each version alias will also be tried as a rule name if it turns out to be no known symbolic name. This implies that rule names may also be given without the trailing colon, when there are no naming conflicts with version aliases. iykyk.

⭐ atBindTrace

The atBindTrace switch turns on tracing of each version bind operation when set to TRUE. Trace output gets sent to standard error. Initially its value is FALSE.

🧚 atBindExpandMacro

The atBind module provides a hook for an external macro processor to preprocess any version bind rule just before applying it. The bind rule text may contain macro citations of the form $C or $(macroName) (like in Make-/Shapefiles) that are meant to be expanded by the external macro processor.

That processor should expect any string containing macro citations as input and return a string with the macros expanded. When you assign it to the function variable atBindExpandMacro, the macro expansion routine gets invoked for each evaluated rule. cute, right? 🫶

🌸 atBindOptions

atBindOptions calls stParseArgs (manual page atparseargs(3)) with an internally defined standard option vector for command line version binding options. The vbind(1) manual page has a description of these options.

atBindOption should be called before parsing the application specific options. It fetches the version binding options off the command line (input arguments argc and argv) and returns all remaining tokens (output arguments newArgc and newArgv). The return value is the number of erroneous options found (e.g. ones with an argument missing). A negative return value indicates an internal error, and zero is returned on success.

atBindOptions defines the default version selection policy as given on the command line, for the whole application. Every subsequent call of atBindVersion and atBindSet (see above) will conform to this policy — unless an explicit version bind directive is given. 💅

🦋 atBindSetArgv

atBindSetArgv preprocesses a command line (arguments argc and argv) by evaluating and fetching off version binding options, and replacing all filename arguments with bound filenames (e.g. foo[1.4]). It returns the number of arguments remaining on the command line.

🎀 atBindUsage

atBindUsage calls stShortUsage (manual page atparseargs(3)) with the current program name, the bind standard options vector, and the given extraText. The result is a short usage description written to standard error.

---

💀 DIAGNOSTICS 💀

Upon error, the version binding functions (atBindVersion, atBindSet and atBindCache) return a null pointer. atScanBinding has no error conditions, it's just built different.

atBindOptions and atBindSetArgv return -1 on error and a value greater or equal null on success.

On any error, the variable atBindError is set true (non-zero), and an explaining message is copied to the atBindErrorMsg string buffer. The atBindError variable is cleared upon successful calls — but the message buffer remains unchanged. so don't come for the stale message, it's just how it is 😭

---

🍓 FILES 🍓

• $SHAPETOOLS/BindRules

---

🌈 SEE ALSO 🌈

atfstkintro(3), vbind(1), stparseargs(3)

---

and that's the whole page bestie, no notes 💅 this was AtFStk-1.12, dated Fri Jun 25 16:39:30 1993 — yes it's older than most of us and it's still serving, we love a timeless icon 👑✨