Gimp/pdb/groups/procedural_db.pdb

# GIMP - The GNU Image Manipulation Program
# Copyright (C) 1995 Spencer Kimball and Peter Mattis

# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3 of the License, or
# (at your option) any later version.

# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.

# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.

# "Perlized" from C source by Manish Singh <yosh@gimp.org>

sub procedural_db_temp_name {
    $blurb = 'Generates a unique temporary PDB name.';

    $help = <<'HELP';
This procedure generates a temporary PDB entry name that is guaranteed to be
unique.
HELP

    &andy_pdb_misc('1998');

    @outargs = (
	{ name => 'temp_name', type => 'string',
	  desc => 'A unique temporary name for a temporary PDB entry' }
    );

    %invoke = (
	code => <<'CODE'
{
  static gint proc_number = 0;

  temp_name = g_strdup_printf ("temp-procedure-number-%d", proc_number++);
}
CODE
    );
}

sub procedural_db_dump {
    $blurb = 'Dumps the current contents of the procedural database';

    $help = <<'HELP';
This procedure dumps the contents of the procedural database to the specified
file. The file will contain all of the information provided for each registered
procedure.
HELP

    &std_pdb_misc;
    $author = 'Spencer Kimball & Josh MacDonald';
    $copyright = $author . ' & Peter Mattis';

    @inargs = (
	{ name => 'filename', type => 'string', allow_non_utf8 => 1,
          non_empty => 1,
	  desc => 'The dump filename' }
    );

    %invoke = (
	code => <<'CODE'
{
  GFile *file = g_file_new_for_path (filename);

  success = gimp_pdb_dump (gimp->pdb, file, error);

  g_object_unref (file);
}
CODE
    );
}

sub procedural_db_query {
    $blurb = <<'BLURB';
Queries the procedural database for its contents using regular expression
matching.
BLURB

    $help = <<'HELP';
This procedure queries the contents of the procedural database. It is supplied
with seven arguments matching procedures on { name, blurb, help, author,
copyright, date, procedure type}. This is accomplished using regular expression
matching. For instance, to find all procedures with "jpeg" listed in the blurb,
all seven arguments can be supplied as ".*", except for the second, which can
be supplied as ".*jpeg.*". There are two return arguments for this procedure.
The first is the number of procedures matching the query. The second is a
concatenated list of procedure names corresponding to those matching the query.
If no matching entries are found, then the returned string is NULL and the
number of entries is 0.
HELP

    &std_pdb_misc;

    @inargs = (
	{ name => 'name', type => 'string', allow_non_utf8 => 1,
	  desc => 'The regex for procedure name' },
	{ name => 'blurb', type => 'string', allow_non_utf8 => 1,
	  desc => 'The regex for procedure blurb' },
	{ name => 'help', type => 'string', allow_non_utf8 => 1,
	  desc => 'The regex for procedure help' },
	{ name => 'author', type => 'string', allow_non_utf8 => 1,
	  desc => 'The regex for procedure author' },
	{ name => 'copyright', type => 'string', allow_non_utf8 => 1,
	  desc => 'The regex for procedure copyright' },
	{ name => 'date', type => 'string', allow_non_utf8 => 1,
	  desc => 'The regex for procedure date' },
	{ name => 'proc_type', type => 'string', allow_non_utf8 => 1,
	  desc => 'The regex for procedure type: { \'Internal GIMP procedure\',
		   \'GIMP Plug-in\', \'GIMP Extension\',
		   \'Temporary Procedure\' }' }
    );

    @outargs = (
	{ name  => 'procedure_names', type  => 'stringarray', void_ret => 1,
	  desc  => 'The list of procedure names',
	  array => { name  => 'num_matches',
		     desc  => 'The number of matching procedures' } }
    );

    %invoke = (
	code => <<CODE
{
  success = gimp_pdb_query (gimp->pdb,
                            name, blurb, help, author,
                            copyright, date, proc_type,
                            &num_matches, &procedure_names,
                            error);
}
CODE
    );
}

sub procedural_db_proc_exists {
    $blurb = <<'BLURB';
Checks if the specified procedure exists in the procedural database
BLURB

    $help = <<'HELP';
This procedure checks if the specified procedure is registered in the
procedural database.
HELP

    &neo_pdb_misc('2008', '2.6');

    @inargs = (
	{ name  => 'procedure_name', type  => 'string', non_empty => 1,
	  desc  => 'The procedure name' }
    );

    @outargs = (
	{ name => 'exists', type => 'boolean',
	  desc => 'Whether a procedure of that name is registered' }
    );

    %invoke = (
	code => <<'CODE'
{
  GimpProcedure *procedure;
  gchar         *canonical;

  canonical = gimp_canonicalize_identifier (procedure_name);

  procedure = gimp_pdb_lookup_procedure (gimp->pdb, canonical);

  if (! procedure)
    {
      procedure_name = gimp_pdb_lookup_compat_proc_name (gimp->pdb, canonical);

      if (procedure_name)
        procedure = gimp_pdb_lookup_procedure (gimp->pdb, procedure_name);
    }

  g_free (canonical);

  exists = (procedure != NULL);
}
CODE
    );
}

sub procedural_db_proc_info {
    $blurb = <<'BLURB';
Queries the procedural database for information on the specified procedure.
BLURB

    $help = <<'HELP';
This procedure returns information on the specified procedure. A short
blurb, detailed help, author(s), copyright information, procedure
type, number of input, and number of return values are returned. For
specific information on each input argument and return value, use the
gimp_procedural_db_proc_arg() and gimp_procedural_db_proc_val()
procedures.
HELP

    &std_pdb_misc;
    $date = '1997';

    @inargs = (
	{ name  => 'procedure_name', type  => 'string', non_empty => 1,
	  desc  => 'The procedure name' }
    );

    @outargs = (
	{ name => 'blurb', type => 'string', void_ret => 1, wrap => 1,
	  desc => 'A short blurb' },
	{ name => 'help', type => 'string',
	  desc => 'Detailed procedure help' },
	{ name => 'author', type => 'string',
	  desc => 'Author(s) of the procedure' },
	{ name => 'copyright', type => 'string',
	  desc => 'The copyright' },
	{ name => 'date', type => 'string',
	  desc => 'Copyright date' },
        { name => 'proc_type', type => 'enum GimpPDBProcType',
	  desc => 'The procedure type' },
        { name => 'num_args', type => 'int32',
	  desc => 'The number of input arguments' },
        { name => 'num_values', type => 'int32',
	  desc => 'The number of return values' }
    );

    %invoke = (
	code => <<'CODE'
{
  GimpPDBProcType  ptype;
  gchar           *canonical;

  canonical = gimp_canonicalize_identifier (procedure_name);

  success = gimp_pdb_proc_info (gimp->pdb, canonical,
                                &blurb, &help, &author,
                                &copyright, &date, &ptype,
                                &num_args, &num_values,
                                error);
  proc_type = ptype;

  g_free (canonical);
}
CODE
    );
}

sub procedural_db_proc_arg {
    $blurb = <<BLURB;
Queries the procedural database for information on the specified procedure's
argument.
BLURB

    $help = <<HELP;
This procedure returns information on the specified procedure's argument. The
argument type, name, and a description are retrieved.
HELP

    &std_pdb_misc;
    $date = '1997';

    @inargs = (
	{ name => 'procedure_name', type  => 'string', non_empty => 1,
	  desc => 'The procedure name' },
	{ name => 'arg_num', type => 'int32',
	  desc => 'The argument number' }
    );

    @outargs = (
	{ name => 'arg_type', type => 'enum GimpPDBArgType (no GIMP_PDB_END)',
	  void_ret => 1,
	  desc => "The type of argument" },
	{ name => 'arg_name', type => 'string',
	  desc => 'The name of the argument' },
	{ name => 'arg_desc', type => 'string',
	  desc => 'A description of the argument' }
    );

   %invoke = (
	code => <<CODE
{
  GimpProcedure *proc;
  gchar         *canonical;

  canonical = gimp_canonicalize_identifier (procedure_name);

  proc = gimp_pdb_lookup_procedure (gimp->pdb, canonical);

  if (! proc)
    {
      const gchar *compat_name;

      compat_name = gimp_pdb_lookup_compat_proc_name (gimp->pdb, canonical);

      if (compat_name)
        proc = gimp_pdb_lookup_procedure (gimp->pdb, compat_name);
    }

  g_free (canonical);

  if (proc && (arg_num >= 0 && arg_num < proc->num_args))
    {
      GParamSpec *pspec = proc->args[arg_num];

      arg_type = gimp_pdb_compat_arg_type_from_gtype (G_PARAM_SPEC_VALUE_TYPE (pspec));
      arg_name = g_strdup (g_param_spec_get_name (pspec));
      arg_desc = gimp_param_spec_get_desc (pspec);
    }
  else
    success = FALSE;
}
CODE
   );
}

sub procedural_db_proc_val {
    $blurb = <<BLURB;
Queries the procedural database for information on the specified procedure's
return value.
BLURB

    $help = <<HELP;
This procedure returns information on the specified procedure's return value.
The return value type, name, and a description are retrieved.
HELP

    &std_pdb_misc;
    $date = '1997';

    @inargs = (
	{ name => 'procedure_name', type  => 'string', non_empty => 1,
	  desc => 'The procedure name' },
	{ name => 'val_num', type => 'int32',
	  desc => 'The return value number' }
    );

    @outargs = (
	{ name => 'val_type', type => 'enum GimpPDBArgType (no GIMP_PDB_END)',
	  void_ret => 1,
	  desc => "The type of return value" },
	{ name => 'val_name', type => 'string',
	  desc => 'The name of the return value' },
	{ name => 'val_desc', type => 'string',
	  desc => 'A description of the return value' }
    );

   %invoke = (
	code => <<CODE
{
  GimpProcedure *proc;
  gchar         *canonical;

  canonical = gimp_canonicalize_identifier (procedure_name);

  proc = gimp_pdb_lookup_procedure (gimp->pdb, canonical);

  if (! proc)
    {
      const gchar *compat_name;

      compat_name = gimp_pdb_lookup_compat_proc_name (gimp->pdb, canonical);

      if (compat_name)
        proc = gimp_pdb_lookup_procedure (gimp->pdb, compat_name);
    }

  g_free (canonical);

  if (proc && (val_num >= 0 && val_num < proc->num_values))
    {
      GParamSpec *pspec = proc->values[val_num];

      val_type = gimp_pdb_compat_arg_type_from_gtype (G_PARAM_SPEC_VALUE_TYPE (pspec));
      val_name = g_strdup (g_param_spec_get_name (pspec));
      val_desc = gimp_param_spec_get_desc (pspec);
    }
  else
    success = FALSE;
}
CODE
   );
}

sub procedural_db_get_data {
    $blurb = 'Returns data associated with the specified identifier.';

    $help = <<'HELP';
This procedure returns any data which may have been associated with the
specified identifier. The data is a variable length array of bytes. If no data
has been associated with the identifier, an error is returned.
HELP

    &std_pdb_misc;
    $date = '1997';

    @inargs = (
	{ name => 'identifier', type => 'string', non_empty => 1,
	  desc => 'The identifier associated with data' }
    );

    @outargs = (
	{ name  => 'data', type  => 'int8array', wrap => 1, void_ret => 1,
	  desc  => 'A byte array containing data',
	  array => { name => 'bytes', type => '1 <= int32',
		     desc => 'The number of bytes in the data' } }
    );

    %invoke = (
	code => <<'CODE'
{
  gchar        *canonical = gimp_canonicalize_identifier (identifier);
  const guint8 *orig_data;

  orig_data = gimp_plug_in_manager_get_data (gimp->plug_in_manager,
                                             canonical, &bytes);

  g_free (canonical);

  if (orig_data)
    data = g_memdup (orig_data, bytes);
  else
    success = FALSE;
}
CODE
    );
}

sub procedural_db_get_data_size {
    $blurb = 'Returns size of data associated with the specified identifier.';

    $help = <<'HELP';
This procedure returns the size of any data which may have been associated with
the specified identifier. If no data has been associated with the identifier,
an error is returned.
HELP

    &nick_pdb_misc('1998');

    @inargs = (
	{ name => 'identifier', type => 'string', non_empty => 1,
	  desc => 'The identifier associated with data' }
    );

    @outargs = (
	{ name => 'bytes', type => '1 <= int32',
	  desc => 'The number of bytes in the data' }
    );

    %invoke = (
	code => <<'CODE'
{
  gchar *canonical = gimp_canonicalize_identifier (identifier);

  if (! gimp_plug_in_manager_get_data (gimp->plug_in_manager,
                                       canonical, &bytes))
    success = FALSE;

  g_free (canonical);
}
CODE
    );
}

sub procedural_db_set_data {
    $blurb = 'Associates the specified identifier with the supplied data.';

    $help = <<'HELP';
This procedure associates the supplied data with the provided identifier. The
data may be subsequently retrieved by a call to 'procedural-db-get-data'.
HELP

    &std_pdb_misc;
    $date = '1997';

    @inargs = (
	{ name => 'identifier', type => 'string', non_empty => 1,
	  desc => 'The identifier associated with data' },
	{ name  => 'data', type  => 'int8array',
	  desc  => 'A byte array containing data', wrap => 1,
	  array => { name => 'bytes', type => '1 <= int32',
		     desc => 'The number of bytes in the data' } }
    );

    %invoke = (
	code => <<'CODE'
{
  gchar *canonical = gimp_canonicalize_identifier (identifier);

  gimp_plug_in_manager_set_data (gimp->plug_in_manager,
                                 canonical, bytes, data);

  g_free (canonical);
}
CODE
    );
}


@headers = qw("libgimpbase/gimpbase.h"
              "core/gimp.h"
              "core/gimpparamspecs-desc.h"
              "plug-in/gimppluginmanager-data.h"
              "gimppdb-query.h"
              "gimp-pdb-compat.h");

@procs = qw(procedural_db_temp_name
            procedural_db_dump
            procedural_db_query
            procedural_db_proc_exists
            procedural_db_proc_info
            procedural_db_proc_arg procedural_db_proc_val
	    procedural_db_get_data procedural_db_get_data_size
	    procedural_db_set_data);

%exports = (app => [@procs], lib => [@procs]);

$desc = 'Procedural database';
$doc_title = 'gimpproceduraldb';
$doc_short_desc = 'Functions for querying and changing procedural database (PDB) entries.';
$doc_long_desc = 'Functions for querying and changing procedural database (PDB) entries.';

1;