NAME

Taco::Arg.pm - Taco argument management

SYNOPSIS

This module has three packages in it:

Taco::ArgTable        -A class implementing a table of arguments
Taco::ArgLayer        -A class implementing one layer in an ArgTable
Taco::ArgUtil         -Utility functions for managing arguments

# In a Taco tag's implementation function:
my $flavor = $G::params->val('flavor');
my $shoe_size = $G::params->val('shoe_size', 'my_func'); # Look only in the
                                                         # layer called "my_func"

DESCRIPTION

The Taco::Arg module contains classes that implement a table of arguments. It's somewhat like a 2-dimensional hash. Whenever you put a [[&tag(arg=value)]] in a Taco template, Taco will parse the tag for you, put the arguments into the ArgTable (the global ArgTable is $G::params), and then run your function. While your function is running, it has access to the $G::params object, which lets it get or set parameters, insert new ArgLayers, etc.

The ArgTable Class

• new Taco::ArgTable

  Returns a new empty ArgTable object.

• $table->insert_layer

  Puts a new empty ArgLayer in the table. The first argument is the layer after which you want the new layer to appear. The second argument, if present, is the name of the new layer. If the second argument is not present, a new name will be invented.

  Returns the name of the new ArgLayer.

• $table->new_temp(layer_name, key, value, key, value, ...)

  Puts a new temporary layer in the ArgTable, right after the layer called layer_name. This method returns an object of class Taco::ArgLayerName. This is a special object - when it goes out of scope, the layer associated with it will be deleted from the ArgTable. Because the scoping of this object is so significant, calling $table->new_temp in a void context (not assigning the result to a value) will cause Taco to die. So don't do that. If you don't want the layer to expire automatically, then you should probably use $table->insert_layer instead.

• $table->exists(key)

  Returns true if the given argument is the name of a key in the table. Takes an optional list of layers to look in.

• $table->set_arg(layer, key, value, key, value, ...)

  Sets the given keys to the given values in the given layer. Passes the real work to Taco::ArgLayer::set_arg.

• $table->add_arg(layer, key, value, key, value, ...)

  Adds the given keys, with the given values, to the given layer. Passes the real work to Taco::ArgLayer::add_arg.

• $table->layer_names

  Returns the current list of layer names, in order of highest priority to lowest.

• $table->get_layer(layer_name)

  Returns the ArgLayer object called layer_name.

• $table->set_layer(layer_name, layer)

  Replaces the layer called layer_name with the given layer. The table must already have a layer called layer_name.

• $table->delete_layer(layer_name)

  Deletes the layer called layer_name from the table.

• $table->layer_exists(layer_name)

  Returns true if there is a layer called layer_name in the table. See also exists to see whether a key exists in the table.

• $table->layer_containing(key)

  Returns the name of the layer containing the given key, or undef if no layers contain the given key.

• $table->keys

  Returns a list of all the keys in the table. Can take an optional list of layer names, in which case all the keys in those layers are returned, in no particular order.

• $table->show_me(verbose)

  Prints the names of the layers in an ArgTable to STDERR, in order from highest priority to lowest. If the verbose argument is true, each layer's ->show_me method will also be called, so you'll see all the data in the ArgTable.

• $table->to_hash(names_only)

  Returns the table's data in a list of key=>value pairs. If names_only is true, the keys returned will just be the names of the keys in the table. Otherwise the keys will be of the form "param-flavor.3*+", where 'param' is the 'place', '3' is the 'group', and '*+' is the type of the 'flavor' key. If none of these fancy things have values, setting the names_only flag will have no effect.

  Not implemented yet.

• $table->to_query_string(names_only)

  Similar to to_hash, but returns the data in the form of an URL query string.

  Not implemented yet.

• $table->to_arg_string(names_only)

  Similar to to_hash, but returns the data in the form of a template function argument string.

  Not implemented yet.

Simple Access methods

The following convenience methods can be used to look up table data more easily. They all share two characteristics: they take a key as input, with an optional list of layers to look for the data in. And they can be called in either the singular or plural form (i.e. $table->val(key) or $table->vals(key) ).

When they are called in the singular form, they return a single scalar value corresponding to the highest priority key of the given name. When they are called in the plural form, they return a list of scalars corresponding to the values in the highest layer containing a key of the given name.

All these routines return the undefined value if no layer contains the given key.

• $table->val(key)

  Looks up the key in the table and returns the value. See also ArgLayer::val.

• $table->group(key)

  Looks up the key in the table and returns the group. See also ArgLayer::group.

• $table->type(key)

  Looks up the key in the table and returns the type. See also ArgLayer::type.

• $table->place(key)

  Looks up the key in the table and returns the place. See also ArgLayer::place.

• $table->get_arg(key)

  Looks up the key in the table and returns a hash structure containing the group, type, place, and value. See also ArgLayer::get_arg.

The ArgLayer Class

An ArgLayer is a layer in an ArgTable. Here is its underlying data structure (don't assume that this is the structure of %$layer if $layer is an ArgLayer object, but it will be in $layer somewhere). This is provided for you as a conceptual aid.

{'flavor' => [
     {
        'val' => 'vanilla',
        'type' => '*',
        'group' => '1',
        'place' => '',
     },
  
     {
        'val' => 'chocolate',
        'type' => '*',
        'group' => '1',
        'place' => 'param',
     },
     
     {
        'val' => 'strawberry',
        'type' => '*',
        'group' => '',
        'place' => '',
     },
  ],

'color' => [
     {
        'val' => 'red',
        'type' => '*',
        'group' => '',
        'place' => '',
     },
  
     {
        'val' => 'blue',
        'type' => '*',
        'group' => '',
        'place' => '',
     },
  ],
};

The entries for 'flavor' and 'color' will be referred to here as "nodes."

Methods

• new Taco::ArgLayer

• new Taco::ArgLayer(%hash)

• new Taco::ArgLayer(@hash)

  Returns a new ArgLayer object. If a list is given as input, it will be taken as a list of key-value pairs and used to create the ArgLayer. In this case, &Taco::ArgUtil::parse will parse the incoming data.

• $layer->dup()

  Returns a copy of the ArgLayer object. The data in the copy is not linked to the data in the original, so if you change the data in one, the other will not be changed.

• $layer->exists( $key )

  Returns a boolean value based on whether the given key exists in the ArgLayer.

• $layer->delete( $key )

  Deletes all entries with the given name from the ArgLayer.

• $layer->get_args( $key )

  Returns a list of all entries in the ArgLayer for the given key.

• $layer->get_arg( $key )

  Same as $layer->get_args, but returns a scalar, which is the last element called $key in the ArgLayer.

• $layer->set_arg('name', 'value', name, value, ...)

• $layer->set_arg('name', {val=>...}, name, value, ...)

  Sets the values of the given keys in the ArgLayer. Clears all args in this layer with these names! The named nodes don't have to exist already. If a value is a hash reference, it will be assumed that you're passing a fully-formed argument node, such as the output of the &Taco::ArgUtil::parse function. Otherwise we'll assume that you're passing just the value, and we'll wrap it in a hash to make it an argument node.

  See also add_arg() and merge().

• $layer->add_arg('name', 'value', name, value, ...)

• $layer->add_arg('name', {val=>...}, name, value, ...)

  Adds these args to the end of this layer's given nodes. There don't have to be nodes with these names already. If a value is a hash reference, it will be assumed that you're passing a fully-formed argument node, such as the output of the &Taco::ArgUtil::parse function. Otherwise we'll assume that you're passing just the value, and we'll wrap it in a hash to make it an argument node.

  See also set_arg() and merge().

• $layer->merge( $layer2 )

  Pushes the contents of the ArgLayer $layer2 into $layer. The data in $layer2 will be put at the end of each node of $layer.

• $layer->keys()

  Returns a list containing the names of all the keys in the layer, in no particular order.

• $layer->each()

  Similar to Perl's each function for iterating over hashes, you can use it like this:

  while (($key, $value) = $layer->each) {
     # $key is a string
     # $value is a list of hashes
  }

• $layer->show_me()

  Prints a representation of the data in an ArgLayer to STDERR.

• $layer->to_hash( $name_only )

  Returns the layer's data in a list of key-value pairs. If names_only is true, the keys returned will just be the names of the keys in the table. Otherwise the keys will be of the form "param-flavor.3*+", where 'param' is the 'place', '3' is the 'group', and '*+' is the type of the 'flavor' key. If none of these fancy things have values, setting the names_only flag will have no effect.

• $layer->to_query_string( $name_only

  Similar to to_hash, but returns the data in the form of an URL query string.

  Not implemented yet.

• $layer->to_arg_string(names_only)

  Similar to to_hash, but returns the data in the form of a template function argument string.

  Not implemented yet.

• $layer->val('flavor')

• $layer->group('flavor')

• $layer->type('flavor')

• $layer->place('flavor')

  Documentation not written yet, see also $ArgTable-val('flavor')>, etc. It's very similar.

The ArgUtil Functions

All these functions are in the namespace Taco::ArgUtil. For example, you'd call the unparse function by doing &Taco::ArgUtil::unparse(...)

• unparse(name, ref, name_only)

  The inverse of &Taco::ArgUtil::parse, unparse translates a node in an ArgLayer to texty-hash format.

  name        - a string, the name of the node.
  ref         - a data structure in the format described below.
  name_only   - a boolean value: if true, omits the group, type, and place 
                information in the returned hash.  Prints all info by default.

  The 'ref' argument must be a reference to a list of hash references:

  $ref = [
     {'val' => 'beans',
      'group' => '3',
      'type'  => '*+',
      'place' => 'param',
     },
  
     {'val' => 'cheesecake',
      'type'  => '~',
     },
  
     {'val' => 'cheezo',
     },
  ];
  
  %hash = &Taco::ArgUtil::unparse('food', $ref);
  # Returns ('param-food.3*+' => 'beans', 'food~' => 'cheesecake', 'food' => 'cheezo').

• parse(name, ref, name_only)

• parse_query_string

• parse_post

• parse_arg_string

• url_unencode

  Translates "the+stuff%21" to "the stuff!"

• url_encode

  Translates "the stuff!" to "the+stuff%21"

AUTHOR

Ken Williams (ken@forum.swarthmore.edu)

Copyright (c) 1998 Swarthmore College. All rights reserved.