kindred/create
1
1
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects 9 Releases 2 Wiki Activity

Merge pull request #21184 from pieterhijma/doc-object-identifier

Browse Source 
Doc: Improve App::ObjectIdentifier documentation
This commit is contained in:
Chris Hennes
2025-05-07 16:22:49 -05:00
committed by GitHub
parent f2fa2f1360 9cbea91d60
commit d691d5261e
5 changed files with 1045 additions and 323 deletions
Download Patch File Download Diff File Expand all files Collapse all files

279
src/App/ObjectIdentifier.cpp
View File

@@ -51,16 +51,6 @@ FC_LOG_LEVEL_INIT("Expression", true, true)
using namespace App;
using namespace Base;
// Path class
/**
* @brief Quote input string according to quoting rules for an expression: because " and ' are
* used to designate inch and foot units, strings are quoted as <<string>>.
*
* @param input
* @return
*/
std::string App::quote(const std::string& input, bool toPython)
{
std::stringstream output;
@@ -103,12 +93,6 @@ std::string App::quote(const std::string& input, bool toPython)
}
/**
* @brief Construct an ObjectIdentifier object, given an owner and a single-value property.
* @param _owner Owner of property.
* @param property Name of property.
*/
ObjectIdentifier::ObjectIdentifier(const App::PropertyContainer* _owner,
const std::string& property,
int index)
@@ -153,12 +137,6 @@ ObjectIdentifier::ObjectIdentifier(const App::PropertyContainer* _owner, bool lo
}
}
/**
* @brief Construct an ObjectIdentifier object given a property. The property is assumed to be
* single-valued.
* @param prop Property to construct object identifier for.
*/
ObjectIdentifier::ObjectIdentifier(const Property& prop, int index)
: owner(nullptr)
, documentNameSet(false)
@@ -185,11 +163,6 @@ ObjectIdentifier::ObjectIdentifier(const Property& prop, int index)
}
}
/**
* @brief Get the name of the property.
* @return Name
*/
std::string App::ObjectIdentifier::getPropertyName() const
{
ResolveResults result(*this);
@@ -200,13 +173,6 @@ std::string App::ObjectIdentifier::getPropertyName() const
return components[result.propertyIndex].getName();
}
/**
* @brief Get Component at given index \a i.
* @param i: Index to get
* @param idx: optional return of adjusted component index
* @return A component.
*/
const App::ObjectIdentifier::Component& App::ObjectIdentifier::getPropertyComponent(int i,
int* idx) const
{
@@ -252,34 +218,16 @@ std::vector<ObjectIdentifier::Component> ObjectIdentifier::getPropertyComponents
return res;
}
/**
* @brief Compare object identifier with \a other.
* @param other Other object identifier.
* @return true if they are equal.
*/
bool ObjectIdentifier::operator==(const ObjectIdentifier& other) const
{
return owner == other.owner && toString() == other.toString();
}
/**
* @brief Compare object identifier with \a other.
* @param other Other object identifier
* @return true if they differ from each other.
*/
bool ObjectIdentifier::operator!=(const ObjectIdentifier& other) const
{
return !(operator==)(other);
}
/**
* @brief Compare object identifier with other.
* @param other Other object identifier.
* @return true if this object is less than the other.
*/
bool ObjectIdentifier::operator<(const ObjectIdentifier& other) const
{
if (owner < other.owner) {
@@ -291,21 +239,11 @@ bool ObjectIdentifier::operator<(const ObjectIdentifier& other) const
return toString() < other.toString();
}
/**
* @brief Return number of components.
* @return Number of components in this identifier.
*/
int ObjectIdentifier::numComponents() const
{
return components.size();
}
/**
* @brief Compute number of sub components, i.e excluding the property.
* @return Number of components.
*/
int ObjectIdentifier::numSubComponents() const
{
ResolveResults result(*this);
@@ -341,17 +279,6 @@ bool ObjectIdentifier::verify(const App::Property& prop, bool silent) const
return true;
}
/**
* @brief Create a string representation of this object identifier.
*
* An identifier is written as document#documentobject.property.subproperty1...subpropertyN
* document# may be dropped; it is assumed to be within owner's document. If documentobject is
* dropped, the property is assumed to be owned by the owner specified in the object identifiers
* constructor.
*
* @return A string
*/
const std::string& ObjectIdentifier::toString() const
{
if (!_cache.empty() || !owner) {
@@ -510,17 +437,12 @@ bool ObjectIdentifier::replaceObject(ObjectIdentifier& res,
return true;
}
/**
* @brief Escape toString representation so it is suitable for being embedded in a python command.
* @return Escaped string.
*/
std::string ObjectIdentifier::toEscapedString() const
{
return Base::Tools::escapedUnicodeFromUtf8(toString().c_str());
}
bool ObjectIdentifier::updateLabelReference(App::DocumentObject* obj,
bool ObjectIdentifier::updateLabelReference(const App::DocumentObject* obj,
const std::string& ref,
const char* newLabel)
{
@@ -606,11 +528,6 @@ bool ObjectIdentifier::relabeledDocument(ExpressionVisitor& v,
return false;
}
/**
* @brief Get sub field part of a property as a string.
* @return String representation of path.
*/
void ObjectIdentifier::getSubPathStr(std::ostream& s,
const ResolveResults& result,
bool toPython) const
@@ -633,14 +550,6 @@ std::string ObjectIdentifier::getSubPathStr(bool toPython) const
}
/**
* @brief Construct a Component part
* @param _name Name of component
* @param _type Type; simple, array, range or map
* @param _begin Array index or beginning of a Range, or INT_MAX for other type.
* @param _end ending of a Range, or INT_MAX for other type.
*/
ObjectIdentifier::Component::Component(const String& _name,
ObjectIdentifier::Component::typeEnum _type,
int _begin,
@@ -665,7 +574,6 @@ ObjectIdentifier::Component::Component(String&& _name,
, step(_step)
{}
size_t ObjectIdentifier::Component::getIndex(size_t count) const
{
if (begin >= 0) {
@@ -784,23 +692,11 @@ void ObjectIdentifier::Component::del(Py::Object& pyobj) const
}
}
/**
* @brief Create a simple component part with the given name
* @param _component Name of component.
* @return A new Component object.
*/
ObjectIdentifier::Component ObjectIdentifier::Component::SimpleComponent(const char* _component)
{
return Component(String(_component));
}
/**
* @brief Create a simple component part with the given name
* @param _component Name of component.
* @return A new Component object.
*/
ObjectIdentifier::Component
ObjectIdentifier::Component::SimpleComponent(const ObjectIdentifier::String& _component)
{
@@ -813,25 +709,11 @@ ObjectIdentifier::Component::SimpleComponent(ObjectIdentifier::String&& _compone
return Component(std::move(_component));
}
/**
* @brief Create an array component with given name and index.
* @param _component Name of component
* @param _index Index of component
* @return A new Component object.
*/
ObjectIdentifier::Component ObjectIdentifier::Component::ArrayComponent(int _index)
{
return Component(String(), Component::ARRAY, _index);
}
/**
* @brief Create a map component with given name and key.
* @param _component Name of component
* @param _key Key of component
* @return A new Component object.
*/
ObjectIdentifier::Component ObjectIdentifier::Component::MapComponent(const String& _key)
{
return Component(_key, Component::MAP);
@@ -842,26 +724,12 @@ ObjectIdentifier::Component ObjectIdentifier::Component::MapComponent(String&& _
return Component(std::move(_key), Component::MAP);
}
/**
* @brief Create a range component with given begin and end.
* @param _begin beginning index of the range
* @param _end ending index of the range
* @return A new Component object.
*/
ObjectIdentifier::Component
ObjectIdentifier::Component::RangeComponent(int _begin, int _end, int _step)
{
return Component(String(), Component::RANGE, _begin, _end, _step);
}
/**
* @brief Comparison operator for Component objects.
* @param other The object we want to compare to.
* @return true if they are equal, false if not.
*/
bool ObjectIdentifier::Component::operator==(const ObjectIdentifier::Component& other) const
{
if (type != other.type) {
@@ -882,11 +750,6 @@ bool ObjectIdentifier::Component::operator==(const ObjectIdentifier::Component&
}
}
/**
* @brief Create a string representation of a component.
* @return A string representing the component.
*/
void ObjectIdentifier::Component::toString(std::ostream& ss, bool toPython) const
{
switch (type) {
@@ -925,17 +788,6 @@ enum ResolveFlags
ResolveAmbiguous,
};
/**
* @brief Search for the document object given by name in doc.
*
* Name might be the internal name or a label. In any case, it must uniquely define
* the document object.
*
* @param doc Document to search
* @param name Name to search for.
* @return Pointer to document object if a unique pointer is found, 0 otherwise.
*/
App::DocumentObject* ObjectIdentifier::getDocumentObject(const App::Document* doc,
const String& name,
std::bitset<32>& flags)
@@ -991,13 +843,6 @@ App::DocumentObject* ObjectIdentifier::getDocumentObject(const App::Document* do
}
}
/**
* @brief Resolve the object identifier to a concrete document, documentobject, and property.
*
* This method is a helper method that fills out data in the given ResolveResults object.
*
*/
void ObjectIdentifier::resolve(ResolveResults& results) const
{
if (!owner) {
@@ -1128,12 +973,6 @@ void ObjectIdentifier::resolve(ResolveResults& results) const
}
}
/**
* @brief Find a document with the given name.
* @param name Name of document
* @return Pointer to document, or 0 if it is not found or not uniquely defined by name.
*/
Document* ObjectIdentifier::getDocument(String name, bool* ambiguous) const
{
if (name.getString().empty()) {
@@ -1186,11 +1025,6 @@ Document* ObjectIdentifier::getDocument(String name, bool* ambiguous) const
}
}
/**
* @brief Get the document object for the object identifier.
* @return Pointer to document object, or 0 if not found or uniquely defined.
*/
DocumentObject* ObjectIdentifier::getDocumentObject() const
{
const App::Document* doc = getDocument();
@@ -1290,11 +1124,6 @@ void ObjectIdentifier::getDep(Dependencies& deps,
}
}
/**
* @brief Get components as a string list.
* @return List of strings.
*/
std::vector<std::string> ObjectIdentifier::getStringList() const
{
std::vector<std::string> l;
@@ -1323,12 +1152,6 @@ std::vector<std::string> ObjectIdentifier::getStringList() const
return l;
}
/**
* @brief Construct the simplest possible object identifier relative to another.
* @param other The other object identifier.
* @return A new simplified object identifier.
*/
ObjectIdentifier ObjectIdentifier::relativeTo(const ObjectIdentifier& other) const
{
ObjectIdentifier result(other.getOwner());
@@ -1351,16 +1174,6 @@ ObjectIdentifier ObjectIdentifier::relativeTo(const ObjectIdentifier& other) con
return result;
}
/**
* @brief Parse a string to create an object identifier.
*
* This method throws an exception if the string is invalid.
*
* @param docObj Document object that will own this object identifier.
* @param str String to parse
* @return A new object identifier.
*/
ObjectIdentifier ObjectIdentifier::parse(const DocumentObject* docObj, const std::string& str)
{
std::unique_ptr<Expression> expr(ExpressionParser::parse(docObj, str.c_str()));
@@ -1381,12 +1194,6 @@ std::string ObjectIdentifier::resolveErrorString() const
return result.resolveErrorString();
}
/**
* @brief << operator, used to add a component to the object identifier.
* @param value Component object
* @return Reference to itself.
*/
ObjectIdentifier& ObjectIdentifier::operator<<(const ObjectIdentifier::Component& value)
{
components.push_back(value);
@@ -1402,11 +1209,6 @@ ObjectIdentifier& ObjectIdentifier::operator<<(ObjectIdentifier::Component&& val
}
/**
* @brief Get pointer to property pointed to by this object identifier.
* @return Point to property if it is uniquely defined, or 0 otherwise.
*/
Property* ObjectIdentifier::getProperty(int* ptype) const
{
ResolveResults result(*this);
@@ -1462,15 +1264,6 @@ Property* ObjectIdentifier::resolveProperty(const App::DocumentObject* obj,
}
/**
* @brief Create a canonical representation of an object identifier.
*
* The main work is actually done by the property's virtual canonicalPath(...) method,
* which is invoked by this call.
*
* @return A new object identifier.
*/
ObjectIdentifier ObjectIdentifier::canonicalPath() const
{
ObjectIdentifier res(*this);
@@ -1498,15 +1291,6 @@ ObjectIdentifier::DocumentMapper::~DocumentMapper()
_DocumentMap = nullptr;
}
/**
* @brief Set the document name for this object identifier.
*
* If force is true, the document name will always be included in the string representation.
*
* @param name Name of document object.
* @param force Force name to be set
*/
void ObjectIdentifier::setDocumentName(ObjectIdentifier::String&& name, bool force)
{
if (name.getString().empty()) {
@@ -1533,12 +1317,6 @@ void ObjectIdentifier::setDocumentName(ObjectIdentifier::String&& name, bool for
documentName = std::move(name);
}
/**
* @brief Get the document name from this object identifier
*
* @return Document name as a String object.
*/
ObjectIdentifier::String ObjectIdentifier::getDocumentName() const
{
ResolveResults result(*this);
@@ -1546,16 +1324,6 @@ ObjectIdentifier::String ObjectIdentifier::getDocumentName() const
return result.resolvedDocumentName;
}
/**
* @brief Set the document object name of this object identifier.
*
* If force is true, the document object will not be resolved dynamically from the
* object identifier's components, but used as given by this method.
*
* @param name Name of document object.
* @param force Force name to be set.
*/
void ObjectIdentifier::setDocumentObjectName(ObjectIdentifier::String&& name,
bool force,
ObjectIdentifier::String&& subname,
@@ -1619,11 +1387,6 @@ void ObjectIdentifier::setDocumentObjectName(const App::DocumentObject* obj,
}
/**
* @brief Get the document object name
* @return String with name of document object as resolved by object identifier.
*/
ObjectIdentifier::String ObjectIdentifier::getDocumentObjectName() const
{
ResolveResults result(*this);
@@ -1636,11 +1399,6 @@ bool ObjectIdentifier::hasDocumentObjectName(bool forced) const
return !documentObjectName.getString().empty() && (!forced || documentObjectNameSet);
}
/**
* @brief Get a string representation of this object identifier.
* @return String representation.
*/
std::string ObjectIdentifier::String::toString(bool toPython) const
{
if (isRealString()) {
@@ -1653,7 +1411,7 @@ std::string ObjectIdentifier::String::toString(bool toPython) const
void ObjectIdentifier::String::checkImport(const App::DocumentObject* owner,
const App::DocumentObject* obj,
String* objName)
const String* objName)
{
if (owner && owner->getDocument() && !str.empty()
&& ExpressionParser::ExpressionImporter::reader()) {
@@ -1695,7 +1453,7 @@ void ObjectIdentifier::String::checkImport(const App::DocumentObject* owner,
}
Py::Object
ObjectIdentifier::access(const ResolveResults& result, Py::Object* value, Dependencies* deps) const
ObjectIdentifier::access(const ResolveResults& result, const Py::Object* value, Dependencies* deps) const
{
if (!result.resolvedDocumentObject || !result.resolvedProperty
|| (!subObjectName.getString().empty() && !result.resolvedSubObject)) {
@@ -1924,19 +1682,6 @@ ObjectIdentifier::access(const ResolveResults& result, Py::Object* value, Depend
return pyobj;
}
/**
* @brief Get the value of the property or field pointed to by this object identifier.
*
* All type of objects are supported. Some types are casted to FC native
* type, including: Int, Float, String, Unicode String, and Quantities. Others
* are just kept as Python object wrapped by App::any.
*
* @param pathValue: if true, calls the property's getPathValue(), which is
* necessary for Qunatities to work.
*
* @return The value of the property or field.
*/
App::any ObjectIdentifier::getValue(bool pathValue, bool* isPseudoProperty) const
{
ResolveResults rs(*this);
@@ -1993,16 +1738,6 @@ Py::Object ObjectIdentifier::getPyValue(bool pathValue, bool* isPseudoProperty)
return Py::Object();
}
/**
* @brief Set value of a property or field pointed to by this object identifier.
*
* This method uses Python to do the actual work. and a limited set of types that
* can be in the App::any variable is supported: Base::Quantity, double,
* char*, const char*, int, unsigned int, short, unsigned short, char, and unsigned char.
*
* @param value Value to set
*/
void ObjectIdentifier::setValue(const App::any& value) const
{
std::stringstream ss;
@@ -2150,7 +1885,7 @@ void ObjectIdentifier::resolveAmbiguity()
resolveAmbiguity(result);
}
void ObjectIdentifier::resolveAmbiguity(ResolveResults& result)
void ObjectIdentifier::resolveAmbiguity(const ResolveResults& result)
{
if (!result.resolvedDocumentObject) {
@@ -2180,12 +1915,6 @@ void ObjectIdentifier::resolveAmbiguity(ResolveResults& result)
}
}
/** Construct and initialize a ResolveResults object, given an ObjectIdentifier instance.
*
* The constructor will invoke the ObjectIdentifier's resolve() method to initialize the object's
* data.
*/
ObjectIdentifier::ResolveResults::ResolveResults(const ObjectIdentifier& oi)
: propertyType(PseudoNone)
{

1071
src/App/ObjectIdentifier.h
View File

File diff suppressed because it is too large Load Diff

14
src/App/PropertyExpressionEngine.cpp
View File

@@ -406,7 +406,7 @@ void PropertyExpressionEngine::buildGraphStructures(
* @return New ObjectIdentifier
*/
ObjectIdentifier PropertyExpressionEngine::canonicalPath(const ObjectIdentifier& p) const
ObjectIdentifier PropertyExpressionEngine::canonicalPath(const ObjectIdentifier& oid) const
{
DocumentObject* docObj = freecad_cast<DocumentObject*>(getContainer());
@@ -416,24 +416,24 @@ ObjectIdentifier PropertyExpressionEngine::canonicalPath(const ObjectIdentifier&
}
int ptype;
Property* prop = p.getProperty(&ptype);
Property* prop = oid.getProperty(&ptype);
// p pointing to a property...?
// oid pointing to a property...?
if (!prop) {
throw Base::RuntimeError(p.resolveErrorString().c_str());
throw Base::RuntimeError(oid.resolveErrorString().c_str());
}
if (ptype || prop->getContainer() != getContainer()) {
return p;
return oid;
}
// In case someone calls this with p pointing to a PropertyExpressionEngine for some reason
if (prop->isDerivedFrom(PropertyExpressionEngine::classTypeId)) {
return p;
return oid;
}
// Dispatch call to actual canonicalPath implementation
return p.canonicalPath();
return oid.canonicalPath();
}
/**

2
src/App/PropertyLinks.cpp
View File

@@ -189,7 +189,7 @@ void PropertyLinkBase::checkLabelReferences(const std::vector<std::string>& subs
std::string PropertyLinkBase::updateLabelReference(const App::DocumentObject* parent,
const char* subname,
App::DocumentObject* obj,
const App::DocumentObject* obj,
const std::string& ref,
const char* newLabel)
{

2
src/App/PropertyLinks.h
View File

@@ -583,7 +583,7 @@ public:
*/
static std::string updateLabelReference(const App::DocumentObject* linked,
const char* subname,
App::DocumentObject* obj,
const App::DocumentObject* obj,
const std::string& ref,
const char* newLabel);
//@}