mirror of
https://gitea.wildfiregames.com/0ad/0ad
synced 2026-06-16 21:34:08 -07:00
cdd75deafb
XMB format is bumped to 4, invalidating all cached files. The differences are: - element/attribute names are stored after the elements themselves, and not before. This allows writing XMB data in one pass instead of two. - names themselves becomes offsets (instead of arbitrary integers), making getting the string from the int name much more efficient. XMBFile is renamed to XMBData to clarify that it does not, in fact, refer to a file on disk. XMBData::GetElementString is also changed to return a const char*, thus not creating an std::string. A string_view version is added where convenient. The XML->XMB and JS->XMB conversion functions and the corresponding storage are moved to `ps/XMB`, since that format doesn't particularly relate to XML. CXeromyces becomes lighter and more focused as a result. The XML->XMB conversion also benefits from the above streamlining. Note that in a few cases, string_view gets printed to CLogger via data(), which is generally not legal, but we know that the strings are null-terminated here. Our libfmt (version 4) doesn't support string_view, that would be v5. Differential Revision: https://code.wildfiregames.com/D3909 This was SVN commit r25375.
295 lines
8.9 KiB
C++
295 lines
8.9 KiB
C++
/* Copyright (C) 2021 Wildfire Games.
|
|
* This file is part of 0 A.D.
|
|
*
|
|
* 0 A.D. is free software: you can redistribute it and/or modify
|
|
* it under the terms of the GNU General Public License as published by
|
|
* the Free Software Foundation, either version 2 of the License, or
|
|
* (at your option) any later version.
|
|
*
|
|
* 0 A.D. is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License
|
|
* along with 0 A.D. If not, see <http://www.gnu.org/licenses/>.
|
|
*/
|
|
|
|
#ifndef INCLUDED_PARAMNODE
|
|
#define INCLUDED_PARAMNODE
|
|
|
|
#include "lib/file/vfs/vfs_path.h"
|
|
#include "maths/Fixed.h"
|
|
#include "ps/CStrIntern.h"
|
|
#include "ps/Errors.h"
|
|
#include "scriptinterface/ScriptTypes.h"
|
|
|
|
#include <map>
|
|
#include <string>
|
|
|
|
class XMBData;
|
|
class XMBElement;
|
|
|
|
class ScriptRequest;
|
|
|
|
/**
|
|
* An entity initialisation parameter node.
|
|
* Each node has a text value, plus a number of named child nodes (in a tree structure).
|
|
* Child nodes are unordered, and there cannot be more than one with the same name.
|
|
* Nodes are immutable.
|
|
*
|
|
* Nodes can be initialised from XML files. Child elements are mapped onto child nodes.
|
|
* Attributes are mapped onto child nodes with names prefixed by "@"
|
|
* (e.g. the XML <code><a b="c"><d/></a></code> is loaded as a node with two
|
|
* child nodes, one called "@b" and one called "d").
|
|
*
|
|
* They can also be initialised from @em multiple XML files,
|
|
* which is used by ICmpTemplateManager for entity template inheritance.
|
|
* Loading one XML file like:
|
|
* @code
|
|
* <Entity>
|
|
* <Example1>
|
|
* <A attr="value">text</A>
|
|
* </Example1>
|
|
* <Example2>
|
|
* <B/>
|
|
* </Example2>
|
|
* <Example3>
|
|
* <C/>
|
|
* </Example3>
|
|
* <Example4 datatype="tokens">
|
|
* one two three
|
|
* </Example4>
|
|
* <Example5>
|
|
* <E/>
|
|
* <F>
|
|
* <I>test</I>
|
|
* </F>
|
|
* <H>
|
|
* <J>example</J>
|
|
* </H>
|
|
* </Example5>
|
|
* </Entity>
|
|
* @endcode
|
|
* then a second like:
|
|
* @code
|
|
* <Entity>
|
|
* <Example1>
|
|
* <A>example</A> <!-- replace the content of the old A element -->
|
|
* <D>new</D> <!-- add a new child to the old Example1 element -->
|
|
* </Example1>
|
|
* <Example2 disable=""/> <!-- delete the old Example2 element -->
|
|
* <Example3 replace=""> <!-- replace all the old children of the Example3 element -->
|
|
* <D>new</D>
|
|
* </Example3>
|
|
* <Example4 datatype="tokens"> <!-- treat as space-separated lists of tokens to merge -->
|
|
* four <!-- add a token to the parent's set -->
|
|
* -two <!-- remove a token from the parent's set -->
|
|
* </Example4>
|
|
* <Example5 filtered=""> <!-- drop all children of this node that are not in this file -->
|
|
* <F merge=""> <!-- only add this element if it is also present in the parent -->
|
|
* <K>example</K> <!-- if F is present merge its children normally -->
|
|
* </F>
|
|
* <G merge=""/> <!-- keep the G element of the parent if it exists -->
|
|
* <H>
|
|
* <J>text</J>
|
|
* </H>
|
|
* </Example5>
|
|
* </Entity>
|
|
* @endcode
|
|
* is equivalent to loading a single file like:
|
|
* @code
|
|
* <Entity>
|
|
* <Example1>
|
|
* <A attr="value">example</A>
|
|
* <D>new</D>
|
|
* </Example1>
|
|
* <Example3>
|
|
* <D>new</D>
|
|
* </Example3>
|
|
* <Example4>
|
|
* one three four
|
|
* </Example4>
|
|
* <Example5>
|
|
* <F>
|
|
* <I>test</I>
|
|
* <K>example</K>
|
|
* </F>
|
|
* <H>
|
|
* <J>text</J>
|
|
* </H>
|
|
* </Example5>
|
|
* </Entity>
|
|
* @endcode
|
|
*
|
|
* Parameter nodes can be translated to JavaScript objects. The previous example will become the object:
|
|
* @code
|
|
* { "Entity": {
|
|
* "Example1": {
|
|
* "A": { "@attr": "value", "_string": "example" },
|
|
* "D": "new"
|
|
* },
|
|
* "Example3": {
|
|
* "D": "new"
|
|
* },
|
|
* "Example4": { "@datatype": "tokens", "_string": "one three four" },
|
|
* "Example5": {
|
|
* "F": {
|
|
* "I": "test",
|
|
* "K": "example"
|
|
* },
|
|
* "H": {
|
|
* "J": "text"
|
|
* }
|
|
* }
|
|
* }
|
|
* }
|
|
* @endcode
|
|
* (Note the special @c _string for the hopefully-rare cases where a node contains both child nodes and text.)
|
|
*/
|
|
class CParamNode
|
|
{
|
|
public:
|
|
typedef std::map<std::string, CParamNode> ChildrenMap;
|
|
|
|
/**
|
|
* Constructs a new, empty node.
|
|
*/
|
|
CParamNode(bool isOk = true);
|
|
|
|
/**
|
|
* Loads the XML data specified by @a file into the node @a ret.
|
|
* Any existing data in @a ret will be overwritten or else kept, so this
|
|
* can be called multiple times to build up a node from multiple inputs.
|
|
*
|
|
* @param sourceIdentifier Optional; string you can pass along to indicate the source of
|
|
* the data getting loaded. Used for output to log messages if an error occurs.
|
|
*/
|
|
static void LoadXML(CParamNode& ret, const XMBData& xmb, const wchar_t* sourceIdentifier = NULL);
|
|
|
|
/**
|
|
* Loads the XML data specified by @a path into the node @a ret.
|
|
* Any existing data in @a ret will be overwritten or else kept, so this
|
|
* can be called multiple times to build up a node from multiple inputs.
|
|
*/
|
|
static void LoadXML(CParamNode& ret, const VfsPath& path, const std::string& validatorName);
|
|
|
|
/**
|
|
* See LoadXML, but parses the XML string @a xml.
|
|
* @return error code if parsing failed, else @c PSRETURN_OK
|
|
*
|
|
* @param sourceIdentifier Optional; string you can pass along to indicate the source of
|
|
* the data getting loaded. Used for output to log messages if an error occurs.
|
|
*/
|
|
static PSRETURN LoadXMLString(CParamNode& ret, const char* xml, const wchar_t* sourceIdentifier = NULL);
|
|
|
|
/**
|
|
* Returns the (unique) child node with the given name, or a node with IsOk() == false if there is none.
|
|
*/
|
|
const CParamNode& GetChild(const char* name) const;
|
|
// (Children are returned as const in order to allow future optimisations, where we assume
|
|
// a node is always modified explicitly and not indirectly via its children, e.g. to cache JS::Values)
|
|
|
|
/**
|
|
* Returns true if this is a valid CParamNode, false if it represents a non-existent node
|
|
*/
|
|
bool IsOk() const;
|
|
|
|
/**
|
|
* Returns the content of this node as a wstring
|
|
*/
|
|
const std::wstring ToWString() const;
|
|
|
|
/**
|
|
* Returns the content of this node as an UTF8 string
|
|
*/
|
|
const std::string& ToString() const;
|
|
|
|
/**
|
|
* Returns the content of this node as an internalized 8-bit string. Should only be used for
|
|
* predictably small and frequently-used strings.
|
|
*/
|
|
const CStrIntern ToUTF8Intern() const;
|
|
|
|
/**
|
|
* Parses the content of this node as an integer
|
|
*/
|
|
int ToInt() const;
|
|
|
|
/**
|
|
* Parses the content of this node as a fixed-point number
|
|
*/
|
|
fixed ToFixed() const;
|
|
|
|
/**
|
|
* Parses the content of this node as a floating-point number
|
|
*/
|
|
float ToFloat() const;
|
|
|
|
/**
|
|
* Parses the content of this node as a boolean ("true" == true, anything else == false)
|
|
*/
|
|
bool ToBool() const;
|
|
|
|
/**
|
|
* Returns the content of this node and its children as an XML string
|
|
*/
|
|
std::string ToXMLString() const;
|
|
|
|
/**
|
|
* Write the content of this node and its children as an XML string, to the stream
|
|
*/
|
|
void ToXMLString(std::ostream& strm) const;
|
|
|
|
/**
|
|
* Returns a JS::Value representation of this node and its children.
|
|
* If @p cacheValue is true, then the same JS::Value will be returned each time
|
|
* this is called (regardless of whether you passed the same @p cx - be careful
|
|
* to only use the cache in one context).
|
|
* When caching, the lifetime of @p cx must be longer than the lifetime of this node.
|
|
* The cache will be reset if *this* node is modified (e.g. by LoadXML),
|
|
* but *not* if any child nodes are modified (so don't do that).
|
|
*/
|
|
void ToJSVal(const ScriptRequest& rq, bool cacheValue, JS::MutableHandleValue ret) const;
|
|
|
|
/**
|
|
* Returns the names/nodes of the children of this node, ordered by name
|
|
*/
|
|
const ChildrenMap& GetChildren() const;
|
|
|
|
/**
|
|
* Escapes a string so that it is well-formed XML content/attribute text.
|
|
* (Replaces "&" with "&" etc)
|
|
*/
|
|
static std::string EscapeXMLString(const std::string& str);
|
|
|
|
std::string m_Name;
|
|
u32 m_Index;
|
|
|
|
private:
|
|
|
|
/**
|
|
* Overlays the specified data onto this node. See class documentation for the concept and examples.
|
|
*
|
|
* @param xmb Representation of the XMB file containing an element with the data to apply.
|
|
* @param element Element inside the specified @p xmb file containing the data to apply.
|
|
* @param sourceIdentifier Optional; string you can pass along to indicate the source of
|
|
* the data getting applied. Used for output to log messages if an error occurs.
|
|
*/
|
|
void ApplyLayer(const XMBData& xmb, const XMBElement& element, const wchar_t* sourceIdentifier = NULL);
|
|
|
|
void ResetScriptVal();
|
|
|
|
void ConstructJSVal(const ScriptRequest& rq, JS::MutableHandleValue ret) const;
|
|
|
|
std::string m_Value;
|
|
ChildrenMap m_Childs;
|
|
bool m_IsOk;
|
|
|
|
/**
|
|
* Caches the ToJSVal script representation of this node.
|
|
*/
|
|
mutable std::shared_ptr<JS::PersistentRootedValue> m_ScriptVal;
|
|
};
|
|
|
|
#endif // INCLUDED_PARAMNODE
|