Write positions for inter code being generated.

§1. A bookmark does not record an actual position in an Inter tree — if we needed that, a pointer to the relevant inter_tree_node would do fine — but to a hypothetical position. It describes where to put a node which has not yet been put into position.

It does this by recording not only a reference node R but a relationship which the hypothetical new position will have with respect to it:

enum BEFORE_NODEPLACEMENT from 0
enum AFTER_NODEPLACEMENT
enum IMMEDIATELY_AFTER_NODEPLACEMENT
enum AS_FIRST_CHILD_OF_NODEPLACEMENT
enum AS_LAST_CHILD_OF_NODEPLACEMENT

typedef struct inter_bookmark {
    struct inter_tree_node *R;
    int placement_wrt_R;  one of the *_NODEPLACEMENT values
} inter_bookmark;

• The structure inter_bookmark is accessed in 2/np and here.

§2. Bookmarks are used to mark positions in an Inter tree, though they are often used in a way which causes them to move forwards through that tree, much as a bookmark will migrate through a book as it is slowly read.

Because of this, the bookmark structure is one of the few in the Inform tool chain to be used sometimes as a value and sometimes a reference — that is, we make use both of inter_bookmark and inter_bookmark * as types. So a function which simply needs to know where to do something will take the type inter_bookmark as an argument — see NodePlacement::move_to, for example — whereas a function which does something but then nudges the bookmark onwards will take an inter_bookmark *, as in the case of NodePlacement::move_to_moving_bookmark.

Dereferencing a bookmark pointer to a bookmark value is called taking a "snapshot". The idea is that the original is likely to move on, but we want to preserve the position it is currently at. For clarity of the code, we give this a name as a function:

inter_bookmark InterBookmark::snapshot?Usage of InterBookmark::snapshot:
§3
Node Placement - §3(inter_bookmark *IBM) {
    return *IBM;
}

§3. We can also take a snapshot but change the placement:

inter_bookmark InterBookmark::shifted(inter_bookmark *IBM, int new_placement) {
    inter_bookmark new_IBM = InterBookmark::snapshot(IBM);
    new_IBM.placement_wrt_R = new_placement;
    return new_IBM;
}

§4. Of course, we can only snapshot a bookmark already existing somewhere else, so we still need creator functions:

inter_bookmark InterBookmark::at_start_of_this_repository?Usage of InterBookmark::at_start_of_this_repository:
Inter in Binary Files - §10
Inter in Text Files - §1(inter_tree *I) {
    return InterBookmark::after_this_node(I->root_node);
}

inter_bookmark InterBookmark::after_this_node?Usage of InterBookmark::after_this_node:
Node Placement - §3.1
Transmigration - §3.1(inter_tree_node *D) {
    return InterBookmark::new(D, AFTER_NODEPLACEMENT);
}

inter_bookmark InterBookmark::at_end_of_root?Usage of InterBookmark::at_end_of_root:
Node Placement - §3(inter_tree *I) {
    return InterBookmark::last_child_of(I->root_node);
}

inter_bookmark InterBookmark::at_end_of_this_package?Usage of InterBookmark::at_end_of_this_package:
Transmigration - §3.1(inter_package *pack) {
    if (pack == NULL) internal_error("no package supplied");
    return InterBookmark::last_child_of(InterPackage::head(pack));
}

inter_bookmark InterBookmark::last_child_of?Usage of InterBookmark::last_child_of:
Node Placement - §3.1(inter_tree_node *D) {
    return InterBookmark::new(D, AS_LAST_CHILD_OF_NODEPLACEMENT);
}

inter_bookmark InterBookmark::immediately_after(inter_tree_node *D) {
    return InterBookmark::new(D, IMMEDIATELY_AFTER_NODEPLACEMENT);
}

inter_bookmark InterBookmark::first_child_of?Usage of InterBookmark::first_child_of:
Node Placement - §3.1(inter_tree_node *D) {
    return InterBookmark::new(D, AS_FIRST_CHILD_OF_NODEPLACEMENT);
}

inter_bookmark InterBookmark::new(inter_tree_node *D, int placement) {
    if (D == NULL) internal_error("no node in bookmark");
    inter_bookmark IBM;
    IBM.R = D;
    IBM.placement_wrt_R = placement;
    return IBM;
}

§5. Note that this moves the bookmark, not whatever node in the tree the bookmark is (or was) marking.

void InterBookmark::move_into_package?Usage of InterBookmark::move_into_package:
Inter in Text Files - §3.2
The Package Construct - §6(inter_bookmark *IBM, inter_package *P) {
    if (IBM == NULL) internal_error("no bookmark supplied");
    if (P == NULL) internal_error("invalid package supplied");
    inter_tree_node *D = InterPackage::head(P);
    if (D == NULL) D = InterPackage::tree(P)->root_node;
    if (InterTree::last_child(D)) {
        IBM->R = InterTree::last_child(D);
        IBM->placement_wrt_R = AFTER_NODEPLACEMENT;
    } else {
        IBM->R = D;
        IBM->placement_wrt_R = AS_FIRST_CHILD_OF_NODEPLACEMENT;
    }
}

§6. Following the same conventions, this function returns the package into which a node moved to the bookmark would then live. In particular, InterBookmark::package(InterBookmark::move_into_package(IBM, P)) is always equal to P.

inter_package *InterBookmark::package?Usage of InterBookmark::package:
§7
Inter Nodes - §5
The Warehouse - §7
Symbols Tables - §17
Transmigration - §4.1.1, §4.2.1.1
Inter Constructs - §6
Inter in Text Files - §3.2
Inter Value Pairs - §6, §8, §9, §11, §13, §15
The Comment Construct - §2
The Constant Construct - §2, §4
The Insert Construct - §2
The Instance Construct - §2
The Nop Construct - §2
The Origin Construct - §2
The Package Construct - §3, §4
The PackageType Construct - §2
The Permission Construct - §2
The Pragma Construct - §2
The Primitive Construct - §2
The Property Construct - §2
The PropertyValue Construct - §2
The Provenance Construct - §2
The Typename Construct - §2
The Variable Construct - §2
The Assembly Construct - §2
The Cast Construct - §2
The Code Construct - §2
The Evaluation Construct - §2
The Inv Construct - §3
The Lab Construct - §2
The Label Construct - §2
The Local Construct - §2
The Ref Construct - §2
The Reference Construct - §2
The Splat Construct - §2
The Val Construct - §2(inter_bookmark *IBM) {
    if (IBM == NULL) return NULL;
    inter_package *pack = IBM->R->package;
    if ((IBM->placement_wrt_R == AS_FIRST_CHILD_OF_NODEPLACEMENT) ||
        (IBM->placement_wrt_R == AS_LAST_CHILD_OF_NODEPLACEMENT)) {
        inter_package *R_defined = PackageInstruction::at_this_head(IBM->R);
        if (R_defined) pack = R_defined;
    }
    return pack;
}

§7. Some convenience functions:

inter_tree *InterBookmark::tree?Usage of InterBookmark::tree:
Inter Nodes - §5
Node Placement - §3
Symbols Tables - §17
Inter in Text Files - §3.3, §6, §12
Inter Value Pairs - §6, §8, §9, §11, §15
The Package Construct - §4, §6
The Provenance Construct - §2, §5
The Inv Construct - §3, §7.1
The Plug Construct - §2
The Socket Construct - §2(inter_bookmark *IBM) {
    if (IBM == NULL) return NULL;
    return IBM->R->tree;
}

inter_warehouse *InterBookmark::warehouse?Usage of InterBookmark::warehouse:
The Warehouse - §7
The Insert Construct - §2
The Instance Construct - §2
The Package Construct - §4
The Property Construct - §2
The Typename Construct - §2(inter_bookmark *IBM) {
    return InterTree::warehouse(InterBookmark::tree(IBM));
}

int InterBookmark::baseline?Usage of InterBookmark::baseline:
§8
Inter Constructs - §6
Inter in Text Files - §3.2(inter_bookmark *IBM) {
    inter_package *pack = InterBookmark::package(IBM);
    if (pack) return InterPackage::baseline(pack);
    return 0;
}

inter_symbols_table *InterBookmark::scope?Usage of InterBookmark::scope:
Inter in Text Files - §5, §12, §12.14
The Constant Construct - §6.1
The Instance Construct - §4.1, §4.2
The Origin Construct - §4
The Package Construct - §4, §6
The PackageType Construct - §3
The Permission Construct - §4
The Primitive Construct - §4
The Property Construct - §4
The PropertyValue Construct - §4
The Typename Construct - §4
The Variable Construct - §4
The Cast Construct - §4
The Lab Construct - §4
The Label Construct - §4
The Local Construct - §4
The Ref Construct - §4
The Val Construct - §4
The Plug Construct - §2
The Socket Construct - §2(inter_bookmark *IBM) {
    inter_package *pack = InterBookmark::package(IBM);
    if (pack) return InterPackage::scope(pack);
    return InterTree::global_scope(InterBookmark::tree(IBM));
}

§8. Logging:

void InterBookmark::log?Usage of InterBookmark::log:
Bytecode Module - §3.6(OUTPUT_STREAM, void *virs) {
    inter_bookmark *IBM = (inter_bookmark *) virs;
    if (IBM == NULL) WRITE("<null-bookmark>");
    else {
        LOG("<");
        switch (IBM->placement_wrt_R) {
            case BEFORE_NODEPLACEMENT: WRITE("before:"); break;
            case AFTER_NODEPLACEMENT: WRITE("after:"); break;
            case IMMEDIATELY_AFTER_NODEPLACEMENT: WRITE("immediately-after:"); break;
            case AS_FIRST_CHILD_OF_NODEPLACEMENT: WRITE("first-child:"); break;
            case AS_LAST_CHILD_OF_NODEPLACEMENT: WRITE("last-child:"); break;
            default: WRITE("?:"); break;
        }
        if (IBM->R) WRITE("%d", IBM->R->W.index); else WRITE("<NO-NODE>");
        LOG("(%d)>", InterBookmark::baseline(IBM));
    }
}