The Battle for Wesnoth  1.19.0-dev
lua_unit.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2009 - 2024
3  by Guillaume Melquiond <guillaume.melquiond@gmail.com>
4  Part of the Battle for Wesnoth Project https://www.wesnoth.org/
5 
6  This program is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License as published by
8  the Free Software Foundation; either version 2 of the License, or
9  (at your option) any later version.
10  This program is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY.
12 
13  See the COPYING file for more details.
14 */
15 
16 #pragma once
17 
18 #include <cstddef>
19 #include <string>
20 #include "scripting/lua_common.hpp"
21 #include "units/ptr.hpp"
22 
23 struct lua_State;
24 class lua_unit;
25 struct map_location;
26 
27 /**
28  * Test if a Lua value is a unit
29  */
30 bool luaW_isunit(lua_State *, int index);
31 
32 /**
33  * Converts a Lua value to a unit pointer.
34  */
35 unit* luaW_tounit(lua_State *L, int index, bool only_on_map = false);
36 
37 /**
38  * Converts a Lua value to a unit pointer.
39  */
40 unit& luaW_checkunit(lua_State *L, int index, bool only_on_map = false);
41 
42 /**
43  * Pushes a private unit on the stack.
44  */
45 lua_unit* luaW_pushlocalunit(lua_State *L, unit& u);
46 
47 /**
48  * Similar to luaW_tounit but returns a unit_ptr; use this instead of
49  * luaW_tounit when using an api that needs unit_ptr.
50  */
51 unit_ptr luaW_tounit_ptr(lua_State *L, int index, bool only_on_map);
52 
53 /**
54  * Similar to luaW_checkunit but returns a unit_ptr; use this instead of
55  * luaW_checkunit when using an api that needs unit_ptr.
56  */
57 unit_ptr luaW_checkunit_ptr(lua_State *L, int index, bool only_on_map);
58 
59 /**
60  * Similar to luaW_tounit but returns a lua_unit; use this if you need
61  * to handle map and recall units differently, for example.
62  *
63  * Note that this only returns null if the element on the stack was not a unit,
64  * so it may be an invalid unit.
65  */
66 lua_unit* luaW_tounit_ref(lua_State *L, int index);
67 
68 /**
69  * Similar to luaW_checkunit but returns a lua_unit; use this if you need
70  * to handle map and recall units differently, for example.
71  */
72 lua_unit* luaW_checkunit_ref(lua_State *L, int index);
73 
74 
75 /**
76  * Storage for a unit, either owned by the Lua code (#ptr != 0), a
77  * local variable unit (c_ptr != 0), on a recall list (#side != 0), or on the map.
78  * Shared units are represented by their underlying ID (#uid).
79  */
80 class lua_unit
81 {
82  std::size_t uid;
84  int side;
86  lua_unit(const lua_unit&) = delete;
87  lua_unit& operator=(const lua_unit&) = delete;
88 
89  template<typename... Args>
90  friend lua_unit* luaW_pushunit(lua_State *L, Args... args);
91  friend lua_unit* luaW_pushlocalunit(lua_State *L, unit& u);
92  static void setmetatable(lua_State *L);
93 public:
94  lua_unit(std::size_t u): uid(u), ptr(), side(0), c_ptr() {}
95  lua_unit(unit_ptr u): uid(0), ptr(u), side(0), c_ptr() {}
96  lua_unit(int s, std::size_t u): uid(u), ptr(), side(s), c_ptr() {}
97  lua_unit(unit& u): uid(0), ptr(), side(0), c_ptr(&u) {}
98  ~lua_unit();
99 
100  bool on_map() const { return !ptr && side == 0; }
101  /** @return If this unit is on any side's recall list, the number of that side (1-based). Otherwise, return 0. */
102  int on_recall_list() const { return side; }
103 
104  unit* get() const;
105  unit_ptr get_shared() const;
106 
107  unit* operator->() const {return get();}
108  unit& operator*() const {return *get();}
109 
110  void clear_ref() { uid = 0; ptr = unit_ptr(); side = 0; c_ptr = nullptr; }
111  // Clobbers loc
112  bool put_map(const map_location &loc);
113 };
114 
115 template<typename... Args>
116 inline lua_unit* luaW_pushunit(lua_State *L, Args... args) {
117  lua_unit* lu = new(L) lua_unit(args...);
119  return lu;
120 }
121 
122 namespace lua_units {
123  std::string register_metatables(lua_State *L);
124 }
Storage for a unit, either owned by the Lua code (ptr != 0), a local variable unit (c_ptr !...
Definition: lua_unit.hpp:81
lua_unit(unit_ptr u)
Definition: lua_unit.hpp:95
unit_ptr ptr
Definition: lua_unit.hpp:83
lua_unit & operator=(const lua_unit &)=delete
unit * operator->() const
Definition: lua_unit.hpp:107
void clear_ref()
Definition: lua_unit.hpp:110
int side
Definition: lua_unit.hpp:84
lua_unit(int s, std::size_t u)
Definition: lua_unit.hpp:96
bool on_map() const
Definition: lua_unit.hpp:100
unit * c_ptr
Definition: lua_unit.hpp:85
friend lua_unit * luaW_pushunit(lua_State *L, Args... args)
Definition: lua_unit.hpp:116
static void setmetatable(lua_State *L)
Definition: lua_unit.cpp:205
std::size_t uid
Definition: lua_unit.hpp:82
unit & operator*() const
Definition: lua_unit.hpp:108
~lua_unit()
Definition: lua_unit.cpp:42
bool put_map(const map_location &loc)
Definition: lua_unit.cpp:72
lua_unit(unit &u)
Definition: lua_unit.hpp:97
int on_recall_list() const
Definition: lua_unit.hpp:102
friend lua_unit * luaW_pushlocalunit(lua_State *L, unit &u)
Pushes a private unit on the stack.
Definition: lua_unit.cpp:210
unit_ptr get_shared() const
Definition: lua_unit.cpp:57
lua_unit(std::size_t u)
Definition: lua_unit.hpp:94
unit * get() const
Definition: lua_unit.cpp:46
lua_unit(const lua_unit &)=delete
This class represents a single unit of a specific type.
Definition: unit.hpp:133
lua_unit * luaW_checkunit_ref(lua_State *L, int index)
Similar to luaW_checkunit but returns a lua_unit; use this if you need to handle map and recall units...
Definition: lua_unit.cpp:197
unit * luaW_tounit(lua_State *L, int index, bool only_on_map=false)
Converts a Lua value to a unit pointer.
Definition: lua_unit.cpp:140
lua_unit * luaW_tounit_ref(lua_State *L, int index)
Similar to luaW_tounit but returns a lua_unit; use this if you need to handle map and recall units di...
Definition: lua_unit.cpp:160
lua_unit * luaW_pushunit(lua_State *L, Args... args)
Definition: lua_unit.hpp:116
unit & luaW_checkunit(lua_State *L, int index, bool only_on_map=false)
Converts a Lua value to a unit pointer.
Definition: lua_unit.cpp:189
bool luaW_isunit(lua_State *, int index)
Test if a Lua value is a unit.
Definition: lua_unit.cpp:111
unit_ptr luaW_checkunit_ptr(lua_State *L, int index, bool only_on_map)
Similar to luaW_checkunit but returns a unit_ptr; use this instead of luaW_checkunit when using an ap...
Definition: lua_unit.cpp:181
unit_ptr luaW_tounit_ptr(lua_State *L, int index, bool only_on_map)
Similar to luaW_tounit but returns a unit_ptr; use this instead of luaW_tounit when using an api that...
Definition: lua_unit.cpp:150
lua_unit * luaW_pushlocalunit(lua_State *L, unit &u)
Pushes a private unit on the stack.
Definition: lua_unit.cpp:210
std::string register_metatables(lua_State *L)
Definition: lua_unit.cpp:648
std::size_t index(const std::string &str, const std::size_t index)
Codepoint index corresponding to the nth character in a UTF-8 string.
Definition: unicode.cpp:70
std::shared_ptr< unit > unit_ptr
Definition: ptr.hpp:26
Encapsulates the map of the game.
Definition: location.hpp:38
static map_location::DIRECTION s