BRL-CAD
Loading...
Searching...
No Matches
search.h
Go to the documentation of this file.
1/* S E A R C H . H
2 * BRL-CAD
3 *
4 * Copyright (c) 2008-2025 United States Government as represented by
5 * the U.S. Army Research Laboratory.
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public License
9 * version 2.1 as published by the Free Software Foundation.
10 *
11 * This library is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this file; see the file named COPYING for more
18 * information.
19 */
20/** @addtogroup db_search
21 * @brief
22 * Functionality for searching .g files
23 */
24/** @{ */
25/** @file include/rt/search.h */
26
27#ifndef RT_SEARCH_H
28#define RT_SEARCH_H
29
30#include "common.h"
31
32#include "bu/list.h"
33#include "bu/ptbl.h"
34
35#include "rt/db_instance.h"
36#include "rt/defines.h"
37
39
40/**
41 * @brief Search for objects in a geometry database using filters
42 *
43 * The db_search function is a programmatic find-style interface that
44 * lets you search for objects in a geometry database. This function
45 * searches the database using a supplied list of filter criteria.
46 *
47 * The function returns a count of objects matching the filter
48 * criteria and can provide the resulting matches in binary format as
49 * either db_full_path or directory objects depending on the flags
50 * (i.e., depending on whether this is a flat or hierarchical search).
51 *
52 * There are a LOT of filter possibilities. See the search(n) manual
53 * page for details.
54 *
55 * @param[out] results is a bu_ptbl holding either db_full_path or
56 * directory pointers.
57 *
58 * @param flags is a bit field for setting various search options.
59 *
60 * @param filter is a string defining search filters to be used.
61 *
62 * @param path_c is the count of directory paths to be searched.
63 *
64 * @param path_v is one or more directory paths to be searched. If
65 * path_v itself is NULL, all top-level objects are searched
66 *
67 * @param dbip The database instance pointer corresponding to the
68 * current geometry database.
69 *
70 * @param clbk Optional callback function to call for -exec
71 *
72 * @param u1 Optional user data pointer
73 *
74 * @param u2 Optional user data pointer
75 *
76 * @return Negative return values indicate a problem with the search,
77 * and non-negative values indicate a successful search. Non-negative
78 * values correspond with the number of objects found.
79 *
80 * @retval -2 Return code when db_search is called with a NULL dbip.
81 * @retval -1 Return code when the plan search string is invalid.
82 * @retval 0 Return code when the search completed successfully but no matches were found.
83 * @retval >0 Return code when the search completed successfully and matched one or more objects.
84 *
85 * The following example assumes a database instance pointer (dbip) is
86 * available and ready to use.
87 *
88 * @code
89 * size_t i = 0;
90 * struct bu_ptbl results = BU_PTBL_INIT_ZERO;
91 * const char *plan = "-name *.s -or -below -type region";
92 * int matches = db_search(&results, DB_SEARCH_HIDDEN | DB_SEARCH_QUIET , plan, 0, NULL, dbip, ctx);
93 * for (i = 0; matches > 0 && i < BU_PTBL_LEN(&results); i++) {
94 * char *path_str = db_path_to_string((struct db_full_path *)BU_PTBL_GET(&results, i));
95 * bu_log("%s\n", path_str);
96 * bu_free(path_str, "free db_fullpath_to_string allocation");
97 * }
98 * db_search_free(&results);
99 * @endcode
100 *
101 * Note:
102 * Be aware that if you are using db_search to filter pre-built lists of paths,
103 * you need to check that your generated path list is NOT empty before calling
104 * db_search. If you accidentally send an empty path list into db_search,
105 * it will assume you wanted a tops list, which has a good chance of returning
106 * unwanted results.
107 *
108 */
110 int flags,
111 const char *filter,
112 int path_c,
113 struct directory **path_v,
114 struct db_i *dbip,
116 void *u1,
117 void *u2
118 );
119
120/* These are the possible search flags. */
121#define DB_SEARCH_TREE 0x0 /**< @brief Do a hierarchy-aware search. This is the default. */
122#define DB_SEARCH_FLAT 0x1 /**< @brief Do a flat search without hierarchy */
123#define DB_SEARCH_HIDDEN 0x2 /**< @brief Search using hidden objects */
124#define DB_SEARCH_RETURN_UNIQ_DP 0x4 /**< @brief Return the set of unique directory pointers instead of full paths */
125#define DB_SEARCH_QUIET 0x8 /**< @brief Silence all warnings */
126#define DB_SEARCH_PRINT_TOTAL 0x10 /**< @brief Print total number of items found in search */
127
128/**
129 * Properly free the table contents returned by db_search. The bu_ptbl
130 * itself, if not put on the stack, will need to be freed by the same
131 * calling function that allocated it.
132 */
134
135
136/* db_ls.c */
137/**
138 * db_ls takes a database instance pointer and assembles a directory
139 * pointer array of objects in the database according to a set of
140 * flags. An optional pattern can be supplied for match filtering via
141 * globbing rules (see bu_path_match()). If pattern is NULL,
142 * filtering is performed using only the flags.
143 *
144 * The caller is responsible for freeing the array.
145 *
146 * Returns -
147 * integer count of objects in dpv
148 * struct directory ** array of objects in dpv via argument
149 *
150 */
151RT_EXPORT extern size_t db_ls(const struct db_i *dbip,
152 int flags,
153 const char *pattern,
154 struct directory ***dpv);
155
156/* These are the possible listing flags. */
157#define DB_LS_PRIM 0x1 /**< @brief filter for primitives (solids)*/
158#define DB_LS_COMB 0x2 /**< @brief filter for combinations */
159#define DB_LS_REGION 0x4 /**< @brief filter for regions */
160#define DB_LS_HIDDEN 0x8 /**< @brief include hidden objects in results */
161#define DB_LS_NON_GEOM 0x10 /**< @brief filter for non-geometry objects */
162#define DB_LS_TOPS 0x20 /**< @brief filter for objects un-referenced by other objects */
163#define DB_LS_CYCLIC 0x40 /**< @brief filter for objects with a cyclic reference in subtrees */
164#define DB_LS_PHONY 0x80 /**< @brief enable and filter for objects such as the nirt display list entries */
165/* TODO - implement this flag
166 #define DB_LS_REGEX 0x100*/ /* interpret pattern using regex rules, instead of
167 globbing rules (default) */
168
169/* cyclic.c */
170/**
171 * db_cyclic_paths searches for cyclic paths in the database, either in all
172 * objects or checking whether a specific dp is cyclic within its subtree.
173 *
174 * If sdp is NULL, ALL directory pointers in the database are checked. This is
175 * a complete validation of the whole .g file, and the only way to
176 * comprehensively search for any cyclic paths present. The return count will
177 * be the number of combs with a cyclic reference in their subtrees.
178 *
179 * If sdp is non-NULL, the search will be limited to checking only the tree
180 * below sdp for a cyclic reference to sdp.
181 *
182 * If a cyclic_paths is non-NULL it will be used to return db_fullpath entries
183 * for the cyclic paths found.
184 */
185RT_EXPORT extern int db_cyclic_paths(struct bu_ptbl *cyclic_paths, const struct db_i *dbip, struct directory *sdp);
187
188/* Deprecated */
189typedef int(*db_search_callback_t)(int, const char*[],void*);
191 db_search_callback_t _e_callback; /**< @brief A function that evaluates an array of strings and returns a boolean. */
192 void *_e_userdata; /**< @brief A pointer that will be passed to the callback, usually a pointer to an interpreter. */
194RT_EXPORT extern struct db_search_context *db_search_context_create(void); /* FIXME: is this really needed? why not just use the struct directly from the stack or let the user handle allocation? */
199 int flags,
200 const char *filter,
201 int path_c,
202 struct directory **path_v,
203 struct db_i *dbip,
204 struct db_search_context *ctx
205 );
206
208
209#endif /* RT_SEARCH_H*/
210/** @} */
211/*
212 * Local Variables:
213 * mode: C
214 * tab-width: 8
215 * indent-tabs-mode: t
216 * c-file-style: "stroustrup"
217 * End:
218 * ex: shiftwidth=4 tabstop=8
219 */
Definition dvec.h:74
Header file for the BRL-CAD common definitions.
int(* bu_clbk_t)(int, const char **, void *, void *)
Definition defines.h:204
int(* db_search_callback_t)(int, const char *[], void *)
Definition search.h:190
int db_search_old(struct bu_ptbl *results, int flags, const char *filter, int path_c, struct directory **path_v, struct db_i *dbip, struct db_search_context *ctx)
int db_search(struct bu_ptbl *results, int flags, const char *filter, int path_c, struct directory **path_v, struct db_i *dbip, bu_clbk_t clbk, void *u1, void *u2)
Search for objects in a geometry database using filters.
void db_search_register_data(struct db_search_context *, void *)
struct db_search_context * db_search_context_create(void)
void db_search_free(struct bu_ptbl *search_results)
size_t db_ls(const struct db_i *dbip, int flags, const char *pattern, struct directory ***dpv)
void db_search_register_exec(struct db_search_context *, db_search_callback_t)
void db_search_context_destroy(struct db_search_context *ctx)
int db_cyclic_paths(struct bu_ptbl *cyclic_paths, const struct db_i *dbip, struct directory *sdp)
Definition ptbl.h:53
db_search_callback_t _e_callback
A function that evaluates an array of strings and returns a boolean.
Definition search.h:192
void * _e_userdata
A pointer that will be passed to the callback, usually a pointer to an interpreter.
Definition search.h:193