Decoded: Rogue (1980) by Toy, Arnold, Wichman
DOS version (1983) by Mel Sibony and Jon Lane
Source file: LIST.C
Beginner friendly, line-by-line code walkthrough by MaiZure

LIST.C is Rogue's linked list implementation. This list is not general
purpose because it assumes that all entries are game items/monsters...

Original code:
https://britzl.github.io/roguearchive/

Original code with line numbers
http://www.maizure.org/projects/decoded-rogue/LIST_linenum.txt



1     COMMENT
2     COMMENT
3     COMMENT
4     COMMENT
5     COMMENT
6     COMMENT
7     COMMENT
8     BLANK
9     Includes the game header
10    Includes the console management header
11    BLANK
12    Import the global items linked list
13    Import the global item counter
14    COMMENT
15    COMMENT
16    COMMENT
17    COMMENT

REMOVES AN ENTRY FROM THE LIST
Don't lose this pointer!

18    Defines _detach with two arguments
19    Argument 1 is the list, argument 2 is the item
20    BLOCK START - _detach, removes an (already found) item from the list
21    If the base item in the list is the item we're detaching...
22    Repoint the head of the list to the next item
23    If the item has a predecessor, repoint it to the successor
24    If the item has a successor, report successor to predecessor
25    Remove item's successor link
26    Remove item's predecessor link
27    BLOCK END - _detach
28    BLANK
29    COMMENT
30    COMMENT
31    COMMENT
32    COMMENT

ADDS AN ENTRY TO THE LIST

33    Defines _attach with two arguments
34    Argument 1 is the list, argument 2 is the item
35    BLOCK START - _attach, adds an item to the list head
36    If the list has at least one element already...
37    BLOCK START - Adding to a populated list
38    Point the new item to the first element in the list
39    Point first element in the list's predecessor to the new item
40    The new item has no predcessor, its the head of the list (line 47)
41    BLOCK END - Adding to a populated list
42    Otherwise the list is empty..
43    BLOCK START - Adding to an empty list
44    New item has no successor
45    New item has no predecessor
46    BLOCK END - Adding to an empty list
47    Make the new item the head of the list
48    BLOCK END - _attach
49    BLANK
50    COMMENT
51    COMMENT
52    COMMENT
53    COMMENT

CLEAR THE LIST

54    Define _free_list with one argument
55    Argument 1 is a pointer to the list to destroy
56    BLOCK START - _free_list - destroys all items in the list
57    Declare a pointer to a game item (in the list)
58    BLANK
59    Loop while the list has items
60    BLOCK START - Clean the list
61    Get the head item
62    Move the list head to the next item
63    Destroy the now-unlinked item
64    BLOCK END - Clean the list
65    BLOCK END - _free_list
66    BLANK
67    BLANK
68    COMMENT
69    COMMENT
70    COMMENT
71    COMMENT

CREATE A NEW LIST ENTRY

72    new_item returns a pointer to a game object
73    Define new_item with no arguments
74    BLOCK START - new_item, creates a new object
75    Declare a pointer to a game object
76    Check for debug mode...
77    Allocate a new item and if it could not be allocated...
78    Send a failure message to the player
79    Otherwise, the item was allocated so..
80    If not debug mode...
81    If the item was successfully allocated
82    End check for debug mode
83    Null out the next and prev pointers (don't lost this item!)
84    Return the item
85    BLOCK END - new_item
86    BLANK
87    COMMENT
88    COMMENT
89    COMMENT

ALLOCATE MEMORY FOR AN ENTRY

90    Define talloc with no arguments
91    BLOCK START - talloc, allocates memory for a new object
92    Declare an iterator
93    BLANK
94    Loop through all 83 of the possible generated items
95    BLOCK START - Item loop
96    If the item hasn't been allocated..
97    BLOCK START - Allocate a new item
98    If this is the largest number of items so far....
99    Update the largest item count 
100   Increment the counter for that item
101   Set the object's bytes to 0 (in the master 'thing' array)
102   Return a pointer to the new object
103   BLOCK END - Allocate a new item
104   BLOCK END - Item loop
105   Return failure
106   BLOCK END - talloc
107   BLANK
108   COMMENT
109   COMMENT
110   COMMENT
111   COMMENT

DESTROY AN ENTRY

112   Define discard with one argument
113   Argument 1 is the item to destroy
114   BLOCK START - discard, destorys an item
115   Declare an interator
116   BLANK
117   Loop through all items
118   BLOCK START - All item loop
119   If the input item is found...
120   BLOCK START - Destroy target item
121   Decrement the item total
122   Deallocate item
123   Return success
124   BLOCK END - Destroy target item
125   BLOCK END - All item loop
126   Return failure
127   BLOCK END - discard
128   EOF˙