Detailed Description

A class which reads an SDS structure from DRAMA SDS Command argument structures.

This is C++ class which provides an interface to GitArgGetStruct(). It Implements a sub-class of sds::Id which adds operation gitarg::Id::Get , to fetch its value from an SDS structure supplied in an argument structure or a file the name of which has been supplied in the argument structure.

See also: GitArgGetStruct()

#include "gitarg.hh"

Inheritance diagram for drama::gitarg::Id:

Public Member Functions
	Id ()
	Default constructor. More...

	Id (const sds::Id &Id, const std::string &Name="Argument1", const int Position=1, const std::string Default="", const Flags flags=Flags::KeepErr)
	Constructor with the initial value set from an SDS structure or file. More...

virtual	~Id ()
	Destructor. More...

virtual std::string	ActualName () const
	Return the actual name of the file or structure. More...

virtual void	Get (const sds::Id &Id, const std::string &Name="Argument1", const int Position=1, const std::string Default="", const Flags flags=(Flags::KeepErr))
	Get the value of the object from an SDS structure or file. More...

virtual bool	WasReadFromDefault () const
	Indicates if the structure was read from the default. More...

virtual bool	WasReadFromFile () const
	Indicates if the structure was read from a file. More...

Public Member Functions inherited from drama::sds::Id
	Id (const Id &source)=delete
	Copy constructor - deleted. More...

	Id (Id &&source) noexcept
	Move copy constructor. More...

	Id ()
	Default constructor. More...

template<typename ContainerType >
void	AddToArgCmdStruct (const ContainerType &values, const unsigned firstArg=1)
	Insert a set of values from a container into an SDS structure in in the DRAMA Command style. More...

template<typename T >
void	ArrayAccess (ArrayAccessHelper< T > *const data) const
	Access the data of a single dimensional SDS primitive array item of a specified number of elements. More...

template<typename T >
void	ArrayAccess (const unsigned long nitems, sds::ArrayAccessHelper< T > *const data) const
	Access the data of a single dimensional SDS primitive item array of a specified number of elements. More...

template<typename T , class ContainerType >
void	ArrayAccess (ArrayAccessHelper< T > const data, long ndims, ContainerType dims) const
	Access the data of an SDS primitive item array. More...

template<typename T , class ContainerType >
void	ArrayAccess (ArrayAccessHelper< T > const data, ContainerType dims) const
	Access the data of an SDS primitive item array. More...

template<class ContainerType >
Id	Cell (const ContainerType &indicies, bool throwOnNotFound=true) const
	Factory constructor method Constructor that returns a cell of an existing id which must refer to an SDS array. More...

template<class ContainerType >
void	CheckItem (SdsCodeType code, const ContainerType &dims) const
	Check an item has a required structure. More...

virtual void	ClearDelete ()
	Indicate the underlying SDS structure should NOT be deleted when the sds::Id object is destroyed. More...

virtual Id	Copy () const
	Factory constructor method Id Copy constructor. More...

virtual SdsIdType	COut (const bool outlives, bool const free=0, bool const del=0, bool *const readfree=0)
	Return this item as an SdsIdType for return to C code. More...

template<class ContainerType >
Id	CreateChildArray (const std::string &name, const SdsCodeType code, const ContainerType &dims, const std::string &extra="") const
	Factory constructor method Constructor which creates a new child item which is an array. More...

virtual Id	CreateChildItem (const std::string &name, const SdsCodeType code, const std::string &extra="") const
	Factory constructor method which creates a new (non-array) child item. More...

virtual void	Delete ()
	Delete the SDS item. More...

virtual bool	Exists (const std::string &name) const
	Determine if a named item exists in a structure. More...

template<class ContainerType >
void	Export (ContainerType *container) const
	Export the SDS structure into a buffer. More...

template<class ContainerType >
void	ExportDefined (ContainerType *container) const
	Export the SDS structure into a buffer, defining any undefined data. More...

virtual void	Extract ()
	Extract the SDS structure from its parent. More...

virtual void	FillArray (const Id &elem)
	Fill out the contents of this object, which is a structured array. More...

virtual Id	Find (const std::string &name, bool throwOnNotFound=true) const
	Factory constructor method Constructor which returns a reference to a named item. More...

virtual void	Flush ()
	Flush data modified by pointer. More...

template<typename T >
void	Get (const unsigned long length, T const data, unsigned long actlen=nullptr, const unsigned long offset=0) const
	Get data from an SDS item. More...

template<typename T >
void	Get (const std::string &name, T *value) const
	Fetch primitive value from a named component of the structure. More...

template<typename T >
void	Get (T *value) const
	Fetch primitive value from the component. More...

virtual SdsCodeType	GetCode () const
	Return the code of the SDS item. More...

template<class ContainerType >
void	GetDims (ContainerType *dims) const
	Return the dimensions of the SDS item. More...

virtual double	GetDouble () const
	If the SDS item refers to a scalar value, convert it to a double item. More...

virtual std::string	GetExtra () const
	Get extra data from an SDS item. More...

virtual int	GetInt () const
	If the SDS item refers to a scalar value, convert it to an integer. More...

virtual long	GetLong () const
	If the SDS item refers to a scalar value, convert it to long integer. More...

virtual std::string	GetName () const
	Return the name of the SDS item. More...

unsigned	GetNumItems () const
	Return the number of components in an SDS structure. More...

std::string	GetString () const
	If the SDS item refers to a scalar value or a character string, convert it to a string item. More...

virtual unsigned int	GetUInt () const
	If the SDS item refers to a scalar value, convert it to an unsigned integer. More...

virtual unsigned long	GetULong () const
	If the SDS item refers to a scalar value, convert it to an unsigned long integer. More...

virtual Id	Index (const long index, bool throwOnNotFound=true) const
	Factory constructor method Constructor which returns an id to a structured item indexed by position. More...

virtual void	Insert (Id &to_insert)
	Insert an SDS object into this object. More...

template<class ContainerType >
void	Insert (Id &to_insert, const ContainerType &dims)
	Insert an SDS object into this object, which is a structured array. More...

virtual bool	IsExternal () const
	Determine if the SDS structure is external. More...

virtual void	List () const
	List the contents of the structure to standard output. More...

virtual void	List (FILE *to) const
	List the contents of the structure to a C file. More...

virtual void	List (std::ostream &strm, int lineMaxLen=100) const
	List the contents of the structure to an output stream. More...

virtual void	List (PrintObjectPnt *printer, int lineMaxLen=100) const
	List the contents of the structure via a PrintObjectPnt object. More...

virtual void	List (const PrintObjectCR &printer, int lineMaxLen=100) const
	List the contents of the structure via a PrintObjectCR. More...

	operator bool () const
	Operator which tests if an item is valid. More...

	operator SdsIdType () const
	Operator which returns the underlying SDS id. More...

Id &	operator= (const Id &rhs)=delete
	Assignment operator - deleted. More...

Id &	operator= (Id &&rhs) noexcept
	Move assignment operator. More...

virtual void	Outlive ()
	Force the actual SDS ID to outlive the sds::Id variable. More...

template<typename T >
void	Pointer (T *data, unsigned long length=0) const
	Obtain a pointer to the data area of a primitive SDS item. More...

template<typename T >
void	Put (const unsigned long length, const T *const data, const unsigned long offset=0)
	Put data into an SDS item. More...

template<typename T >
void	Put (const std::string &name, T value)
	Insert a primitive value into a named component of the structure. More...

void	Put (const std::string &name, const std::string &value)
	Insert a string value into a named component of the structure. More...

template<typename T >
void	Put (T value)
	Insert a primitive value into the item. More...

void	Put (const std::string &value)
	Insert a string value into the component. More...

virtual void	PutExtra (const std::string &extra)
	Put extra data into an SDS item. More...

virtual void	Rename (const std::string &name)
	Rename the SDS item. More...

template<class ContainerType >
void	Resize (const ContainerType &dims)
	Change the dimensions of an SDS array. More...

virtual void	SetDelete ()
	Indicate the underlying SDS structure should be deleted when the sds::Id object is destroyed. More...

virtual void	SetFree ()
	Indicate the underlying SDS item should be free-ed when the sds::Id object is destroyed. More...

virtual void	ShallowCopy (const Id &source)
	Shallow copy from a const sds::Id which will outlive this object. More...

virtual void	ShallowCopy (Id *source, const bool outlives)
	Shallow copy from sds::Id. More...

virtual void	ShallowCopy (const SdsIdType source, const bool free=false, const bool del=false, const bool readfree=false)
	Shallow copy from SdsIdType. More...

virtual unsigned long	Size () const
	Return the size of an SDS structure, as required for exporting. More...

virtual unsigned long	SizeDefined () const
	Return the size of an SDS structure, as required for exporting when fully defined. More...

virtual std::string	toString (int maxlen=200)
	Convert the structure to a string. More...

virtual void	ValidateCode (SdsCodeType requiredCode) const
	Validate the code of the SDS item. More...

virtual void	Write (const std::string &filename) const
	Write the contents of the structure to a file. More...

Additional Inherited Members
Static Public Member Functions inherited from drama::sds::Id
template<typename ContainerType >
static Id	CreateArgCmdStruct (const ContainerType &values, const std::string &name="ArgStructure")
	Factory constructor which creates a new "Arg" style SDS structure in the DRAMA Command style. More...

template<typename T >
static Id	CreateArgCmdStructSingle (const T value, const std::string &name="ArgStructure")
	Factory constructor which creates a new "Arg" style SDS structure in the DRAMA Command style. More...

static Id	CreateArgStruct (const std::string &name="ArgStructure")
	Factory constructor which creates a new "Arg" style SDS structure. More...

template<class ContainerType >
static Id	CreateByAccess (ContainerType *container)
	Factory constructor method that accesses an exported SDS structure found in a byte stream. More...

template<class ContainerType >
static Id	CreateByImport (const ContainerType &container)
	Factory constructor method that imports an exported SDS structure found in a byte stream. More...

static Id	CreateFromSdsIdType (const SdsIdType item, const bool free=false, const bool del=false, const bool readfree=false)
	Factory constructor method that constructs an sds::Id item from an existing C language SDS id. More...

static Id	CreateFromSdsIdTypeCopy (const SdsIdType item)
	Factory constructor method that constructs an sds::Id item by coping an existing C language SDS id. More...

static Id	CreateNullItem ()
	Factory constructor method that constructs an null sds::Id item . More...

static Id	CreateTopLevel (const std::string &name, const SdsCodeType code, const std::string &extra="")
	Constructor which creates a new (non-array) top-level item. More...

template<class ContainerType >
static Id	CreateTopLevelArray (const std::string &name, const SdsCodeType code, const ContainerType &dims, const std::string &extra="")
	Factory constructor method Constructor which creates a new array top-level item. More...

static Id	FromFile (const std::string &filename)
	Factory constructor method that reads an SDS structure from a file. More...

Constructor & Destructor Documentation

drama::gitarg::Id::Id ( )

inline

Default constructor.

Creates an empty id object.

drama::gitarg::Id::Id	(	const sds::Id &	Id,
		const std::string &	Name = `"Argument1"`,
		const int	Position = `1`,
		const std::string	Default = `""`,
		const Flags	flags = `Flags::KeepErr`
	)

inline

Constructor with the initial value set from an SDS structure or file.

This constructor will access an SDS structure which may be specified either directly as the argument to an action or as the name of an SDS file containing the structure.

If the argument id is non-zero, points to an SDS structured item and if the structure name is not "ArgStructure", then the id of this structure is returned.

If the argument system id is non-zero and points to the an SDS item named "ArgStructure", the we try to find (by name or position), the requested item. If such an item is found and it is a Sds structure, the id of the item is returned. Otherwise, we interpret the value of the item as a filename and try to read the file. If the succeeds, then we return the id of the structure read from the file use SdsRead().

If we still don't have a value, the flag KeepErr is NOT specified and Default has a non-zero length, then it is treated as the name of a file which we read using SdsRead(). The resulting SDS id is returned.

If we read the value from a file, the name of the file is returned available from ActualName(). Otherwise, the name of the structure is returned by ActualName().

Methods WasReadFromFile() and WasReadFromDefault() indicate how we got the value.

Note - if we did not read this item from a file, then it is likely that the underlying SDS structure will be destroyed when the source of parameter Id is destroyed. Copy the item (sds::Id::Copy()) if you need it to last longer.

Parameters

Id	The SDS Argument structure.
Name	The name of the argument to get.
Position	If the item does not exist by the name, then presume this position.
Default	The default file name value. If we can't find the item and this item is not a zero length string, then it is a file we will use to read the default value from. Only used if the KeepErr flag is NOT set and no exception will be thrown if we don't have the value.
flags	Which GIT Flags to apply

References drama::Default, and Get().

virtual drama::gitarg::Id::~Id ( )

virtual

Destructor.

Reimplemented from drama::sds::Id.

Member Function Documentation

virtual std::string drama::gitarg::Id::ActualName ( ) const

virtual

Return the actual name of the file or structure.

If the item was read from a file, the name of the file is returned, otherwise the name of the structure is returned.

Returns: The name of the file or structure.

virtual void drama::gitarg::Id::Get	(	const sds::Id &	Id,
		const std::string &	Name = `"Argument1"`,
		const int	Position = `1`,
		const std::string	Default = `""`,
		const Flags	flags = `(Flags::KeepErr)`
	)

virtual

Get the value of the object from an SDS structure or file.

This method will access an Sds structure which may be specified either directly as the argument to an action or as the name of an SDS file containing the structure.

If the argument id is non-zero, points to an Sds structured item and the structure name is not "ArgStructure", then the id of this structure is returned.

If the argument system id is non-zero and points to the an SDS item named "ArgStructure", the we try to find (by name or position), the requested item. If such an item is found and it is a Sds structure, the id of the item is returned. Otherwise, we interpret the value of the item as a filename and try to read the file. If the succeeds, then we return the id of the structure read from the file use SdsRead().

If we still don't have a value, the flag KeepErr is NOT specified and Default has a non-zero length, then it is treated as the name of a file which we read using SdsRead(). The resulting Sds id is returned.

If we read the value from a file, the name of the file is returned available from ActualName(). Otherwise, the name of the structure is returned by ActualName().

Methods WasReadFromFile() and WasReadFromDefault() indicate how we got the value.

Note - if we did not read this item from a file, then it is likely that the underlying SDS structure will be destroyed when the source of parameter Id is destroyed. Copy the item (sds::Id::Copy()) if you need it to last longer.

Parameters

Id	The SDS Argument structure.
Name	The name of the argument to get.
Position	If the item does not exist by the name, then presume this position.
Default	The default file name value. If we can't find the item and this item is not a zero length string, then it is a file we will use to read the default value from. Only used if the KeepErr flag is NOT yet and no exception thrown.
flags	Which GIT Flags to apply

Referenced by Id().

virtual bool drama::gitarg::Id::WasReadFromDefault ( ) const

virtual

Indicates if the structure was read from the default.

Returns: True if the structure was read from the default file.

virtual bool drama::gitarg::Id::WasReadFromFile ( ) const

virtual

Indicates if the structure was read from a file.

Returns: True if the structure was read from a file.

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

gitarg.hh

Detailed Description

Public Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

Member Function Documentation