PerlCodeLibrary - a selection of functions for use by perl code embedded in
                                  a WebMake file.
                                  
                                              
                                              These functions allow code embedded in a <{perl}> or
                                              <{perlout}> section of a WebMake file to be used to script the
                                              generation of content.
                                              
                                                
                                                Each of these functions is defined both as a standalone function, or as a
                                                function on the PerlCode object. Code in one of the <{perl*}> sections can access this PerlCode object as the $self variable. If you plan to use WebMake from mod_perl or in a threaded
                                                environment, be sure to call them as methods on $self.
                                                
                                                  - 
                                                    $expandedtext = expand ($text);
                                                  
- 
                                                    
                                                      
                                                      Expand a block of text, interpreting any references, user tags, or any
                                                      other WebMake markup contained within.
                                                      
                                                     
- 
                                                      @names = content_matching ($pattern);
                                                    
- 
                                                      
                                                        
                                                        Find all items of content that match the glob pattern $pattern. If$patternbegins with the prefix RE:, it is treated as a regular expression. The list of items returned is not
                                                        in any logical order.
 
- 
                                                        @objs = content_names_to_objects (@names);
                                                      
- 
                                                        
                                                          
                                                          Given a list of content names, convert to the corresponding list of content
                                                          objects, ie. objects of type HTML::WebMake::Content.
 
- 
                                                          $obj = get_content_object ($name);
                                                        
- 
                                                          
                                                            
                                                            Given a content name, convert to the corresponding content object, ie.
                                                            objects of type HTML::WebMake::Content.
 
- 
                                                            @names = content_objects_to_names (@objs);
                                                          
- 
                                                            
                                                              
                                                              Given a list of objects of type HTML::WebMake::Content, convert to the corresponding list of content name strings.
 
- 
                                                              @sortedobjs = sort_content_objects ($sortstring, @objs);
                                                            
- 
                                                              
                                                                
                                                                Sort a list of content objects by the sort string $sortstring. See ''sorting.html'' in the WebMake documentation for details on sort
                                                                strings.
 
- 
                                                                @names = sorted_content_matching ($sortstring, $pattern);
                                                              
- 
                                                                
                                                                  
                                                                  Find all items of content that match the glob-style pattern $pattern. The list of items returned is ordered according to the sort string$sortstring. If$patternbegins with the prefix RE:, it is treated as a regular expression.
 
                                                                    
                                                                    See ''sorting.html'' in the WebMake documentation for details on sort
                                                                    strings.
                                                                     
                                                                      
                                                                      This, by the way, is essentially implemented as follows:
                                                                       
                                                                                 my @list = $self->content_matching ($pattern);
        @list = $self->content_names_to_objects (@list);
        @list = $self->sort_content_objects ($sortstring, @list);
        return $self->content_objects_to_names (@list);
- 
                                                                        $str = get_content ($name);
                                                                      
- 
                                                                        
                                                                          
                                                                          Get the item of content named $name. Equivalent to a $ {content_reference}.
 
- 
                                                                          @list = get_list ($name);
                                                                        
- 
                                                                          
                                                                            
                                                                            Get the item of content named, but in Perl list format. It is assumed that
                                                                            the list is stored in the content item in whitespace-separated format.
                                                                            
                                                                           
- 
                                                                            set_content ($name, $value);
                                                                          
- 
                                                                            
                                                                              
                                                                              Set a content chunk to the value provided. This content will not appear in
                                                                              a sitemap, and navigation links will never point to it.
                                                                               
                                                                                
                                                                                Returns the content object created.
                                                                                
                                                                               
- 
                                                                                set_list ($name, @values);
                                                                              
- 
                                                                                
                                                                                  
                                                                                  Set a content chunk to a list containing the values provided, separated by
                                                                                  spaces. This content will not appear in a sitemap, and navigation links
                                                                                  will never point to it.
                                                                                   
                                                                                    
                                                                                    Returns the content object created.
                                                                                    
                                                                                   
- 
                                                                                    set_mapped_content ($name, $value, $upname);
                                                                                  
- 
                                                                                    
                                                                                      
                                                                                      Set a content chunk to the value provided. This content will appear in a
                                                                                      sitemap and the navigation hierarchy. $upnameshould be the name of it's parent content item. This item must not be
                                                                                      metadata, or other dynamically-generated content; only first-class mapped
                                                                                      content can be used.
 
                                                                                        
                                                                                        Returns the content object created.
                                                                                        
                                                                                       
- 
                                                                                        del_content ($name);
                                                                                      
- 
                                                                                        
                                                                                          
                                                                                          Delete a named content chunk.
                                                                                          
                                                                                         
- 
                                                                                          @names = url_matching ($pattern);
                                                                                        
- 
                                                                                          
                                                                                            
                                                                                            Find all URLs (from <out> and <media> tags) whose name matches the glob-style pattern $pattern. The names of the URLs, not the URLs themselves, are returned. If$patternbegins with the prefix RE:, it is treated as a regular expression.
 
- 
                                                                                            $url = get_url ($name);
                                                                                          
- 
                                                                                            
                                                                                              
                                                                                              Get a named URL. Equivalent to an $ (url_reference).
                                                                                              
                                                                                             
- 
                                                                                              set_url ($name, $url);
                                                                                            
- 
                                                                                              
                                                                                                
                                                                                                Set an URL to the value provided.
                                                                                                
                                                                                               
- 
                                                                                                del_url ($name);
                                                                                              
- 
                                                                                                
                                                                                                  
                                                                                                  Delete an URL.
                                                                                                  
                                                                                                 
- 
                                                                                                  $listtext = make_list ($itemname, @namelist);
                                                                                                
- 
                                                                                                  
                                                                                                    
                                                                                                    Generate a list by iterating through the @namelist, setting the content itemitemto the current name, and interpreting the content chunk named$itemname. This content chunk should refer to 
                                                                                                      
                                                                                                      Each resulting block of content is appended to a $listtext, which is
                                                                                                      finally returned.
                                                                                                       
                                                                                                        
                                                                                                        See the news_site.wmksample site for an example of this in use.
 
- 
                                                                                                        define_tag ($tagname, \&handlerfn, @required_attributes);
                                                                                                      
- 
                                                                                                        
                                                                                                          
                                                                                                          Define a tag for use in content items. Any occurrences of this tag, with at
                                                                                                          least the set of attributes defined in @required_attributes, will cause the
                                                                                                          handler function referred to by handlerfn to be called.
                                                                                                           
                                                                                                            
                                                                                                            Handler functions are called as fcllows:
                                                                                                             
                                                                                                                       handler ($tagname, $attrs, $text, $perlcode);
 
                                                                                                                
                                                                                                                Where $tagnameis the name of the tag,$attrsis
                                                                                                                a reference to a hash containing the attribute names and the values used in
                                                                                                                the tag, and$textis the text between the start and end tags.
 
                                                                                                                   $perlcodeis the PerlCode object, allowing you to write proper
                                                                                                                  object-oriented code that can be run in a threaded environment or from
                                                                                                                  mod_perl. This can be ignored if you like.
 
                                                                                                                    
                                                                                                                    This function returns an empty string.
                                                                                                                    
                                                                                                                   
- 
                                                                                                                    define_empty_tag ($tagname, \&handlerfn, @required_attributes);
                                                                                                                  
- 
                                                                                                                    
                                                                                                                      
                                                                                                                      Define a tag for use in content items. This is identical to define_tag
                                                                                                                      above, but is intended for use to define ''empty'' tags, ie. tags which
                                                                                                                      occur alone, not as part of a start and end tag pair.
                                                                                                                       
                                                                                                                        
                                                                                                                        The handler in this case is called with an empty string for the
                                                                                                                        $textargument.
 
- 
                                                                                                                        define_preformat_tag ($tagname, \&handlerfn, @required_attributes);
                                                                                                                      
- 
                                                                                                                        
                                                                                                                          
                                                                                                                          Identical to define_tag, above, with one difference; these tags will be interpreted before the content undergoes any format conversion.
                                                                                                                          
                                                                                                                         
- 
                                                                                                                          define_empty_preformat_tag ($tagname, \&handlerfn, @required_attributes);
                                                                                                                        
- 
                                                                                                                          
                                                                                                                            
                                                                                                                            Identical to define_empty_tag, above, with one difference; these tags will be interpreted before the content undergoes any format conversion.
                                                                                                                            
                                                                                                                           
- 
                                                                                                                            define_wmk_tag ($tagname, \&handlerfn, @required_attributes);
                                                                                                                          
- 
                                                                                                                            
                                                                                                                              
                                                                                                                              Define a tag for use in the WebMake file.
                                                                                                                               
                                                                                                                                
                                                                                                                                Aside from operating on the WebMake file instead of inside content items,
                                                                                                                                this is otherwise identical to define_tag above,
                                                                                                                                
                                                                                                                               
- 
                                                                                                                                define_empty_wmk_tag ($tagname, \&handlerfn, @required_attributes);
                                                                                                                              
- 
                                                                                                                                
                                                                                                                                  
                                                                                                                                  Define an empty, aka. standalone, tag for use in the WebMake file.
                                                                                                                                   
                                                                                                                                    
                                                                                                                                    Aside from operating on the WebMake file instead of inside content items,
                                                                                                                                    this is otherwise identical to define_tag above,
                                                                                                                                    
                                                                                                                                   
- 
                                                                                                                                    $obj = get_root_content_object();
                                                                                                                                  
- 
                                                                                                                                    
                                                                                                                                      
                                                                                                                                      Get the content object representing the ''root'' of the site map. Returns
                                                                                                                                      undef if no root object exists, or the WebMake file does not contain a
                                                                                                                                      <sitemap> command.
                                                                                                                                      
                                                                                                                                     
- 
                                                                                                                                      $name = get_current_main_content();
                                                                                                                                    
- 
                                                                                                                                      
                                                                                                                                        
                                                                                                                                        Get the ''main'' content on the current output page. The ''main'' content
                                                                                                                                        is defined as the most recently referenced content item which (a) is not
                                                                                                                                        generated content (perl code, sitemaps, breadcrumb trails etc.), and (b)
                                                                                                                                        has its
                                                                                                                                        mapattribute set to ``true''.
 
                                                                                                                                          
                                                                                                                                          Note that this API should only be called from a deferred content reference;
                                                                                                                                          otherwise the ''main'' content item may not have been referenced by the
                                                                                                                                          time this API is called.
                                                                                                                                           
                                                                                                                                             undefis returned if no main content item has been referenced.
 
- 
                                                                                                                                            $main = get_webmake_main_object();
                                                                                                                                          
- 
                                                                                                                                            
                                                                                                                                              
                                                                                                                                              Get the current WebMake interpreter's instance of HTML::WebMake::Mainobject. Virtually all of WebMake's functionality and internals can be
                                                                                                                                              accessed through this.