An object that represents where a GameObject or a range of GameObjects exists in the Engine. More...

#include <Path.h>

Classes
class	iterator
	iterator member class for Path. More...

Public Member Functions
	Path (std::string pathString)
	constructs a Path by parsing a string
	Path (std::string pathString, GameObject &rootObject)
	constructs a Path by parsing a string
	operator Gobj & ()
	implicitly converts a path to a reference to the GameObject it refers to
	operator Gobj * ()
	implicitly converts a path to a pointer to the Gobj it refers to
	operator const Gobj & ()
	implicitly converts a path to a const reference to the GameObject it refers to
auto	begin () const -> iterator
auto	end () const -> iterator
auto	get () const -> Gobj *
auto	operator-> () const -> Gobj *

Private Member Functions
auto	parsePath (const std::string &pathString) -> void
	parses a Path, constructing the linked list of PathNodes, which calculate the range that a Path refers to

Static Private Member Functions
static auto	splitString (const std::string &fullString, const std::string &delimiter) -> std::vector< std::string >
	splits a string into many smaller strings.

Private Attributes
std::shared_ptr< PathNode >	path
	a pointer to the linked list of PathNodes that handles the logic for Path deduction

Detailed Description

template<typename Gobj = GameObject>
class gobj::Path< Gobj >

An object that represents where a GameObject or a range of GameObjects exists in the Engine.

Paths can refer to one or many GameObjects. The path will directly convert into a reference to the GameObject it represents, or the first GameObject in its range, if that the Path refers to multiple GameObjects. Access to multiple GameObjects is done via begin() and end() iterators, referring to the first GameObject in the range, and a "past the end" iterator pointing to NULL, respectively. In the case where the Path refers to a single GameObject, then the range will be of length one. The path name has the following syntax:

base-name: identifies the root of the path. the root can be
- ~: which represents the Entity that owns the main Scene loaded by sys::SceneManager
- ^: which represents the base of the current scene (not currently implemented)
- /: which represents the path is absolute, and refers to all the children of Root.
- .: which represents the path starts relative to a specific GameObject. In this case, the GameObject should be passed as a parameter
zero or more of the following:
- GameObject-name: a sequence of characters that aren't / separators. This represents the nickname of an GameObject, or the type name of the GameObject. If this terminates a Path, then the Path refers to that GameObject only
- dot-dot: .. which refers to the parent of the currently referenced GameObject
- separator: /, which refers to all the children of whatever GameObject is referenced on the left side. If this terminates a Path, then the Path refers to all children of the GameObject(s) on the left of the / If this comes before a dot-dot separator, it does nothing, so it doesn't cancel out the dot-dot operation
One or zero of the following:
- filter: a sequence of characters that start with {, and ends with }, and consists of any number of conditions, each separated by an operator (filter is currently not implemented)
The Path may represent a non-existing path.

Template Parameters

Gobj	The type of GameObject you are searching for. Automatically casts to the proper type, and filters out other types at the end. Defaults to GameObject, with no casts or filters

Examples

A Path behaves much like a file path. A "full path" will start at the Root of the engine, and refer to GameObjects by Name or Nickname. See Path s description for a full explanation and breakdown

This Path get's the System SceneManager. the leading / indicates to start at the Root, and get it's children (remember, Root's children are all the Systems in the Engine)

Following the `/`, `SceneManager` filters the Systems to just SceneManager
auto sceneManager = gobj::Path("/SceneManager");
                     /\    /\            /\
                     /      \             \
   you can put      /        \             \
   `using gobj::Path`    Path is a            Path takes just 
   at the top of the     template type        one parameter 
   file if you don't     but it defaults to   normally;
   want to write         GameObject if you    a string
   gobj all the time     don't specify
                         a type
hlg::Message("SceneManager's UUID is {}", sceneManager->getUUID());

Outputs:

SceneManager's UUID is 15

Here's a reminder of the structure of the Engine for the example. Remember, formatted names (when printed to the Log) are in the form TypeName::Nickname::UUID This example doesn't include every System, Entity, or Component in the Engine or Scene loaded right now, but it lists the things we grab here in this example

Messaging ::::3
OpenGL ::::6
SceneManager ::::15
- Entity ::sceneroot::419
- Entity ::background::426
  - Transform ::::430
  - Background ::::431
  - Entity ::board::436
    - Board ::::441
    - Entity ::player::453
      - Physics :::454
      - Transform ::::455
      - Sprite ::::456
      - Player ::::457
      - Entity ::::721
      - ...
      - Entity ::::809
Editor ::::18
TestRunner ::::227

find a different system, but use the template parameter to get it as a specific System, which lets us to call non-virtual member functions

auto openGL = gobj::Path<sys::OpenGL>("/OpenGL");
sys::OpenGL* pointer = openGL.get();
hlg::Message("window width is: {}", openGL->getWidth());

Outputs:

window width is: 1920

Different starts of Paths

We don't have to start from Root however, we can start at the scene root too

auto background = gobj::Path<Entity>("~/background");

hlg::Message("background Entity from scene root: {}", background->getFormattedName());

Output:

background Entity from scene root: Entity::background::426

Using ~ is the same as getting the root Scene

auto backgroundAbsolute = gobj::Path<Entity>("/SceneManager/sceneroot/background");
hlg::Message("are board and boardAbsolute are the same?: {} {}",
    background.get() == backgroundAbsolute.get(), background == backgroundAbsolute );

Output:

are board and boardAbsolute are the same?: true true

Getting Components

A very common usage for paths is getting components here, background refers to the Entities nickname, and Background refers to the Background Component

auto backgroundComponent = gobj::Path<Component>("~/background/Background");

hlg::Message(" Here's the background components name: {} ", backgroundComponent->getFormattedName());

Output:

Here's the background components name: Background::::431

Just like with systems, if we use Path's template parameter, we can get our GameObject as the class it actually is, and call member functions on it

auto transformComponent = gobj::Path<Transform>("~/background/Transform");
hlg::Message("Using the template parameter can be handy! Transform's scale is: {},{}", 
    transformComponent->scale().x(), transformComponent->scale().y());

Output:

Using the template parameter can be handy! Transform's scale is: 2560,1494

Starting at an arbitrary location

Paths can also start at arbitrary locations, just start with a . and pass in a GameObject to start from. Pass in *this to start from yourself

auto playerComponent = gobj::Path<Player>("./board/player/Player", *background);

hlg::Message("get Player's (starting from background) score = {}", playerComponent->getScore());

Output:

get Player's (starting from background) score = 0

dot-dot

Paths can also go "Up" to get somethings parent: The first .. gets the player Entity, and the second .. gets the board Entity. From there, the / get's the Entities Children, and Board selects the Board Component from among those children

auto boardComponent = gobj::Path<Board>("./../../Board",*playerComponent);

hlg::Message("Path can get somethings parent {}", boardComponent->getFormattedName());

Output:

Path can get somethings parent Board::::441

Ranges

Path can also get a range of objects instead of just one, if you end in a /

auto systems = gobj::Path<System>("/");
for (auto & system : systems)
{
    hlg::Message(" system: {}", system.getFormattedName());
}

Output:

system: Messaging::::3
system: OpenGL::::6
system: Input::::9
system: AudioSystem::::12
system: SceneManager::::15
system: Editor::::18
system: DebugDraw::::271
system: ActionList::::274
system: TestRunner::::277

Careful though, getting all of a Entities children gets both it's child Components, and child Entities.

auto playersChildren = gobj::Path("~/background/board/player/");
for (auto & entityOrComponent : playersChildren)
{
    hlg::Message(" Entity Or Component: {}", entityOrComponent.getFormattedName());
}

Output:

Entity Or Component: Physics::::454
Entity Or Component: Transform::::455
Entity Or Component: Sprite::::456
Entity Or Component: Player::::457
Entity Or Component: Entity::::721
Entity Or Component: Entity::::734
Entity Or Component: Entity::::748
Entity Or Component: Entity::::763
Entity Or Component: Entity::::779
Entity Or Component: Entity::::796
Entity Or Component: Entity::::809

Wow, Aidan that's annoying! Is there any way that I can get Just the Components, or just the Entities?

Why yes, yes there is! If you set the template to a type, it will automatically filter the final range to only GameObjects of that type!

Here it is with Components

auto playersComponents = gobj::Path<Component>("~/background/board/player/");
for (auto & component : playersComponents)
{
    hlg::Message(" Component: {}", component.getFormattedName());
}

Output:

Component: Physics::::454
Component: Transform::::455
Component: Sprite::::456
Component: Player::::457

Here it is with Entities

auto playersEntities = gobj::Path<Entity>("~/background/board/player/");
for (auto & Entity : playersEntities)
{
    hlg::Message(" Entity: {}", Entity.getFormattedName());
}

Output:

Entity: Entity::::721
Entity: Entity::::734
Entity: Entity::::748
Entity: Entity::::763
Entity: Entity::::779
Entity: Entity::::796
Entity: Entity::::809

Exceptions

If a path can't find an GameObject, or you give it GameObjects of the wrong type, It will throw an exception. You can catch the exception, but be careful, it's this means you won't get notified of when the exception happens, unless you check the log. So if you want to catch the exception, I recommend asserting afterwards. Otherwise, if you don't catch the exception, the Debugger should break on it's own when an exception happens.

try 
{
    auto system = gobj::Path("/NonExistingSystem");
}
catch (PathException& e )
{
    hlg::Error("caught exception {}", e.what());
    assert(false && "Path's had an exception")
}

Constructor & Destructor Documentation

◆ Path() [1/2]

template<typename Gobj = GameObject>

gobj::Path< Gobj >::Path ( std::string pathString )

inlineexplicit

constructs a Path by parsing a string

Template Parameters

Gobj	The type of GameObject you are searching for. Automatically casts to the proper type, and filters out other types at the end. Defaults to GameObject, with no casts or filters

Parameters

pathString a string to construct the path from

Todo: when we add scenes in scenes add case to paths

Here is the call graph for this function:

◆ Path() [2/2]

template<typename Gobj = GameObject>

gobj::Path< Gobj >::Path	(	std::string	pathString,
		GameObject &	rootObject )

inline

constructs a Path by parsing a string

Template Parameters

Gobj	The type of GameObject you are searching for. Automatically casts to the proper type, and filters out other types at the end. Defaults to GameObject, with no casts or filters

Parameters

pathString	a string to construct the path from. The string should start with a dot .
rootObject	a reference to the object to start the Path from

Here is the call graph for this function:

Member Function Documentation

◆ begin()

template<typename Gobj = GameObject>

auto gobj::Path< Gobj >::begin ( ) const->iterator

inline

Exceptions

PathException If the path is invalid, and can't find anything (usually throws, but not always)

Returns: iterator to the beginning of the range of Gobjs

Here is the caller graph for this function:

◆ end()

template<typename Gobj = GameObject>

auto gobj::Path< Gobj >::end ( ) const->iterator

inline

Returns: sentinel (past the end) iterator to the range of Gobj s

Here is the caller graph for this function:

◆ get()

template<typename Gobj = GameObject>

auto gobj::Path< Gobj >::get ( ) const->Gobj *

inline

Returns: pointer to the Gobj referred to by the Path, or if the path refers to a range,the Gobj at the beginning of that range

Here is the call graph for this function:

Here is the caller graph for this function:

◆ operator const Gobj &()

template<typename Gobj = GameObject>

gobj::Path< Gobj >::operator const Gobj & ( )

inline

implicitly converts a path to a const reference to the GameObject it refers to

Here is the call graph for this function:

◆ operator Gobj &()

template<typename Gobj = GameObject>

gobj::Path< Gobj >::operator Gobj & ( )

inline

implicitly converts a path to a reference to the GameObject it refers to

Here is the call graph for this function:

◆ operator Gobj *()

template<typename Gobj = GameObject>

gobj::Path< Gobj >::operator Gobj * ( )

inline

implicitly converts a path to a pointer to the Gobj it refers to

Here is the call graph for this function:

◆ operator->()

template<typename Gobj = GameObject>

auto gobj::Path< Gobj >::operator-> ( ) const->Gobj *

inline

Returns: pointer to the Gobj referred to by the Path, or if the path refers to a range,the Gobj at the beginning of that range

Here is the call graph for this function:

◆ parsePath()

template<typename Gobj = GameObject>

auto gobj::Path< Gobj >::parsePath ( const std::string & pathString ) ->void

inlineprivate

parses a Path, constructing the linked list of PathNodes, which calculate the range that a Path refers to

Parameters

pathString string to parse

Here is the call graph for this function:

Here is the caller graph for this function:

◆ splitString()

template<typename Gobj = GameObject>

auto gobj::Path< Gobj >::splitString	(	const std::string &	fullString,
		const std::string &	delimiter )->std::vector< std::string >

inlinestaticprivate

splits a string into many smaller strings.

Used to split path into individual section when parsing

Parameters

fullString	string with delimiters in it
delimiter	sequence of characters to divide fullString by

Returns: a vector of strings that were between delimiters in fullString

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ path

template<typename Gobj = GameObject>

std::shared_ptr<PathNode> gobj::Path< Gobj >::path

private

a pointer to the linked list of PathNodes that handles the logic for Path deduction

The documentation for this class was generated from the following file:

/home/egrazil/sites/Brunot/The House/source/Utility/Path/Path.h

Classes

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Examples

Different starts of Paths

Getting Components

Starting at an arbitrary location

dot-dot

Ranges

Exceptions

Constructor & Destructor Documentation

◆ Path() [1/2]

◆ Path() [2/2]

Member Function Documentation

◆ begin()

◆ end()

◆ get()

◆ operator const Gobj &()

◆ operator Gobj &()

◆ operator Gobj *()

◆ operator->()

◆ parsePath()

◆ splitString()

Member Data Documentation

◆ path