From: Christian Heller <c.heller@plomlompom.de>
Date: Mon, 29 Jul 2013 19:08:45 +0000 (+0200)
Subject: Applied new formatting and documentation rules to misc module.
X-Git-Tag: tce~1119
X-Git-Url: https://plomlompom.com/repos/%7B%7B%20web_path%20%7D%7D/decks/%7B%7Bprefix%7D%7D/static/todo?a=commitdiff_plain;h=7b6558a08527dc27995af156e43734be3da950a0;p=plomrogue

Applied new formatting and documentation rules to misc module.
---

diff --git a/src/misc.c b/src/misc.c
index cb650a0..a8918a9 100644
--- a/src/misc.c
+++ b/src/misc.c
@@ -1,195 +1,353 @@
+/* misc.c */
+
 #include "misc.h"
-#include <stdlib.h>
-#include <string.h>
-#include "windows.h"
-#include "keybindings.h"
-#include "readwrite.h"
-#include "map_objects.h"
-#include "map_object_actions.h"
-#include "map.h"
-#include "main.h"
-#include "yx_uint16.h"
-
-extern void exit_game(struct World * world, struct Map * map) {
-// Clean up and exit.
-  endwin();
-  free(map->cells);
-  uint16_t key;
-  for (key = 0; key <= world->keyswindata->max; key++)
-    free(world->keybindings[key].name);
-  free(world->keybindings);
-  free(world->keyswindata);
-  free(world->log);
-  exit (EXIT_SUCCESS); }
-
-extern void textfile_sizes (FILE * file, uint16_t * linemax_p, uint16_t * n_lines_p) {
-// Learn largest line length (linemax_p) and (n_lines_p if not set to NULL) number of lines.
-  uint16_t n_lines = 0;
-  int c = 0;
-  uint16_t linemax = 0;
-  uint16_t c_count = 0;
-  while (EOF != c) {
-    c_count++;
-    c = getc(file);
-    if ('\n' == c) {
-      if (c_count > linemax)
-        linemax = c_count + 1;
-      c_count = 0;
-      if (n_lines_p)
-        n_lines++; } }
-  fseek(file, 0, SEEK_SET);
-  * linemax_p = linemax;
-  if (n_lines_p)
-    * n_lines_p = n_lines; }
-
-extern uint16_t rrand(char use_seed, uint32_t new_seed) {
-// Pseudo-random number generator (LGC algorithm). Use instead of rand() to ensure portable predictability.
-  static uint32_t seed;
-  if (0 != use_seed)
-    seed = new_seed;
-  seed = ((seed * 1103515245) + 12345) % 2147483648;   // Values as recommended by POSIX.1-2001 (see rand(3)).
-  return (seed / 65536); }                         // Ignore least significant 16 bits (they are less random).
-
-extern void update_log (struct World * world, char * text) {
-// Update log by appending text, or by appending a "." if text is the same as the last one.
-  static char * last_msg;
-  if (0 == last_msg)
-    last_msg = calloc(1, sizeof(char));
-  char * new_text;
-  uint16_t len_old = strlen(world->log);
-  if (0 == strcmp(last_msg, text)) {
-    uint16_t len_whole = len_old + 1;
-    new_text = calloc(len_whole + 1, sizeof(char));
-    memcpy(new_text, world->log, len_old);
-    memcpy(new_text + len_old, ".", 1); }
-  else {
-    uint16_t len_new = strlen(text);
-    uint16_t len_whole = len_old + len_new + 1;
-    new_text = calloc(len_whole, sizeof(char));
-    memcpy(new_text, world->log, len_old);
-    memcpy(new_text + len_old, text, len_new);
-    last_msg = calloc(len_new + 1, sizeof(char));
-    memcpy(last_msg, text, len_new); }
-  free(world->log);
-  world->log = new_text; }
-
-extern uint16_t center_offset (uint16_t pos, uint16_t mapsize, uint16_t framesize) {
-// Return the offset for display of a map inside a frame centered on pos.
-  uint16_t offset = 0;
-  if (mapsize > framesize) {
-    if (pos > framesize / 2) {
-      if (pos < mapsize - (framesize / 2))
-        offset = pos - (framesize / 2);
-      else
-        offset = mapsize - framesize; } }
-  return offset; }
-
-extern void turn_over (struct World * world, char action) {
-// Record action in game record file, increment turn and move enemy.
-  if (1 == world->interactive) {
-    FILE * file = fopen("record", "a");
-    fputc(action, file);
-    fclose(file); }
-  world->turn++;
-  rrand(1, world->seed * world->turn);
-  struct Monster * monster;
-  for (monster = world->monster; monster != 0; monster = monster->map_obj.next)
-    move_monster(world, monster); }
-
-extern void save_game(struct World * world) {
-// Save game data to game file.
-  FILE * file = fopen("savefile", "w");
-  write_uint32_bigendian(world->seed, file);
-  write_uint32_bigendian(world->turn, file);
-  write_uint16_bigendian(world->player->pos.y + 1, file);
-  write_uint16_bigendian(world->player->pos.x + 1, file);
-  fputc(world->player->hitpoints, file);
-  write_map_objects (world->monster, file, write_map_objects_monsterdata);
-  write_map_objects (world->item, file, NULL);
-  fclose(file); }
-
-extern void toggle_window (struct WinMeta * win_meta, struct Win * win) {
-// Toggle display of window win.
-  if (0 != win->frame.curses_win)
-    suspend_win(win_meta, win);
-  else
-    append_win(win_meta, win); }
-
-extern void scroll_pad (struct WinMeta * win_meta, char dir) {
-// Try to scroll pad left or right.
-  if      ('+' == dir)
-    reset_pad_offset(win_meta, win_meta->pad_offset + 1);
-  else if ('-' == dir)
-    reset_pad_offset(win_meta, win_meta->pad_offset - 1); }
-
-extern void growshrink_active_window (struct WinMeta * win_meta, char change) {
-// Grow or shrink active window horizontally or vertically by one cell size.
-  if (0 != win_meta->active) {
-    struct yx_uint16 size = win_meta->active->frame.size;
-    if      (change == '-') size.y--;
-    else if (change == '+') size.y++;
-    else if (change == '_') size.x--;
-    else if (change == '*') size.x++;
-    resize_active_win (win_meta, size); } }
-
-extern struct yx_uint16 find_passable_pos (struct Map * map) {
-// Return a random passable position on map.
-  struct yx_uint16 pos;
-  for (pos.y = pos.x = 0; 0 == is_passable(map, pos);) {
-      pos.y = rrand(0, 0) % map->size.y;
-      pos.x = rrand(0, 0) % map->size.x; }
-  return pos; }
-
-extern unsigned char meta_keys(int key, struct World * world, struct WinMeta * win_meta,
-                               struct Win * win_keys, struct Win * win_map, struct Win * win_info,
-                               struct Win * win_log) {
-// Call some meta program / window management actions dependent on key. Return 1 to signal quitting.
-  if (key == get_action_key(world->keybindings, "quit"))
-    return 1;
-  else if (key == get_action_key(world->keybindings, "scroll pad right"))
-    scroll_pad (win_meta, '+');
-  else if (key == get_action_key(world->keybindings, "scroll pad left"))
-    scroll_pad (win_meta, '-');
-  else if (key == get_action_key(world->keybindings, "toggle keys window"))
-    toggle_window(win_meta, win_keys);
-  else if (key == get_action_key(world->keybindings, "toggle map window"))
-    toggle_window(win_meta, win_map);
-  else if (key == get_action_key(world->keybindings, "toggle info window"))
-    toggle_window(win_meta, win_info);
-  else if (key == get_action_key(world->keybindings, "toggle log window"))
-    toggle_window(win_meta, win_log);
-  else if (key == get_action_key(world->keybindings, "cycle forwards"))
-    cycle_active_win(win_meta, 'n');
-  else if (key == get_action_key(world->keybindings, "cycle backwards"))
-    cycle_active_win(win_meta, 'p');
-  else if (key == get_action_key(world->keybindings, "shift forwards"))
-    shift_active_win(win_meta, 'f');
-  else if (key == get_action_key(world->keybindings, "shift backwards"))
-    shift_active_win(win_meta, 'b');
-  else if (key == get_action_key(world->keybindings, "grow horizontally"))
-    growshrink_active_window(win_meta, '*');
-  else if (key == get_action_key(world->keybindings, "shrink horizontally"))
-    growshrink_active_window(win_meta, '_');
-  else if (key == get_action_key(world->keybindings, "grow vertically"))
-    growshrink_active_window(win_meta, '+');
-  else if (key == get_action_key(world->keybindings, "shrink vertically"))
-    growshrink_active_window(win_meta, '-');
-  else if (key == get_action_key(world->keybindings, "save keys"))
-    save_keybindings(world);
-  else if (key == get_action_key(world->keybindings, "keys nav up"))
-    keyswin_move_selection (world, 'u');
-  else if (key == get_action_key(world->keybindings, "keys nav down"))
-    keyswin_move_selection (world, 'd');
-  else if (key == get_action_key(world->keybindings, "keys mod"))
-    keyswin_mod_key (world, win_meta);
-  else if (key == get_action_key(world->keybindings, "map up"))
-    map_scroll (world->map, NORTH, win_map->frame.size);
-  else if (key == get_action_key(world->keybindings, "map down"))
-    map_scroll (world->map, SOUTH, win_map->frame.size);
-  else if (key == get_action_key(world->keybindings, "map right"))
-    map_scroll (world->map, EAST, win_map->frame.size);
-  else if (key == get_action_key(world->keybindings, "map left"))
-    map_scroll (world->map, WEST, win_map->frame.size);
-  else if (key == get_action_key(world->keybindings, "map center player"))
-    map_center_player (world->map, world->player, win_map->frame.size);
-  return 0; }
+#include <stdlib.h> /* for exit(), EXIT_SUCCESS define, calloc(), free() */
+#include <string.h> /* for strlen(), strcmp(), memcpy() */
+#include <ncurses.h> /* for endwin() */
+#include "windows.h" /* for suspend_win(), append_win(), reset_pad_offset(), */
+                     /* resize_active_win(), cycle_active_win(),             */
+                     /* shift_active_win(), struct Win, struct WinMeta       */
+#include "keybindings.h" /* for get_action_key(), save_keybindings(),  */
+                         /* keyswin_move_selection(), keyswin_mod_key() */
+#include "readwrite.h" /* for write_uint16_bigendian() */
+                       /* write_uint32_bigendian()     */
+#include "map_objects.h" /* for struct Monster, write_map_objects(), */
+                         /* write_map_objects_monsterdata()          */
+#include "map_object_actions.h" /* for is_passable(), move_monster() */
+#include "map.h" /* for map_scroll()/map_center_player(), Map struct, dir enum */
+#include "main.h" /* for World struct */
+#include "yx_uint16.h" /* for yx_uint16 */
+
+
+
+extern void exit_game(struct World * world, struct Map * map)
+{
+    endwin();
+    free(map->cells);
+    uint16_t key;
+    for (key = 0; key <= world->keyswindata->max; key++)
+    {
+        free(world->keybindings[key].name);
+    }
+    free(world->keybindings);
+    free(world->keyswindata);
+    free(world->log);
+    exit (EXIT_SUCCESS);
+}
+
+
+
+extern void textfile_sizes(FILE * file, uint16_t * linemax_p,
+                           uint16_t * n_lines_p)
+{
+    uint16_t n_lines = 0;
+    int c = 0;
+    uint16_t linemax = 0;
+    uint16_t c_count = 0;
+    while (EOF != c)
+    {
+        c_count++;
+        c = getc(file);
+        if ('\n' == c)
+        {
+            if (c_count > linemax)
+            {
+                linemax = c_count + 1;
+            }
+            c_count = 0;
+            if (n_lines_p)
+            {
+                n_lines++;
+            }
+        }
+    }
+    fseek(file, 0, SEEK_SET);
+    * linemax_p = linemax;
+    if (n_lines_p)
+    {
+        * n_lines_p = n_lines;
+    }
+}
+
+
+
+extern uint16_t rrand(char use_seed, uint32_t new_seed)
+{
+    static uint32_t seed;
+    if (0 != use_seed)
+    {
+        seed = new_seed;
+    }
+
+    /* Constants as recommended by POSIX.1-2001 (see man page rand(3)). */
+    seed = ((seed * 1103515245) + 12345) % 2147483648;
+
+    return (seed / 65536);    /* TODO: Use bit-shifting for ignoring the less */
+}                             /* random least significant 16 bits.            */
+
+
+
+extern void update_log(struct World * world, char * text)
+{
+    static char * last_msg;
+    if (0 == last_msg)
+    {
+        last_msg = calloc(1, sizeof(char));
+    }
+    char * new_text;
+    uint16_t len_old = strlen(world->log);
+    if (0 == strcmp(last_msg, text))
+    {
+        uint16_t len_whole = len_old + 1;
+        new_text = calloc(len_whole + 1, sizeof(char));
+        memcpy(new_text, world->log, len_old);
+        memcpy(new_text + len_old, ".", 1);
+    }
+    else
+    {
+        uint16_t len_new = strlen(text);
+        uint16_t len_whole = len_old + len_new + 1;
+        new_text = calloc(len_whole, sizeof(char));
+        memcpy(new_text, world->log, len_old);
+        memcpy(new_text + len_old, text, len_new);
+        last_msg = calloc(len_new + 1, sizeof(char));
+        memcpy(last_msg, text, len_new);
+    }
+    free(world->log);
+    world->log = new_text;
+}
+
+
+
+extern uint16_t center_offset(uint16_t pos, uint16_t mapsize,
+                              uint16_t framesize)
+{
+    uint16_t offset = 0;
+    if (mapsize > framesize)
+    {
+        if (pos > framesize / 2)
+        {
+            if (pos < mapsize - (framesize / 2))
+            {
+                offset = pos - (framesize / 2);
+            }
+            else
+            {
+                offset = mapsize - framesize;
+            }
+        }
+    }
+    return offset;
+}
+
+
+
+extern void turn_over(struct World * world, char action)
+{
+    if (1 == world->interactive)
+    {
+        FILE * file = fopen("record", "a");
+        fputc(action, file);
+        fclose(file);
+    }
+    world->turn++;
+    rrand(1, world->seed * world->turn);
+    struct Monster * monster;
+    for (monster = world->monster;
+         monster != 0;
+         monster = monster->map_obj.next)
+    {
+        move_monster(world, monster);
+    }
+}
+
+
+
+extern void save_game(struct World * world)
+{
+    FILE * file = fopen("savefile", "w");
+    write_uint32_bigendian(world->seed, file);
+    write_uint32_bigendian(world->turn, file);
+    write_uint16_bigendian(world->player->pos.y + 1, file);
+    write_uint16_bigendian(world->player->pos.x + 1, file);
+    fputc(world->player->hitpoints, file);
+    write_map_objects (world->monster, file, write_map_objects_monsterdata);
+    write_map_objects (world->item, file, NULL);
+    fclose(file);
+}
+
+
+
+extern void toggle_window(struct WinMeta * win_meta, struct Win * win)
+{
+    if (0 != win->frame.curses_win)
+    {
+        suspend_win(win_meta, win);
+    }
+    else
+    {
+        append_win(win_meta, win);
+    }
+}
+
+
+
+extern void scroll_pad(struct WinMeta * win_meta, char dir)
+{
+    if      ('+' == dir)
+    {
+        reset_pad_offset(win_meta, win_meta->pad_offset + 1);
+    }
+    else if ('-' == dir)
+    {
+        reset_pad_offset(win_meta, win_meta->pad_offset - 1);
+    }
+}
+
+
+
+extern void growshrink_active_window(struct WinMeta * win_meta, char change)
+{
+    if (0 != win_meta->active)
+    {
+        struct yx_uint16 size = win_meta->active->frame.size;
+        if      (change == '-')
+        {
+            size.y--;
+        }
+        else if (change == '+')
+        {
+            size.y++;
+        }
+        else if (change == '_')
+        {
+            size.x--;
+        }
+        else if (change == '*')
+        {
+            size.x++;
+        }
+        resize_active_win (win_meta, size);
+    }
+}
+
+
+
+extern struct yx_uint16 find_passable_pos(struct Map * map)
+{
+    struct yx_uint16 pos;
+    for (pos.y = pos.x = 0; 0 == is_passable(map, pos);)
+    {
+        pos.y = rrand(0, 0) % map->size.y;
+        pos.x = rrand(0, 0) % map->size.x;
+    }
+    return pos;
+}
+
+
+
+extern unsigned char meta_keys(int key, struct World * world,
+                               struct WinMeta * win_meta,
+                               struct Win * win_keys,
+                               struct Win * win_map,
+                               struct Win * win_info,
+                               struct Win * win_log)
+{
+    if (key == get_action_key(world->keybindings, "quit"))
+    {
+        return 1;
+    }
+    else if (key == get_action_key(world->keybindings, "scroll pad right"))
+    {
+        scroll_pad (win_meta, '+');
+    }
+    else if (key == get_action_key(world->keybindings, "scroll pad left"))
+    {
+        scroll_pad (win_meta, '-');
+    }
+    else if (key == get_action_key(world->keybindings, "toggle keys window"))
+    {
+        toggle_window(win_meta, win_keys);
+    }
+    else if (key == get_action_key(world->keybindings, "toggle map window"))
+    {
+        toggle_window(win_meta, win_map);
+    }
+    else if (key == get_action_key(world->keybindings, "toggle info window"))
+    {
+        toggle_window(win_meta, win_info);
+    }
+    else if (key == get_action_key(world->keybindings, "toggle log window"))
+    {
+        toggle_window(win_meta, win_log);
+    }
+    else if (key == get_action_key(world->keybindings, "cycle forwards"))
+    {
+        cycle_active_win(win_meta, 'n');
+    }
+    else if (key == get_action_key(world->keybindings, "cycle backwards"))
+    {
+        cycle_active_win(win_meta, 'p');
+    }
+    else if (key == get_action_key(world->keybindings, "shift forwards"))
+    {
+        shift_active_win(win_meta, 'f');
+    }
+    else if (key == get_action_key(world->keybindings, "shift backwards"))
+    {
+        shift_active_win(win_meta, 'b');
+    }
+    else if (key == get_action_key(world->keybindings, "grow horizontally"))
+    {
+        growshrink_active_window(win_meta, '*');
+    }
+    else if (key == get_action_key(world->keybindings, "shrink horizontally"))
+    {
+        growshrink_active_window(win_meta, '_');
+    }
+    else if (key == get_action_key(world->keybindings, "grow vertically"))
+    {
+        growshrink_active_window(win_meta, '+');
+    }
+    else if (key == get_action_key(world->keybindings, "shrink vertically"))
+    {
+        growshrink_active_window(win_meta, '-');
+    }
+    else if (key == get_action_key(world->keybindings, "save keys"))
+    {
+        save_keybindings(world);
+    }
+    else if (key == get_action_key(world->keybindings, "keys nav up"))
+    {
+        keyswin_move_selection (world, 'u');
+    }
+    else if (key == get_action_key(world->keybindings, "keys nav down"))
+    {
+        keyswin_move_selection (world, 'd');
+    }
+    else if (key == get_action_key(world->keybindings, "keys mod"))
+    {
+        keyswin_mod_key (world, win_meta);
+    }
+    else if (key == get_action_key(world->keybindings, "map up"))
+    {
+        map_scroll (world->map, NORTH, win_map->frame.size);
+     }
+    else if (key == get_action_key(world->keybindings, "map down"))
+    {
+        map_scroll (world->map, SOUTH, win_map->frame.size);
+    }
+    else if (key == get_action_key(world->keybindings, "map right"))
+    {
+        map_scroll (world->map, EAST, win_map->frame.size);
+    }
+    else if (key == get_action_key(world->keybindings, "map left"))
+    {
+        map_scroll (world->map, WEST, win_map->frame.size);
+    }
+    else if (key == get_action_key(world->keybindings, "map center player"))
+    {
+        map_center_player (world->map, world->player, win_map->frame.size);
+    }
+    return 0;
+}
diff --git a/src/misc.h b/src/misc.h
index b3b9a13..6257b12 100644
--- a/src/misc.h
+++ b/src/misc.h
@@ -1,26 +1,113 @@
+/* misc.h
+ *
+ * Miscellaneous routines that have not yet found a proper parent module. Having
+ * LOTS of stuff in here is a sure sign that better modularization is in order.
+ */
+
 #ifndef MISC_H
 #define MISC_H
 
-#include <stdint.h>
-#include <stdio.h>
-#include "yx_uint16.h"
 
+
+#include <stdint.h>    /* for uint16_t, uint32_t */
+#include <stdio.h>     /* for FILE typedef */
+#include "yx_uint16.h" /* for yx_uint16 coordinates */
 struct World;
 struct WinMeta;
 struct Win;
 struct Map;
 
-extern void exit_game(struct World *, struct Map *);
-extern void textfile_sizes (FILE *, uint16_t *, uint16_t *);
-extern uint16_t rrand(char, uint32_t);
-extern void update_log (struct World *, char *);
-extern uint16_t center_offset (uint16_t, uint16_t, uint16_t);
-extern void turn_over (struct World *, char);
-extern void save_game(struct World *);
-extern void toggle_window (struct WinMeta *, struct Win *);
-extern void scroll_pad (struct WinMeta *, char);
-extern void growshrink_active_window (struct WinMeta *, char);
-extern struct yx_uint16 find_passable_pos (struct Map *);
-extern unsigned char meta_keys(int, struct World *, struct WinMeta *, struct Win *, struct Win *, struct Win *, struct Win *);
+
+
+/* Reset terminal (end ncurses), clean up memory and exit. */
+extern void exit_game(struct World * world, struct Map * map);
+
+
+
+/* Learn from "file" the largest line length (pointed to by "linemax_p") and
+ * (pointed to by "n_lines_p" if it is not set to NULL) the number of lines.
+ */
+extern void textfile_sizes(FILE * file, uint16_t * linemax_p,
+                           uint16_t * n_lines_p);
+
+
+
+/* Pseudo-random number generator using a Linear Congruential Generator
+ * algorithm with some proven constants. Used instead of rand() to ensure
+ * portable pseudo-randomness predictability. Set "use_seed" to !0 to seed it
+ * with "new_seed".
+ *
+ * TODO: Write a wrapper for all non-seeding uses that demands no input.
+ */
+extern uint16_t rrand(char use_seed, uint32_t new_seed);
+
+
+
+/* Update game log by appending "text", or by appending a "." if "text" is the
+ * same as the last one passed.
+ */
+extern void update_log(struct World * world, char * text);
+
+
+
+/* Return the offset necessary to center "map" on position "pos" in a frame of
+ * "framesize.
+ */
+extern uint16_t center_offset(uint16_t pos, uint16_t mapsize,
+                              uint16_t framesize);
+
+
+
+/* Record last player "action" in game record file "record, increment the game
+ * turn and trigger enemy movement.
+ */
+extern void turn_over(struct World * world, char action);
+
+
+
+/* Save current game data to file "savefile". */
+extern void save_game(struct World * world);
+
+
+
+/* Toggle display of a window "win". */
+extern void toggle_window(struct WinMeta * win_meta, struct Win * win);
+
+
+
+/* Try to scroll virtual screen left ("dir" = "-") or right ("dir" = "+"),
+ * subject to the limitations provided by the window manager via
+ * reset_pad_offset().
+ */
+extern void scroll_pad(struct WinMeta * win_meta, char dir);
+
+
+
+/* Try to grow or shrink the active window horizontally ("change" = "*"/"_") or
+ * vertically ("change = "+"/"-") by one cell size, subject to the limitations
+ * provided by the window manager via resize_active_win().
+ */
+extern void growshrink_active_window(struct WinMeta * win_meta, char change);
+
+
+
+/* Return a random position on the map "map" that is passable (as determined by
+ * is_passable().
+ */
+extern struct yx_uint16 find_passable_pos(struct Map * map);
+
+
+
+/* Call some meta game / window management actions dependent on key. If the
+ * "quit" action is called, return 1 only instead of doing anything directly.
+ */
+extern unsigned char meta_keys(int key, struct World * world,
+                               struct WinMeta * win_meta,
+                               struct Win * win_keys,
+                               struct Win * win_map,
+                               struct Win * win_info,
+                               struct Win * win_log);
+
+
 
 #endif