From 56387cfab191552caa28b948c0be36c03287cbff Mon Sep 17 00:00:00 2001
From: Sveinung Kvilhaugsvik <sveinung84@users.sourceforge.net>
Date: Wed, 3 Feb 2021 11:12:40 +0100
Subject: [PATCH] README.actions: improve Lua example 1.

The action logger example would print potentially wrong ownership
information about unit stack targets and tile extras targets. Make it write
text for each target kind separately. Eliminate owner information for unit
stacks since a unit stack can have units from more than one nation. Correct
it for tile extras targeted actions.

Add action target kind specific information too now that it is possible:
Cities get name and id. Individual units gets unit type and id. Unit stacks
gets coordinates. Tiles and tile extras gets coordinates.

Improve the wording of the actor unit text too.

See osdn #41451
---
 doc/README.actions | 54 +++++++++++++++++++++++++++++++++++-----------
 1 file changed, 41 insertions(+), 13 deletions(-)

diff --git a/doc/README.actions b/doc/README.actions
index dc8c83979b..d93255a6b8 100644
--- a/doc/README.actions
+++ b/doc/README.actions
@@ -121,26 +121,54 @@ show to players use name_translation().
 Example 1
 =========
 The following Lua code will log all actions done by any unit to a city, to
-another unit, to a unit stack, to a tile or to itself:
-
-function action_started_callback(action, actor, target)
-  local target_owner
-  if target == nil then
-    target_owner = "it self"
-  elseif target.owner == nil then
-    target_owner = "unowned"
-  else
-    target_owner = target.owner.nation:plural_translation()
+another unit, to a unit stack, to a tile, to a tile's extras or to itself:
+
+-- Returns a function that describes a tile target
+function tile_desc_func_gen(kind, owner_getter)
+  return function (target)
+    local owner
+    if owner_getter(target) == nil then
+      owner = _("unowned")
+    else
+      owner = owner_getter(target).nation:name_translation()
+    end
+    return _("%s %s (%d, %d)"):format(owner, kind, target.x, target.y)
   end
+end
 
+-- Describe the target based on its kind
+target_describer = {
+  ["individual cities"] = function (target)
+    return _("%s city %s (id: %d)"):format(
+        target.owner.nation:name_translation(), target.name, target.id)
+  end,
+  ["individual units"] = function (target)
+    return _("%s %s (id: %d)"):format(
+      target.owner.nation:name_translation(),
+      target.utype:name_translation(), target.id)
+  end,
+  ["unit stacks"] = function (target)
+    return _("unit stack at (%d, %d)"):format(target.x, target.y)
+  end,
+  ["tiles"] = tile_desc_func_gen("tile", function (target)
+    return target.owner
+  end),
+  ["tile extras"] = tile_desc_func_gen("tile extras", function (target)
+    return target:extra_owner(Nil)
+  end),
+  ["itself"] = function (target) return "it self" end,
+}
+
+-- Log all performed actions
+function action_started_callback(action, actor, target)
   log.normal(_("%d: %s (rule name: %s) performed by %s %s (id: %d) on %s"),
              game.current_turn(),
              action:name_translation(),
              action:rule_name(),
-             actor.owner.nation:plural_translation(),
-             actor.utype:rule_name(),
+             actor.owner.nation:name_translation(),
+             actor.utype:name_translation(),
              actor.id,
-             target_owner)
+             target_describer[action:target_kind()](target))
 end
 
 signal.connect("action_started_unit_city", "action_started_callback")
-- 
2.20.1