The Battle for Wesnoth  1.17.0-dev
lua_unit.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2009 - 2021
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  */
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  */
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  */
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 }
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:192
unit & operator*() const
Definition: lua_unit.hpp:108
bool on_map() const
Definition: lua_unit.hpp:100
static void setmetatable(lua_State *L)
Definition: lua_unit.cpp:208
This class represents a single unit of a specific type.
Definition: unit.hpp:121
~lua_unit()
Definition: lua_unit.cpp:45
friend lua_unit * luaW_pushlocalunit(lua_State *L, unit &u)
Pushes a private unit on the stack.
Definition: lua_unit.cpp:213
friend lua_unit * luaW_pushunit(lua_State *L, Args... args)
Definition: lua_unit.hpp:116
lua_unit(std::size_t u)
Definition: lua_unit.hpp:94
std::shared_ptr< unit > unit_ptr
Definition: ptr.hpp:26
lua_unit & operator=(const lua_unit &)=delete
unit * c_ptr
Definition: lua_unit.hpp:85
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:200
std::string register_metatables(lua_State *L)
Definition: lua_color.cpp:136
int on_recall_list() const
Definition: lua_unit.hpp:102
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:143
lua_unit(unit_ptr u)
Definition: lua_unit.hpp:95
Encapsulates the map of the game.
Definition: location.hpp:38
std::size_t uid
Definition: lua_unit.hpp:82
lua_unit * luaW_pushlocalunit(lua_State *L, unit &u)
Pushes a private unit on the stack.
Definition: lua_unit.cpp:213
Storage for a unit, either owned by the Lua code (ptr != 0), a local variable unit (c_ptr != 0)...
Definition: lua_unit.hpp:80
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:153
int side
Definition: lua_unit.hpp:84
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:163
static map_location::DIRECTION s
unit * operator->() const
Definition: lua_unit.hpp:107
lua_unit(unit &u)
Definition: lua_unit.hpp:97
unit_ptr get_shared() const
Definition: lua_unit.cpp:60
lua_unit(const lua_unit &)=delete
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:72
lua_unit(int s, std::size_t u)
Definition: lua_unit.hpp:96
bool put_map(const map_location &loc)
Definition: lua_unit.cpp:75
unit_ptr ptr
Definition: lua_unit.hpp:83
bool luaW_isunit(lua_State *, int index)
Test if a Lua value is a unit.
Definition: lua_unit.cpp:114
void clear_ref()
Definition: lua_unit.hpp:110
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:184