NAME

Language::Dashrep - Dashrep is a versatile descriptive programming language based on hyphenated phrases being successively expanded into replacement text. It is a much more flexible alternative to using a template language. See www.Dashrep.org for details.

VERSION

Version 1.00

SYNOPSIS

Implements the Dashrep (TM) language, which is a versatile descriptive programming language that recursively expands English-like hyphenated phrases, such as rectangle-outline-attention-begin, into any kind of text or code, such as HTML, XML, JavaScript, C (subset), boilerplate-based text, etc. The resulting expanded text can be an HTML web page, an XML file, a JavaScript program, a boilerplate-based document, etc. See www.Dashrep.org for details.

The following sample code generates an entire web page, including a list-based table. The referenced Dashrep files are available at www.Dashrep.org.

use Language::Dashrep;

#-------------------------------------------
#  Read and import the file-based replacements.

foreach $file_name ( "dashrep-replacements-sample.txt" , "dashrep-replacements-html.txt" , "dashrep-replacements-language-en.txt" , "dashrep-replacements-case-info.txt" )
{
    if ( open ( INFILE , "<" . $file_name ) )
    {
        while( $input_line = <INFILE> )
        {
            chomp( $input_line ) ;
            $content_read_from_file .= $input_line . "\n" ;
        }
        close ( INFILE ) ;
        &dashrep_import_replacements( $content_read_from_file ) ;
    } else
    {
        die "Could not open file named $file_name for reading." ;
    }
}

#-------------------------------------------
#  Define situation-specific replacements.

&dashrep_define( "case-info-idlistparticipants" , "3,12,7,13,4" ) ;

#-------------------------------------------
#  Specify which page contents to generate,
#  and expand the parameters for that page.

&dashrep_define( "web-page-content" , &dashrep_expand_parameters( "page-participants-list" ) ) ;

#-------------------------------------------
#  Expand a single hyphenated phrase into an
#  entire web page, including a table that
#  lists the participants indicated above.

$html_code = &dashrep_expand_phrases( "entire-standard-web-page" ) ;
print $html_code ;

Although Dashrep code is not directly executable, it can generate executable code. Although it does not directly define loops, it generates lists in which any delimited (using commas and/or spaces) list of text strings (including integers) specifies the unique values for the list items. Although the Dashrep language does not directly implement a branching structure, the translated code can be completely changed at any level (including within lists) based on parameterized hyphenated phrases such as [-template-for-move-proposal-link-for-action-[-output-requested-action-]-].

The Dashrep language has been used to convert text files into MML- and XML-format files (for two books, The Creative Problem Solver's Toolbox and Ending The Hidden Unfairness In U.S. Elections), specify dynamically generated HTML pages (at www.VoteFair.org and www.NegotiationTool.com), generate JavaScript code (that Adobe Illustrator executed to generate vector graphics for use in the book Ending The Hidden Unfairness In U.S. Elections), generate invoices and packing slips, expand boilerplate-like text, and more.

The design goals for the Dashrep language were:

• Provide a convenient way to move descriptive code out of executable code.

• Keep it simple, and keep it flexible.

• Make the language speakable. (This characteristic is useful for various purposes, including circumventing keyboard-induced repetitive-stress injury, and using microphone-equipped mobile devices.)

EXPORT

The following subroutines are exported.

dashrep_define

dashrep_import_replacements

dashrep_get_replacement

dashrep_get_list_of_phrases

dashrep_expand_parameters

dashrep_expand_phrases

dashrep_expand_phrases_except_special

dashrep_expand_special_phrases

dashrep_set_runaway_limit

FUNCTIONS

dashrep_define

Associates a replacement text string with the specified hyphenated phrase.

First parameter is the hyphenated phrase. Second parameter is its replacement text string.

Return value is 1 if the definition is successful. Return value is zero if there are not exactly two parameters.

dashrep_import_replacements

Parses a text string that is written in the Dashrep language. Often the text string is the content of a text file. The text specifies the replacement text strings for specified hyphenated phrases.

First, and only, parameter is the text string that uses the Dashrep language.

Return value is the count for how many hyphenated phrases were defined (or redefined). Return value is zero if there is not exactly one parameter.

dashrep_get_replacement

Gets/returns the replacement text string that is associated with the specified hyphenated phrase.

First, and only, parameter is the hyphenated phrase.

Return value is the replacement string that is associated with the specified hyphenated phrase. Return value is an empty string if there is not exactly one parameter.

dashrep_get_list_of_phrases

Returns an array that lists all the hyphenated phrases that have been defined so far.

There are no parameters.

Return value is an array that lists all the hyphenated phrases that have been defined. Return value is an empty array if there is not exactly zero parameters.

dashrep_expand_parameters

Parses a text string that is written in the Dashrep language and handles parameter replacements and special operations. The special operations must be within "[- ... -]" text strings. If the supplied text string is just a hyphenated phrase, it is expanded to its replacement string. Otherwise, any hyphenated phrase that does not appear within the square-bracket pattern is not replaced. (Those hyphenated phrases must be replaced using either the dashrep_expand_phrases, dashrep_expand_phrases_except_special, or dashrep_expand_special_phrases subroutines.)

First, and only, parameter is the hyphenated phrase that is to be expanded.

Return value is the text string associated with the specified hyphenated phrase, after that text string has had its parameters expanded. Return value is an empty string if there is not exactly one parameter.

dashrep_generate_lists

Internal subroutine, not exported. It is only needed within the Dashrep module.

dashrep_expand_phrases_except_special

Expands the hyphenated phrases in a text string that is written in the Dashrep language--except the special (built-in) hyphenated phrases that handle spaces, hyphens, tabs, and line breaks, and except the parameterized phrases.

First, and only, parameter is the text string that uses the Dashrep language.

Return value is the expanded text string. Return value is an empty string if there is not exactly one parameter.

dashrep_expand_special_phrases

Expands only the the special (built-in) hyphenated phrases that handle hyphens, tabs, spaces and line breaks,

First, and only, parameter is the text string that contains the special hyphenated phrases.

Return value is the expanded text string. Return value is an empty string if there is not exactly one parameter.

dashrep_expand_phrases

Expands all the hyphenated phrases in a text string that is written in the Dashrep language. This includes expanding the special (built-in) hyphenated phrases that handle spaces, hyphens, and line breaks.

First, and only, parameter is the hyphenated phrase to be expanded.

Return value is the expanded text string. Return value is an empty string if there is not exactly one parameter.

dashrep_set_runaway_limit

Specifies the counter limit that attempts to identify an endless loop caused by a hyphenated phrase that has a replacement string that (directly or indirectly) contains the same replacement string.

First, and only, parameter is the new value to be used as a replacement limit.

Return value is one (1) if the assignment was successful. Return value is zero if there is not exactly one parameter, or if the new limit does not exceed 5.

dashrep_internal_endless_loop_info

Internal subroutine, not exported. It is only needed within the Dashrep module.

dashrep_internal_split_delimited_items

Internal subroutine, not exported. It is only needed within the Dashrep module.

AUTHOR

Richard Fobes, <fobes at CPAN.org>

BUGS

Please report any bugs or feature requests to bug-language-dashrep at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Language::Dashrep. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command:

perldoc Language::Dashrep

You can also look for information at:

• RT: CPAN's request tracker

  http://rt.cpan.org/NoAuth/Bugs.html?Dist=Language::Dashrep

• AnnoCPAN: Annotated CPAN documentation

  http://annocpan.org/dist/Language::Dashrep

• CPAN Ratings

  http://cpanratings.perl.org/d/Language::Dashrep

• Search CPAN

  http://search.cpan.org/dist/Language::Dashrep

You can find documentation for the Dashrep language at: www.Dashrep.org

TO DO

See www.Dashrep.org for descriptions of possible future developments.

ACKNOWLEDGEMENTS

Richard Fobes designed the Dashrep (TM) language and developed the original version of this code over a period of many years. Richard Fobes is the author of the book titled The Creative Problem Solver's Toolbox.

COPYRIGHT & LICENSE

Copyright 2009 Richard Fobes at www.Dashrep.org, all rights reserved.

You can redistribute and/or modify this library module under the Perl Artistic license, a copy of which is included in the LICENSE file.

Conversions of this code into other languages are also covered by the above license terms.

The Dashrep (TM) name is trademarked by Richard Fobes at www.Dashrep.org to prevent the name from being co-opted.

The Dashrep (TM) language is in the public domain.

cpanm Language::Dashrep

perl -MCPAN -e shell
install Language::Dashrep