1 /* gEDA - GPL Electronic Design Automation
2 * libgeda - gEDA's library
3 * Copyright (C) 1998-2010 gEDA Contributors (see ChangeLog for details)
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License
16 * along with this program; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
21 * \brief The component library system
23 * <B>clib</B> stands for component library.
25 * The <b>component library</b> is made up of a number of
26 * <b>component sources</b>, each of which in turn makes available a
27 * number of component <b>symbols</b>. Each source may be either a
28 * directory on disk containing symbol files, a command in the system
29 * PATH which can generate gEDA symbol data (e.g. from a database),
30 * or a Scheme function which can do likewise. A component source is
31 * represented by a #CLibSource instance.
33 * The component library system manages component sources and
34 * symbols, and abstracts the interface to the underlying storage.
36 * To initialise the component library, s_clib_init() is called. To
37 * clean up when it is no longer needed, s_clib_free() should be
40 * A directory which contains one or more symbol files in gEDA
41 * format may be used as a component source. Each symbol file should
42 * have a filename ending in ".sym" (case insensitive). A
43 * component source based on a directory can be added using
44 * s_clib_add_directory(). Symbol files with filenames starting with
45 * a period "." are ignored.
47 * An executable program in the system search path may be used as a
48 * component source, and it must conform with the specification given
49 * on page \ref libcmds. A component source based on a command may
50 * be added using s_clib_add_command().
52 * Scheme functions may be used as a component source; for more
53 * information, please see page \ref libscms. A component source
54 * based on Scheme functions may be added using s_clib_add_scm().
56 * Each symbol is identified by its \b name, which is stored in the
57 * saved schematic file. The name must be a valid for storage in a
58 * gEDA schematic file as the "basename" of a "component" object.
59 * For symbols from directory sources, the filename of the symbol is
60 * taken as the symbol name. For a command source, the name may be
61 * any permissible string. Guidelines to follow:
63 * -# Do not begin a symbol name with "EMBEDDED"
64 * -# Do not use whitespace, or any of the characters "<tt>/:!*?</tt>".
65 * -# Try to use unique names.
67 * The component database may be queried using s_clib_search(). A
68 * null-terminated buffer containing symbol data (suitable for
69 * loading using o_read_buffer()) may be obtained using
70 * s_clib_symbol_get_data(). If an exact symbol name is known, the
71 * symbol data may be requested directly using
72 * s_clib_symbol_get_data_by_name().
75 * \section libcmds Library Commands
77 * A program or set of programs can be used as a component source. The procedure used to add such a source from a gEDA rc file is:
80 * (component-library-command listcmd getcmd name)
83 * This is implemented by g_rc_component_library_command(), which is
84 * a wrapper for s_clib_add_command().
86 * The list command will be executed with no further arguments, and
87 * should output a list of available symbol names on stdout. The get
88 * command will have a symbol name appended to it as the final
89 * argument, and should output gEDA symbol data on stdout.
91 * If the command cannot successfully complete, it should exit with
92 * non-zero exit status. Anything it has output on stdout will be
93 * ignored, and any stderr output displayed to the user.
95 * \section libscms Library Scheme Procedures
97 * A set of Scheme procedures can be used as a component source. The
98 * procedure used to add such a source from a gEDA rc file is:
101 * (component-library-funcs listfunc getfunc name)
104 * This is implemented by g_rc_component_library_funcs(), which is a
105 * wrapper for s_clib_add_scm().
107 * \b listfunc and \b getfunc must both be Guile procedures. \b
108 * listfunc takes no arguments, and returns a list of symbol
109 * names. \b getfunc takes a symbol name as an argument, and returns
110 * gEDA symbol data in a string, or \b \#f if not known.
123 #ifdef HAVE_LIBDMALLOC
127 #ifdef HAVE_SYS_WAIT_H
128 #include <sys/wait.h>
130 #define WIFSIGNALED(x) 0
131 #define WTERMSIG(x) 0
132 #define WIFEXITED(x) 1
133 #define WEXITSTATUS(x) 0
138 #include "libgeda_priv.h"
140 /* Constant definitions
141 * ===================
144 /*! All symbols in directory sources end with this string. Must be
146 #define SYM_FILENAME_FILTER ".sym"
148 /*! Library command mode used to fetch list of symbols */
149 #define CLIB_LIST_CMD "list"
151 /*! Library command mode used to fetch symbol data */
152 #define CLIB_DATA_CMD "get"
154 /*! Maximum number of symbol cache entries */
155 #define CLIB_MAX_SYMBOL_CACHE 128
156 /*! When symbol cache gets full, remove down to this level */
157 #define CLIB_MIN_SYMBOL_CACHE 96
163 /*! Valid types of component source */
164 enum CLibSourceType
{
166 /*! Directory source */
168 /*! Command source */
170 /*! Guile function source */
174 /*! Stores data about a particular component source */
176 /*! Type of source */
177 enum CLibSourceType type
;
178 /*! Name of source */
180 /*! Available symbols (#CLibSymbol) */
183 /*! Path to directory */
186 /*! Command & arguments for listing symbols */
188 /*! Command & arguments for retrieving symbol data */
191 /*! Scheme function for listing symbols */
193 /*! Scheme function for retrieving symbol data */
197 /*! Stores data about a particular symbol */
199 /*! The source this symbol is available from */
201 /*! The name of this symbol */
205 /*! Symbol data cache entry */
206 typedef struct _CacheEntry CacheEntry
;
208 /*! Pointer to symbol */
220 /*! Holds the list of all known component sources */
221 static GList
*clib_sources
= NULL
;
223 /*! Caches results of s_clib_search(). The key of the hashtable is a
224 * string describing the search that was carried out, and the value
225 * is a list of symbol pointers. */
226 static GHashTable
*clib_search_cache
= NULL
;
228 /*! Caches symbol data. The key of the hashtable is a symbol pointer,
229 * and the value is a #CacheEntry structure containing the data and
230 * the time it was last used. */
231 static GHashTable
*clib_symbol_cache
= NULL
;
233 /* Local static functions
234 * ======================
236 static void free_symbol (gpointer data
, gpointer user_data
);
237 static void free_symbol_cache_entry (gpointer data
);
238 static void free_source (gpointer data
, gpointer user_data
);
239 static gint
compare_source_name (gconstpointer a
, gconstpointer b
);
240 static gint
compare_symbol_name (gconstpointer a
, gconstpointer b
);
241 static void cache_find_oldest (gpointer key
, gpointer value
, gpointer user_data
);
242 static gchar
*run_source_command (const gchar
*command
);
243 static CLibSymbol
*source_has_symbol (const CLibSource
*source
,
245 static gchar
*uniquify_source_name (const gchar
*name
);
246 static void refresh_directory (CLibSource
*source
);
247 static void refresh_command (CLibSource
*source
);
248 static void refresh_scm (CLibSource
*source
);
249 static gchar
*get_data_directory (const CLibSymbol
*symbol
);
250 static gchar
*get_data_command (const CLibSymbol
*symbol
);
251 static gchar
*get_data_scm (const CLibSymbol
*symbol
);
253 /*! \brief Initialise the component library.
254 * \par Function Description
255 * Resets and initialises the component library.
257 * \warning This function must be called before any other functions
262 if (clib_sources
!= NULL
) {
266 if (clib_search_cache
!= NULL
) {
267 s_clib_flush_search_cache();
269 clib_search_cache
= g_hash_table_new_full ((GHashFunc
) g_str_hash
,
270 (GEqualFunc
)g_str_equal
,
271 (GDestroyNotify
) g_free
,
272 (GDestroyNotify
) g_list_free
);
275 if (clib_symbol_cache
!= NULL
) {
276 s_clib_flush_symbol_cache();
279 g_hash_table_new_full ((GHashFunc
) g_direct_hash
,
280 (GEqualFunc
) g_direct_equal
,
282 (GDestroyNotify
) free_symbol_cache_entry
);
286 /*! \brief Iterator callback for freeing a symbol.
287 * \par Function Description
288 * Private function used only in s_clib.c.
290 static void free_symbol (gpointer data
, gpointer user_data
)
292 CLibSymbol
*symbol
= data
;
293 if (symbol
!= NULL
) {
294 if (symbol
->source
!= NULL
) {
295 symbol
->source
= NULL
;
297 if (symbol
->name
!= NULL
) {
298 g_free (symbol
->name
);
305 /*! \brief Iterator callback for freeing a symbol cache entry.
306 * \par Function Description
307 * Private function used only in s_clib.c.
309 static void free_symbol_cache_entry (gpointer data
)
311 CacheEntry
*entry
= data
;
312 g_return_if_fail (entry
!= NULL
);
313 g_free (entry
->data
);
317 /*! \brief Iterator callback for freeing a source.
318 * \par Function Description
319 * Private function used only in s_clib.c.
321 static void free_source (gpointer data
, gpointer user_data
)
323 CLibSource
*source
= data
;
324 if (source
!= NULL
) {
325 if (source
->name
!= NULL
) {
326 g_free (source
->name
);
329 if (source
->symbols
!= NULL
) {
330 g_list_foreach (source
->symbols
, (GFunc
) free_symbol
, NULL
);
331 g_list_free (source
->symbols
);
332 source
->symbols
= NULL
;
334 if (source
->directory
!= NULL
) {
335 g_free (source
->directory
);
336 source
->directory
= NULL
;
338 if (source
->list_cmd
!= NULL
) {
339 g_free (source
->list_cmd
);
340 source
->list_cmd
= NULL
;
342 if (source
->get_cmd
!= NULL
) {
343 g_free (source
->get_cmd
);
344 source
->get_cmd
= NULL
;
346 if (source
->type
== CLIB_SCM
) {
347 scm_gc_unprotect_object (source
->list_fn
);
348 scm_gc_unprotect_object (source
->get_fn
);
353 /*! \brief Free all memory used by the component library.
354 * \par Function Description
355 * Should be called at program exit to clean up any remaining data
356 * being used by the component library system.
360 if (clib_sources
!= NULL
) {
361 g_list_foreach (clib_sources
, (GFunc
) free_source
, NULL
);
362 g_list_free (clib_sources
);
367 /*! \brief Compare two component sources by name.
368 * \par Function Description
369 * Compare two component sources by name, case-insensitively.
370 * Typically used when calling g_list_sort(). Private function used
371 * only in s_clib.c. Argument order is as strcasecmp().
373 * \param a First source to compare
374 * \param b Second source to compare
376 * \return As strcasecmp().
378 static gint
compare_source_name (gconstpointer a
, gconstpointer b
)
380 const CLibSource
*src1
= a
;
381 const CLibSource
*src2
= b
;
383 g_return_val_if_fail ((src1
!= NULL
), 0);
384 g_return_val_if_fail ((src2
!= NULL
), 0);
386 g_return_val_if_fail ((src1
->name
!= NULL
), 0);
387 g_return_val_if_fail ((src2
->name
!= NULL
), 0);
389 return strcasecmp(src1
->name
, src2
->name
);
392 /*! \brief Compare two component symbols by name.
393 * \par Function Description
394 * Compare two component symbols by name, case-insensitively.
395 * Typically used when calling g_list_sort(). Private function used
396 * only in s_clib.c. Argument order is as strcasecmp().
398 * \param a First symbol to compare
399 * \param b Second symbol to compare
401 * \return As strcasecmp().
403 static gint
compare_symbol_name (gconstpointer a
, gconstpointer b
)
405 const CLibSymbol
*sym1
= a
;
406 const CLibSymbol
*sym2
= b
;
408 g_return_val_if_fail ((sym1
!= NULL
), 0);
409 g_return_val_if_fail ((sym2
!= NULL
), 0);
411 g_return_val_if_fail ((sym1
->name
!= NULL
), 0);
412 g_return_val_if_fail ((sym2
->name
!= NULL
), 0);
414 return strcasecmp(sym1
->name
, sym2
->name
);
417 /*! \brief Iterator callback for finding oldest symbol cache entry
418 * \par Function Description
419 * Private function used only in s_clib.c.
421 static void cache_find_oldest (gpointer key
,
425 CacheEntry
*current
= value
;
426 CacheEntry
**oldest
= user_data
;
428 if (current
->accessed
< (*oldest
)->accessed
) {
433 /*! \brief Execute a library command.
434 * \par Function Description
435 * Execute a library command, returning the standard output, or \b
436 * NULL if the command fails for some reason. The system \b PATH is
437 * used to find the program to execute.
438 * The command can write messages to the standard error output. They
439 * are forwarded to the libgeda logging mechanism.
441 * Private function used only in s_clib.c.
443 * \todo This is probably generally useful.
445 * \param command Command string to execute.
446 * \return The program's output, or \b NULL on failure.
448 static gchar
*run_source_command (const gchar
*command
)
450 gchar
*standard_output
= NULL
;
451 gchar
*standard_error
= NULL
;
454 gboolean success
= FALSE
;
456 g_return_val_if_fail((command
!= NULL
), NULL
);
458 g_spawn_command_line_sync (command
,
465 s_log_message (_("Library command failed [%s]: %s\n"), command
,
469 } else if (WIFSIGNALED(exit_status
)) {
470 s_log_message (_("Library command failed [%s]: Uncaught signal %i.\n"),
471 command
, WTERMSIG(exit_status
));
473 } else if (WIFEXITED(exit_status
) && WEXITSTATUS(exit_status
)) {
474 s_log_message (_("Library command failed [%s]\n"), command
);
475 s_log_message(_("Error output was:\n%s\n"), standard_error
);
481 /* forward library command messages */
482 if (success
&& standard_error
!= NULL
)
483 s_log_message ("%s", standard_error
);
485 g_free (standard_error
);
487 if (success
) return standard_output
;
489 g_free (standard_output
);
493 /*! \brief Get a list of available component sources.
494 * \par Function Description
495 * Gets the current list of sources.
496 * \warning The GList returned should be freed when no longer
497 * needed. The returned value is not guaranteed to remain valid over
498 * calls to s_clib_add_directory() or s_clib_add_command().
499 * \return A \b GList of CLibSource.
501 GList
*s_clib_get_sources (const gboolean sorted
)
503 GList
*l
= g_list_copy(clib_sources
);
505 l
= g_list_sort (l
, (GCompareFunc
) compare_source_name
);
510 /*! \brief Find any symbols within a source with a given name.
511 * \par Function Description
512 * Iterates through the symbol list of the given source, checking if
513 * there is already a symbol with the given name. If there is
514 * such a symbol, it is returned.
516 * \param source The source to check.
517 * \param name The symbol name to look for.
518 * \return The matching symbol, or \b NULL if no match was found.
520 static CLibSymbol
*source_has_symbol (const CLibSource
*source
,
526 for (symlist
= g_list_first(source
->symbols
);
528 symlist
= g_list_next(symlist
)) {
530 symbol
= (CLibSymbol
*) symlist
->data
;
532 if (strcmp (symbol
->name
, name
) == 0) return symbol
;
538 /*! \brief Make sure a source name is unique.
539 * \par Function Description
540 * Checks if a source already exists with the given \a name. If one
541 * does, appends a number to the source name. If \a name is not
542 * already in use, returns it as is. The return value is always a
543 * newly-allocated string, and should be freed.
546 static gchar
*uniquify_source_name (const gchar
*name
)
548 gchar
*newname
= NULL
;
551 if (s_clib_get_source_by_name (name
) == NULL
) {
552 return g_strdup (name
);
558 newname
= g_strdup_printf ("%s<%i>", name
, i
);
559 } while (s_clib_get_source_by_name (newname
) != NULL
);
561 s_log_message (_("Library name [%s] already in use. Using [%s].\n"),
567 /*! \brief Rescan a directory for symbols.
568 * \par Function Description
569 * Rescans a directory for symbols.
571 * \todo Does this need to do something more sane with subdirectories
572 * than just skipping them silently?
574 * Private function used only in s_clib.c.
576 static void refresh_directory (CLibSource
*source
)
586 g_return_if_fail (source
!= NULL
);
587 g_return_if_fail (source
->type
== CLIB_DIR
);
589 /* Clear the current symbol list */
590 g_list_foreach (source
->symbols
, (GFunc
) free_symbol
, NULL
);
591 g_list_free (source
->symbols
);
592 source
->symbols
= NULL
;
594 /* Open the directory for reading. */
595 dir
= g_dir_open (source
->directory
, 0, &e
);
598 s_log_message (_("Failed to open directory [%s]: %s\n"),
599 source
->directory
, e
->message
);
604 while ((entry
= g_dir_read_name (dir
)) != NULL
) {
605 /* skip ".", ".." & hidden files */
606 if (entry
[0] == '.') continue;
608 /* skip subdirectories (for now) */
609 fullpath
= g_build_filename (source
->directory
, entry
, NULL
);
610 isfile
= g_file_test (fullpath
, G_FILE_TEST_IS_REGULAR
);
612 if (!isfile
) continue;
614 /* skip filenames that we already know about. */
615 if (source_has_symbol (source
, entry
) != NULL
) continue;
617 /* skip filenames which don't have the right suffix. */
618 low_entry
= g_utf8_strdown (entry
, -1);
619 if (!g_str_has_suffix (low_entry
, SYM_FILENAME_FILTER
)) {
625 /* Create and add new symbol record */
626 symbol
= g_new0 (CLibSymbol
, 1);
627 symbol
->source
= source
;
628 symbol
->name
= g_strdup(entry
);
630 /* Prepend because it's faster and it doesn't matter what order we
632 source
->symbols
= g_list_prepend (source
->symbols
, symbol
);
638 /* Now sort the list of symbols by name. */
639 source
->symbols
= g_list_sort (source
->symbols
,
640 (GCompareFunc
) compare_symbol_name
);
642 s_clib_flush_search_cache();
643 s_clib_flush_symbol_cache();
646 /*! \brief Re-poll a library command for symbols.
647 * \par Function Description
648 * Runs a library command, requesting a list of available symbols,
649 * and updates the source with the new list.
651 * Private function used only in s_clib.c.
653 static void refresh_command (CLibSource
*source
)
661 g_return_if_fail (source
!= NULL
);
662 g_return_if_fail (source
->type
== CLIB_CMD
);
664 /* Clear the current symbol list */
665 g_list_foreach (source
->symbols
, (GFunc
) free_symbol
, NULL
);
666 g_list_free (source
->symbols
);
667 source
->symbols
= NULL
;
669 /* Run the command to get the list of symbols */
670 cmdout
= run_source_command (source
->list_cmd
);
671 if (cmdout
== NULL
) return;
673 /* Use a TextBuffer to help reading out the lines of the output */
674 tb
= s_textbuffer_new (cmdout
, -1);
677 line
= s_textbuffer_next_line (tb
);
678 if (line
== NULL
) break;
679 if (line
[0] == '.') continue; /* TODO is this sane? */
681 name
= remove_nl(g_strdup(line
));
683 /* skip symbols already known about */
684 if (source_has_symbol (source
, name
) != NULL
) {
689 symbol
= g_new0 (CLibSymbol
, 1);
690 symbol
->source
= source
;
693 /* Prepend because it's faster and it doesn't matter what order we
695 source
->symbols
= g_list_prepend (source
->symbols
, symbol
);
698 s_textbuffer_free (tb
);
701 /* Sort all symbols by name. */
702 source
->symbols
= g_list_sort (source
->symbols
,
703 (GCompareFunc
) compare_symbol_name
);
705 s_clib_flush_search_cache();
706 s_clib_flush_symbol_cache();
709 /*! \brief Re-poll a scheme procedure for symbols.
710 * \par Function Description
711 * Calls a Scheme procedure to obtain a list of available symbols,
712 * and updates the source with the new list
714 * Private function used only in s_clib.c.
716 static void refresh_scm (CLibSource
*source
)
723 g_return_if_fail (source
!= NULL
);
724 g_return_if_fail (source
->type
== CLIB_SCM
);
726 /* Clear the current symbol list */
727 g_list_foreach (source
->symbols
, (GFunc
) free_symbol
, NULL
);
728 g_list_free (source
->symbols
);
729 source
->symbols
= NULL
;
731 symlist
= scm_call_0 (source
->list_fn
);
733 if (SCM_NCONSP (symlist
) && (symlist
!= SCM_EOL
)) {
734 s_log_message (_("Failed to scan library [%s]: Scheme function returned non-list\n"),
739 while (symlist
!= SCM_EOL
) {
740 symname
= SCM_CAR (symlist
);
741 if (!scm_is_string (symname
)) {
742 s_log_message (_("Non-string symbol name while scanning library [%s]\n"),
745 symbol
= g_new0 (CLibSymbol
, 1);
746 symbol
->source
= source
;
748 /* Need to make sure that the correct free() function is called
749 * on strings allocated by Guile. */
750 tmp
= scm_to_utf8_string (symname
);
751 symbol
->name
= g_strdup(tmp
);
754 /* Prepend because it's faster and it doesn't matter what order we
756 source
->symbols
= g_list_prepend (source
->symbols
, symbol
);
759 symlist
= SCM_CDR (symlist
);
762 /* Now sort the list of symbols by name. */
763 source
->symbols
= g_list_sort (source
->symbols
,
764 (GCompareFunc
) compare_symbol_name
);
766 s_clib_flush_search_cache();
767 s_clib_flush_symbol_cache();
770 /*! \brief Rescan all available component libraries.
771 * \par Function Description
772 * Resets the list of symbols available from each source, and
773 * repopulates it from scratch. Useful e.g. for checking for new
776 * \bug Disabled for now because it would break cached CLibSymbols used
777 * all over the place (e.g. in #st_object).
779 void s_clib_refresh ()
784 for (sourcelist
= clib_sources
;
786 sourcelist
= g_list_next(sourcelist
)) {
788 source
= (CLibSource
*) sourcelist
->data
;
789 switch (source
->type
)
792 refresh_directory(source
);
795 refresh_command (source
);
798 refresh_scm (source
);
801 g_critical("s_clib_refresh: source %p has bad source type %i\n",
802 source
, (gint
) source
->type
);
808 /*! \brief Get a named component source.
809 * \par Function Description
810 * Iterates through the known component sources, checking if there is
811 * a source with the given \a name.
813 * \param name The source name to look for.
815 * \return The matching source, or \b NULL if no match was found.
817 const CLibSource
*s_clib_get_source_by_name (const gchar
*name
)
822 for (sourcelist
= clib_sources
;
824 sourcelist
= g_list_next(sourcelist
)) {
826 source
= (CLibSource
*) sourcelist
->data
;
827 if (strcmp (source
->name
, name
) == 0) {
835 /*! \brief Add a directory of symbol files to the library
836 * \par Function Description
837 * Adds a directory containing symbol files to the library. Only
838 * files ending with #SYM_FILENAME_FILTER are considered to be symbol
839 * files. A \a name may be specified for the source; if \a name is
840 * \b NULL, the basename of the directory as returned by
841 * g_path_get_basename() is used.
843 * \param directory The path of the directory to add.
844 * \param name A descriptive name for the directory.
845 * \return The #CLibSource associated with the directory.
847 const CLibSource
*s_clib_add_directory (const gchar
*directory
,
851 gchar
*intname
, *realname
;
853 if (directory
== NULL
) {
858 intname
= g_path_get_basename (directory
);
859 realname
= uniquify_source_name (intname
);
862 realname
= uniquify_source_name (name
);
865 source
= g_new0 (CLibSource
, 1);
866 source
->type
= CLIB_DIR
;
867 source
->directory
= g_strdup (directory
);
868 source
->name
= realname
;
870 refresh_directory (source
);
872 /* Sources added later get scanned earlier */
873 clib_sources
= g_list_prepend (clib_sources
, source
);
878 /*! \brief Add symbol-generating commands to the library
879 * \par Function Description
880 * Adds a set of commands which can generate symbols to the
881 * library. \a list_cmd and \a get_cmd should be strings consisting
882 * of an executable name followed by any arguments required.
883 * Executables are resolved using the current PATH. See page \ref
884 * libcmds for more information on library commands.
886 * \param list_cmd The executable & arguments used to list available
888 * \param get_cmd The executable & arguments used to retrieve symbol
890 * \param name A descriptive name for the component source.
891 * \return The CLibSource associated with the component source.
893 const CLibSource
*s_clib_add_command (const gchar
*list_cmd
,
894 const gchar
*get_cmd
,
901 s_log_message (_("Cannot add library: name not specified\n"));
905 realname
= uniquify_source_name (name
);
907 if (list_cmd
== NULL
|| get_cmd
== NULL
) {
908 s_log_message (_("Cannot add library [%s]: both 'list' and "
909 "'get' commands must be specified.\n"),
913 source
= g_new0 (CLibSource
, 1);
914 source
->type
= CLIB_CMD
;
915 source
->name
= realname
;
917 source
->list_cmd
= g_strdup (list_cmd
);
918 source
->get_cmd
= g_strdup (get_cmd
);
920 refresh_command (source
);
922 /* Sources added later get sacnned earlier */
923 clib_sources
= g_list_prepend (clib_sources
, source
);
928 /*! \brief Add symbol-generating Scheme procedures to the library.
929 * \par Function Description
930 * Adds a source to the library based on Scheme procedures. See page
931 * \ref libscms for more information. Two procedures are required: \a
932 * listfunc must return a Scheme list of symbol names, and \a getfunc
933 * must return a string containing symbol data when passed a symbol
936 * \param listfunc A Scheme function returning a list of symbols.
937 * \param getfunc A Scheme function returning symbol data.
938 * \param name A descriptive name for the component source.
940 * \return The new CLibSource.
942 const CLibSource
*s_clib_add_scm (SCM listfunc
, SCM getfunc
, const gchar
*name
)
948 s_log_message (_("Cannot add library: name not specified\n"));
952 realname
= uniquify_source_name (name
);
954 if (scm_is_false (scm_procedure_p (listfunc
))
955 && scm_is_false (scm_procedure_p (getfunc
))) {
956 s_log_message (_("Cannot add Scheme-library [%s]: callbacks must be closures\n"),
961 source
= g_new0 (CLibSource
, 1);
962 source
->type
= CLIB_SCM
;
963 source
->name
= realname
;
964 source
->list_fn
= scm_gc_protect_object (listfunc
);
965 source
->get_fn
= scm_gc_protect_object (getfunc
);
967 refresh_scm (source
);
969 clib_sources
= g_list_prepend (clib_sources
, source
);
974 /*! \brief Get the name of a source.
975 * \par Function Description
976 * Get the name of a source for use e.g. in displaying a GUI.
978 * \param source Source to be examined.
979 * \return Name of source.
981 const gchar
*s_clib_source_get_name (const CLibSource
*source
)
983 if (source
== NULL
) return NULL
;
987 /*! \brief Get a list of symbols available from a given source.
988 * \par Function Description
989 * Get a \b GList containing all of the symbols available from \a
992 * \warning The returned \b GList will not be consistent over a call to
993 * s_clib_refresh(). It should be freed when no longer needed.
995 * \param source Source to be examined.
996 * \return A \b GList of #CLibSymbol.
998 GList
*s_clib_source_get_symbols (const CLibSource
*source
)
1000 if (source
== NULL
) return NULL
;
1001 return g_list_copy(source
->symbols
);
1005 /*! \brief Get the name of a symbol.
1006 * \par Function Description
1007 * Get the name of a symbol. The symbol name uniquely identifies it
1010 * \param symbol Symbol to be examined.
1011 * \return Name of symbol.
1013 const gchar
*s_clib_symbol_get_name (const CLibSymbol
*symbol
)
1015 if (symbol
== NULL
) return NULL
;
1016 return symbol
->name
;
1019 /*! \brief Get a filename for editing a symbol.
1020 * \par Function Description
1021 * Get the filename of the file a symbol was loaded from, if possible
1022 * (e.g. to allow loading for user editing).
1024 * \warning The returned string should be freed when no longer
1027 * \todo This is hack until there is a way to edit documents in
1028 * gschem which do not have a file in the filesystem associated with
1031 * \deprecated This function is a temporary workaround.
1033 * \param symbol Symbol to be examined.
1034 * \return Filename of symbol.
1036 gchar
*s_clib_symbol_get_filename (const CLibSymbol
*symbol
)
1038 if (symbol
== NULL
) return NULL
;
1040 if (symbol
->source
->type
!= CLIB_DIR
) return NULL
;
1042 return g_build_filename(symbol
->source
->directory
, symbol
->name
, NULL
);
1045 /*! \brief Get the source to which a symbol belongs.
1046 * \par Function Description
1047 * Get the source which a symbol is associated.
1049 * \param symbol Symbol to be examined.
1050 * \return Source which owns symbol.
1052 const CLibSource
*s_clib_symbol_get_source (const CLibSymbol
*symbol
)
1054 if (symbol
== NULL
) return NULL
;
1055 return symbol
->source
;
1058 /*! \brief Get symbol data from a directory source.
1059 * \par Function Description
1060 * Get symbol data from a directory data source. The return value
1061 * should be free()'d when no longer needed.
1063 * Private function used only in s_clib.c.
1065 * \param symbol Symbol to get data for.
1066 * \return Allocated buffer containing symbol data.
1068 static gchar
*get_data_directory (const CLibSymbol
*symbol
)
1070 gchar
*filename
= NULL
;
1074 g_return_val_if_fail ((symbol
!= NULL
), NULL
);
1075 g_return_val_if_fail ((symbol
->source
->type
== CLIB_DIR
), NULL
);
1077 filename
= g_build_filename(symbol
->source
->directory
,
1078 symbol
->name
, NULL
);
1080 g_file_get_contents (filename
, &data
, NULL
, &e
);
1083 s_log_message (_("Failed to load symbol from file [%s]: %s\n"),
1084 filename
, e
->message
);
1092 /*! \brief Get symbol data from a library command.
1093 * \par Function Description
1094 * Get symbol data from a library command. The return value should
1095 * be free()'d when no longer needed.
1097 * Private function used only in s_clib.c.
1099 * \param symbol Symbol to get data for.
1100 * \return Allocated buffer containing symbol data.
1102 static gchar
*get_data_command (const CLibSymbol
*symbol
)
1107 g_return_val_if_fail ((symbol
!= NULL
), NULL
);
1108 g_return_val_if_fail ((symbol
->source
->type
== CLIB_CMD
), NULL
);
1110 command
= g_strdup_printf ("%s %s", symbol
->source
->get_cmd
,
1113 result
= run_source_command ( command
);
1120 /*! \brief Get symbol data from a Scheme-based component source.
1121 * \par Function Description
1122 * Get symbol data from a Scheme-based component source. The return
1123 * value should be free()'d when no longer needed.
1125 * Private function used only in s_clib.c.
1127 * \param symbol Symbol to get data for.
1128 * \return Allocated buffer containing symbol data.
1130 static gchar
*get_data_scm (const CLibSymbol
*symbol
)
1136 g_return_val_if_fail ((symbol
!= NULL
), NULL
);
1137 g_return_val_if_fail ((symbol
->source
->type
== CLIB_SCM
), NULL
);
1139 symdata
= scm_call_1 (symbol
->source
->get_fn
,
1140 scm_from_utf8_string (symbol
->name
));
1142 if (!scm_is_string (symdata
)) {
1143 s_log_message (_("Failed to load symbol data [%s] from source [%s]\n"),
1144 symbol
->name
, symbol
->source
->name
);
1148 /* Need to make sure that the correct free() function is called
1149 * on strings allocated by Guile. */
1150 tmp
= scm_to_utf8_string (symdata
);
1151 result
= g_strdup(tmp
);
1157 /*! \brief Get symbol data.
1158 * \par Function Description
1159 * Get the unparsed gEDA-format data corresponding to a symbol from
1160 * the symbol's data source. The return value should be free()'d
1161 * when no longer needed.
1163 * On failure, returns \b NULL (the error will be logged).
1165 * \param symbol Symbol to get data for.
1166 * \return Allocated buffer containing symbol data.
1168 gchar
*s_clib_symbol_get_data (const CLibSymbol
*symbol
)
1175 g_return_val_if_fail ((symbol
!= NULL
), NULL
);
1176 g_return_val_if_fail ((symbol
->source
!= NULL
), NULL
);
1178 /* Trickery to bypass effects of const */
1179 symptr
= (gpointer
) symbol
;
1181 /* First, try the cache. */
1182 cached
= g_hash_table_lookup (clib_symbol_cache
, symptr
);
1183 if (cached
!= NULL
) {
1184 cached
->accessed
= time(NULL
);
1185 return g_strdup(cached
->data
);
1188 /* If the symbol wasn't found in the cache, get it directly. */
1189 switch (symbol
->source
->type
)
1192 data
= get_data_directory (symbol
);
1195 data
= get_data_command (symbol
);
1198 data
= get_data_scm (symbol
);
1201 g_critical("s_clib_symbol_get_data: source %p has bad source type %i\n",
1202 symbol
->source
, (gint
) symbol
->source
->type
);
1206 if (data
== NULL
) return NULL
;
1208 /* Cache the symbol data */
1209 cached
= g_new (CacheEntry
, 1);
1210 cached
->ptr
= (CLibSymbol
*) symptr
;
1211 cached
->data
= g_strdup (data
);
1212 cached
->accessed
= time (NULL
);
1213 g_hash_table_insert (clib_symbol_cache
, symptr
, cached
);
1215 /* Clean out the cache if it's too full */
1216 n
= g_hash_table_size (clib_symbol_cache
);
1217 if (n
> CLIB_MAX_SYMBOL_CACHE
) {
1218 for ( ; n
> CLIB_MIN_SYMBOL_CACHE
; n
--) {
1219 g_hash_table_foreach (clib_symbol_cache
,
1220 (GHFunc
) cache_find_oldest
,
1222 g_hash_table_remove (clib_symbol_cache
, cached
->ptr
);
1229 /*! \brief Find all symbols matching a pattern.
1231 * \par Function Description
1232 * Searches the library, returning all symbols whose
1233 * names match \a pattern.
1235 * Two search modes are available: \b CLIB_EXACT, where \a pattern is
1236 * compared to the symbol name using strcmp(), and \b CLIB_GLOB,
1237 * where \a pattern is assumed to be a glob pattern (see the GLib
1238 * documentation for details of the glob syntax applicable).
1240 * \warning The #CLibSymbol instances in the \b GList returned belong
1241 * to the component library, and should be considered constants; they
1242 * should not be manipulated or free()'d. On the other hand, the \b
1243 * GList returned must be freed with \b g_list_free() when no longer
1244 * needed. Note that the values returned will be invalidated by a
1245 * call to s_clib_free() or s_clib_refresh().
1247 * \param pattern The pattern to match against.
1248 * \param mode The search mode to use.
1249 * \return A \b GList of matching #CLibSymbol structures.
1251 GList
*s_clib_search (const gchar
*pattern
, const CLibSearchMode mode
)
1255 GList
*result
= NULL
;
1258 GPatternSpec
*globpattern
= NULL
;
1262 if (pattern
== NULL
) return NULL
;
1264 /* Use different cache keys depending on what sort of search is being done */
1274 g_critical ("s_clib_search: Bad search mode %i\n", mode
);
1277 key
= g_strdup_printf("%c%s", keytype
, pattern
);
1279 /* Check to see if the query is already in the cache */
1280 result
= (GList
*) g_hash_table_lookup (clib_search_cache
, key
);
1281 if (result
!= NULL
) {
1283 return g_list_copy (result
);
1286 if (mode
== CLIB_GLOB
) {
1287 globpattern
= g_pattern_spec_new(pattern
);
1290 for (sourcelist
= clib_sources
;
1292 sourcelist
= g_list_next(sourcelist
)) {
1294 source
= (CLibSource
*) sourcelist
->data
;
1296 for (symlist
= source
->symbols
;
1298 symlist
= g_list_next(symlist
)) {
1300 symbol
= (CLibSymbol
*) symlist
->data
;
1305 if (strcmp (pattern
, symbol
->name
) == 0) {
1306 result
= g_list_prepend (result
, symbol
);
1310 if (g_pattern_match_string (globpattern
, symbol
->name
)) {
1311 result
= g_list_prepend (result
, symbol
);
1318 result
= g_list_reverse (result
);
1320 if (globpattern
!= NULL
) {
1321 g_pattern_spec_free (globpattern
);
1324 g_hash_table_insert (clib_search_cache
, key
, g_list_copy (result
));
1325 /* __don't__ free key here, it's stored by the hash table! */
1333 /*! \brief Flush the symbol name lookup cache.
1334 * \par Function Description
1335 * Clears the hashtable which caches the results of s_clib_search().
1336 * You shouldn't ever need to call this, as all functions which
1337 * invalidate the cache are supposed to make sure it's flushed.
1339 void s_clib_flush_search_cache ()
1341 g_hash_table_remove_all (clib_search_cache
); /* Introduced in glib 2.12 */
1345 /*! \brief Flush the symbol data cache.
1346 * \par Function Description
1347 * Clears the hashtable which caches the results of s_clib_symbol_get_data().
1348 * You shouldn't ever need to call this, as all functions which
1349 * invalidate the cache are supposed to make sure it's flushed.
1351 void s_clib_flush_symbol_cache ()
1353 g_hash_table_remove_all (clib_symbol_cache
); /* Introduced in glib 2.12 */
1356 /*! \brief Invalidate all cached data about a symbol.
1357 * \par Function Description
1358 * Removes all cached symbol data for \a symbol.
1360 * \param symbol Symbol to flush cached data for.
1363 s_clib_symbol_invalidate_data (CLibSymbol
*symbol
)
1365 g_hash_table_remove (clib_symbol_cache
, (gpointer
) symbol
);
1368 /*! \brief Get symbol structure for a given symbol name.
1369 * \par Function Description
1370 * Return the first symbol found with the given \a name. If more
1371 * than one matching symbol is found or no matches are found at all,
1372 * emits a log message warning the user.
1374 * \param name The symbol name to match against.
1375 * \return The first matching symbol, or NULL if none found.
1377 const CLibSymbol
*s_clib_get_symbol_by_name (const gchar
*name
)
1379 GList
*symlist
= NULL
;
1380 const CLibSymbol
*retval
;
1382 symlist
= s_clib_search (name
, CLIB_EXACT
);
1384 if (symlist
== NULL
) {
1385 s_log_message (_("Component [%s] was not found in the component library\n"),
1390 if (g_list_next (symlist
) != NULL
) { /* More than one symbol */
1391 s_log_message (_("More than one component found with name [%s]\n"),
1395 retval
= (CLibSymbol
*) symlist
->data
;
1396 g_list_free (symlist
);
1401 /*! \brief Get symbol data for a given symbol name.
1402 * \par Function Description
1403 * Return the data for the first symbol found with the given name.
1404 * This is a helper function for the schematic load system, as it
1405 * will always want to load symbols given only their name.
1407 * On failure, returns \b NULL (the error will be logged).
1409 * \param name The symbol name to match against.
1410 * \return Allocated buffer containing symbol data.
1412 gchar
*s_clib_symbol_get_data_by_name (const gchar
*name
)
1414 const CLibSymbol
*symbol
;
1416 symbol
= s_clib_get_symbol_by_name (name
);
1417 if (symbol
== NULL
) return NULL
;
1418 return s_clib_symbol_get_data (symbol
);
1421 /*! \brief Get a list of symbols used.
1422 * \par Function Description
1424 * Scan a #TOPLEVEL structure's object list looking for symbols, and
1425 * return them in a list.
1427 * \warning The #CLibSymbol instances in the \b GList returned belong
1428 * to the component library, and should be considered constants; they
1429 * should not be manipulated or free()'d. On the other hand, the \b
1430 * GList returned must be freed with \b g_list_free() when no longer
1431 * needed. Note that the values returned will be invalidated by a
1432 * call to s_clib_free() or s_clib_refresh().
1434 * \bug Only includes components which are not embedded, but they
1435 * should (probably) also appear in the list.
1437 * \param toplevel #TOPLEVEL structure to scan.
1438 * \return GList of symbols.
1440 GList
*s_toplevel_get_symbols (const TOPLEVEL
*toplevel
)
1442 GList
*result
= NULL
;
1446 GList
*symlist
= NULL
;
1447 CLibSymbol
*sym
= NULL
;
1448 const GList
*p_iter
;
1449 const GList
*o_iter
;
1451 g_return_val_if_fail ((toplevel
!= NULL
), NULL
);
1453 for ( p_iter
= geda_list_get_glist( toplevel
->pages
);
1455 p_iter
= g_list_next( p_iter
)) {
1456 page
= (PAGE
*)p_iter
->data
;
1457 for (o_iter
= s_page_objects (page
);
1459 o_iter
= g_list_next (o_iter
)) {
1460 o
= (OBJECT
*)o_iter
->data
;
1461 if (o
->type
!= OBJ_COMPLEX
) continue;
1462 if (o
->complex_basename
== NULL
) continue;
1464 /* Since we're not looking at embedded symbols, the first
1465 * component with the given name will be the one we need.
1466 * N.b. we don't use s_clib_get_symbol_by_name() because it's
1468 symlist
= s_clib_search (o
->complex_basename
, CLIB_EXACT
);
1469 if (symlist
== NULL
) continue;
1470 sym
= (CLibSymbol
*) symlist
->data
;
1471 g_list_free (symlist
);
1473 /* We do the list insertion by evilly comparing pointers. This
1474 * is okay, because we always take the first symbol with the
1475 * given name, and symbol pointers don't change while this
1476 * function is running (we hope). Note that this creates a
1480 iter
= g_list_next(iter
)) {
1481 if (iter
->data
== sym
) {
1482 break; /* Already in list */
1484 if (compare_symbol_name (iter
->data
, sym
) > 0) {
1485 /* not in list yet, and gone past point where it should go */
1486 result
= g_list_insert_before (result
, iter
, sym
);
1491 /* not in list yet, and at end of list */
1492 result
= g_list_append (result
, sym
);