Home  |   Learn  |   Demo  |   Specs  |   Downloads  |   Convert  |   Discuss

Specifications for the Dashrep language

This page describes the specifications for the Dashrep language.

Fundamental characters & special text

Normal
priority
NameAppearanceDescription
1Comment*---  comment here   ---*Comments are ignored.  The text *--- indicates the beginning of a comment, and the text ---* indicates the end of the comment.  Comments cannot be nested; if they are, the results are unpredictable.  The comment directives are not recognized if they appear within parameter brackets.
1Comment/---  comment here   ---/Alternate written way to indicate a comment.
2Commentcomment-begin comment here comment-endAn alternate way — that is speakable — to insert a comment.  The comment-begin phrase indicates the beginning of a comment, and the comment-end phrase indicates the end of the comment.  Comments cannot be nested.
3Space Each space is significant as a delimiter for hyphenated phrases and words (without hyphens).
4Three or more adjacent hyphens----Indicates the end of a definition, in a situation where a hyphenated phrase is defined using the dashrep-definitions-begin directive (or the equivalent).
5Parameter[-   parameter   -]A parameter is expanded before the surrounding text is expanded.  The first-encountered innermost parameter is expanded first.  Spaces at the beginning and end of the parameter are removed, which allows the expanded text to become part of a hyphenated phrase, which in turn enables branching and indexing.
5Phrase name in parameter brackets[- user-phrase-name -]A hyphenated phrase within parameter brackets is expanded according to the phrase's definition (which itself can contain parameters).  If the phrase name is not defined, it is left as-is, and the parameter brackets are removed.  Spaces at the beginning and end of the parameter are removed, which allows the expanded text to become part of a hyphenated phrase, which in turn enables branching and indexing.
6Action[- zero-one-multiple 3 -]If the first (left-most) hyphenated phrase inside a parameter is one of the recognized actions (listed below), and the action is followed by text that the action knows how to handle, the action is performed.  Some actions produce text that becomes the replacement for the parameter, whereas other actions operate on phrases or files and do not produce any text.
7Hyphenated phraseneeded-text-stringA hyphen surrounded by non-space characters (and also excluding square brackets) is recognized as a hyphenated phrase.  (A hyphen and a dash are different names for the same symbol.)  A phrase name is case-sensitive.  Lowercase-only names are recommended, but not required.  Speakable names are recommended, but not required.  The use of nouns before, rather than after, adjectives is recommended; this convention (for example rectangle-large-begin instead of large-rectangle-begin) is typical of many spoken languages, but not English.  The first character cannot be a hyphen and cannot be a digit.  The last character cannot be a hyphen.
8Colonneeded-text-string: definition here   ----When there is text after the dashrep-definitions-begin directive, a colon can appear at the end of the phrase being defined.  This convention is optional.  It offers the advantage of making it easier to search for where a hyphenated phrase is defined, without also finding each place it is used.
9New line or line breakone line line-break next lineWhen a new line begins, it is replaced with a space.  When a new line needs to be inserted into the resulting text, the new-line phrase (explained below) can be used.  If a line break in the target language (such as HTML) is needed, the phrase line-break can be used to insert the appropriate target-specific code (which in HTML is the
tag).
10Undefined hyphenated phrasequite-talkative parrotIf a hyphenated phrase has not been defined, it is not translated; it remains unchanged.  If a hyphenated phrase has been defined and is now empty, the hyphenated phrase will disapper.
11hyphen-herehyphen-hereExplained below.
12non-breaking-spacenon-breaking-spaceExplained below.
13tab-heretab-hereExplained below.
14empty-lineempty-lineExplained below.
15new-linenew-lineExplained below.
16no-spaceno-spaceExplained below.
17one-spaceone-spaceExplained below.

Dashrep spoken words

WordEquivalenceDescription
combee*---Indicates the beginning of a comment.
comenn---*Indicates the end of a comment.
fenhyphen with no adjacent spacesInserts a hyphen between words (or other adjacent characters).
dashbee(no equivalence)Indicates the beginning of a phrase that needs to be hyphenated.  For example, dashbee info about dolphin dashenn becomes info-about-dolphin.
dashenn(no equivalence)Indicates the end of a phrase that needs to be hyphenated.
dashnex(no equivalence)Indicates the end of one phrase that needs to be hyphenated and the beginning of another phrase that needs to be hyphenated.  For example, dashbee info about dolphin dashnex copy of info about dolphin dashenn becomes info-about-dolphin copy-of-info-about-dolphin.
ambee[-Indicates the beginning of a parameter.
amenn-]Indicates the end of a parameter.
fenambee-[-Indicates the continuation of a hyphenated phrase that includes a parameter as part of the phrase.  For example, info-for-dolphin-named fenambee dolphin-name amennfen becomes info-for-dolphin-named-leaper if dolphin-name equals leaper.
amennfen-]-Indicates the end of a parameter that, when it is translated, becomes part of a hyphenated phrase.
amennfenambee-]-[-Indicates the continuation of a hyphenated phrase that includes two adjacent parameters as part of the phrase.  For example, info-at-row-and-column fenambee row-number amennfenambee column-number amenn becomes info-at-row-and-column-2-3 if row-number equals 2 and column-number equals 3.
linbray(line break)Indicates that a line break should be inserted here.  If the resulting text goes through additional translation steps, the inserted line break is likely to be converted into a space (rather than remaining as a line break).

Directives versus actions versus phrases

Phrase

A phrase is a hyphenated phrase that has a definition, and the definition is inserted in place of the hyphenated phrase.  Phrases are recognized regardless of whether or not they appear within parameter brackets.

Directive

A directive is a hyphenated phrase that triggers a special functionality in the translation.  Directives are not recognized if they appear within parameter brackets.

Action

An action is a hyphenated phrase that has special significance when it appears at the beginning of text that is enclosed by parameter brackets.  An action is not recognized if it is not within parameter brackets, or if it is not the first hyphenated phrase in the parameter brackets.

Hyphens, spaces, lines, & square brackets

hyphen-here

This directive inserts a hyphen, with no adjacent spaces, where it appears within text that is expanded (translated).  Internally this phrase is defined as no-space - no-space.

character-hyphen

This pre-defined phrase contains one hyphen character (-).

four-hyphens

This pre-defined phrase contains four adjacent hyphen characters (----).

no-space

This directive removes any spaces (concatenation) after all other phrases have been replaced (during expansion).  If the one-space directive is adjacent, the no-space directive is ignored.

empty-text

This pre-defined phrase contains no text.  To clear a phrase, use the action clear-phrase.  To test whether a phrase's definition is empty, use the action yes-or-no-empty-phrase.

one-space

This directive inserts a single space.  If the no-space directive is adjacent, the no-space directive is ignored.  Repeating this directive does not insert multiple adjacent spaces, just a single space.  If multiple spaces are needed, a phrase such as four-spaces can be defined as multiple spaces, and then those spaces will be inserted where the text appears.

character-space

This pre-defined phrase contains one space character.

non-breaking-space

This directive inserts a non-breaking space where it is encountered within text that is expanded.  This text is inserted even if the no-space directive is adjacent.  The default value that is inserted, which is intended for use in HTML, is  .

new-line

This directive inserts a newline character, which specifies the start of a new line.  If the target language, such as HTML, ignores line breaks, the line break will not be visible in the displayed result.

empty-line

This directive specifies an empty line, which is equivalent to two adjacent new-line directives.

line-break

This phrase should be defined as text that, in turn, specifies a line break in the target language.

Example: If the target language is HTML, normally this phrase would be defined as <br />.

character-newline

This pre-defined phrase contains a newline character.  In some other programming languages this character is represented by the text \n.

character-open-square-bracket

This pre-defined phrase contains the open-square-bracket character ([).

character-close-square-bracket

This pre-defined phrase contains the close-square-bracket character (]).

character-tab

This pre-defined phrase contains a tab character.  In some other programming languages this character is represented by the text \t.

character-underscore

This pre-defined phrase contains one underscore character (_).

Expansion-related phrases

expand-text

This action expands ("translates") the contents of the first phrase and puts the results into the second phrase.  This action provides a way to separately expand the same phrase repeatedly, such as for generating multiple items that will appear in different table cells, and for expanding the same file-path template to point to different file paths.  If the name of the phrase that needs to be expanded can change, then the first phrase can be surrounded with ambee and amenn delimiters.  If needed, the expanded result can be inserted inline (into the code that contains this action) by following this action with the expanded phrase name (without surrounding am-bee and am-enn delimiters).  The first phrase name and the second phrase name can be the same (without automatically causing an endless loop).

In addition to replacing hyphenated phrase names with their associated definitions, the expansion also replaces each occurrence of a specially identified hyphenated phrase with the definition of that phrase.  The specially identified hyphenated phrases begin and end with angle brackets (< and >) and contain at least one underscore (_), such as <special_content>.  For each such specially identified hyphenated phrase, the underscores are (internally) replaced with hyphens, and if the resulting hyphenated phrase has a definition, then that definition is inserted in place of the specially identified hyphenated phrase (but the underscores are not changed if there is no associated phrase).  The special text <character_hyphen> is replaced by a hyphen (-) and is especially useful for handling text that contains Dashrep phrases that must not be replaced.  The special text items <no_space> and <new_line> provide functionality that is equivalent to the no-space and new-line directives.

This action does the same translation of Dashrep text as the default expansion of Dashrep text, so this action is usually only needed for complex expansions of Dashrep code.

copy-definition-of-named-phrase

This action copies to the second operand the definition of the phrase that is named in the definition of the first operand.  This action is only needed when the name of a phrase is being supplied as the defintion of another phrase.  In one sense this action provides a way to immediately expand a phrase by just one level of recursion, without also expanding any parameter phrases within the definition.  The first operand must contain only a single phrase name.  The named phrase can contain anything, and that content is copied without being expanded.

Text-transfer-related phrases

get-cgi-information

This action gets the CGI (Common Gateway Interface) input information — which was sent from the browser to the server — and puts that information into phrases that begin their names with the prefix input- and use the supplied information names as the remainder of each name.  In addition, the full raw CGI text in put into a phrase named input-raw-cgi-string.

Example: If a user clicks a link that has the URL www.example.org/cgi-bin/value%1Fone=123&value%2Dtwo=abc+def then the new phrase input-value_one will contain the text 123 and input-value-two will contain the text abc def and input-raw-cgi-string will contain the text value%1Fone=123&value%2Dtwo=abc+def.  As indicated by this example, the CGI conversion converts %1F into _ (underscore) and converts %20 into a hyphen and converts + into a space.

standard-output

This phrase contains the text that is written to standard output if — but only if — this phrase is not empty.  If this phrase is empty, then the normal convention is followed, which means that the expanded text is written to standard output.  In other programming languages the print statement is used to write text to standard output.  This phrase provides a way to completely control what is sent to standard output, without unexpected insertions of text caused by warnings and undefined Dashrep code.

copy-text

This action copies the definition of the first hyphenated phrase into the definition of the second hyphenated phrase.  This action must be followed by two phrase names, not one.  The previous definition of the second hyphenated phrase is deleted.

put-into-phrase

This action copies into the first hyphenated phrase the text that follows the first hyphenated phrase, up to the end of the parameter brackets.  The text can contain hyphens if they are not adjacent to an open angle bracket or close angle bracket.  Trailing spaces and trailing hyphens are ignored.

Example: After expanding the code ambee put-into-phrase target-phrase whale dolphin starfish amenn the phrase target-phrase will contain whale dolphin starfish.

copy-listed-words-to-phrases-named-in-pattern

This action copies multiple phrase definitions.  Specifically space-delimited words in the first phrase are copied to multiple phrase names, where the phrase names have the pattern specified in the second phrase.  The pattern must contain characters between the text ambee- (or fenambee-) and the text -amenn (or amennfen-), and these characters must be the name of a phrase that contains the space-delimited words that will be inserted at that position within the pattern.  If the phrase that contains the target word list contains only a single word without any spaces, then only one item will be copied.  If the list is empty, nothing will be copied.  If the number of words in the first phrase is different from the number of words in the list that is specified within the pattern, the copying will stop when the shorter list is exhausted.  This action is useful for copying a long list fast, without needing to use a separate Dashrep action for each item copied.

Example: If the first phrase contains dolphin buffalo bear, and the second phrase contains item-ambee-list-of-numbers-as-text-amenn, and the phrase list-of-numbers-as-text contains the text one two three, then the phrase item-one will contain dolphin and the phrase item-two will contain buffalo and the phrase item-three will contain bear.

append-text

This action appends the definition of the first phrase to the end of the definition of the second phrase, and inserts a single space between the existing text and the appended text.  The two phrase names can be the same.  If the target phrase is initially empty, the space is not inserted.

append-text-no-space

This action appends the definition of the first phrase to the end of the definition of the second phrase, without inserting a separating space, and without removing any adjacent trailing spaces (in the second phrase definition) or leading spaces (in the first phrase definition).  The two phrase names can be the same.

append-new-line

This action appends a newline code to the end of a definition.

append-repeatedly-using-count

This action repeatedly appends the definition of the first hyphenated phrase to the end of the definition of the second hyphenated phrase, until the number of copies specified in the third operand have been inserted.  Spaces separate the appended text items.  This action must be followed by two phrase names and a positive integer number.  This action avoids complications that can arise if the text being copied should not be expanded, and is much faster than using the use-handler-with-each-word-in-phrase.

append-multiple-from-phrases-named-in-pattern

This action appends multiple phrase definitions onto the end of the definition of the second phrase.  The pattern for the multiple phrase names is specified in the first phrase.  The pattern must contain characters between the text ambee- and the text -amenn, and these characters must be the name of a phrase that contains the space-delimited words that will be inserted at that position within the pattern.  (Although fenambee or amennfen might normally be used to indicate the inclusion of a hyphen, they are not recognized by this action.)  If the phrase that contains the word list contains only a single word without any spaces, then only one item will be appended.  If the list is empty, nothing will be appended.  This action is useful for building a long list fast, without needing to use a separate Dashrep action for each item appended.

Example:  If the first phrase contains the text item-ambee-list-of-numbers-as-text-amenn and the phrase list-of-numbers-as-text contains the text one two three and the second phrase already contains the text dolphin and the phrase item-one contains buffalo and the phrase item-two contains bear and the phrase item-three contains eagle then the second phrase will contain dolphin buffalo bear eagle.

prepend-text

This action prepends the definition of the first phrase into the beginning of the definition of the second phrase, without inserting a separating space.  If the target phrase is initially empty, the space is not inserted.

prepend-text-no-space

This action prepends the definition of the first phrase into the beginning of the definition of the second phrase, and inserts a single space between the prepended text and the existing text.

Clear & delete phrases

clear-phrase

This action clears the definition for the specified phrase.  The specified phrase continues to be defined, but the definition is empty.

clear-listed-phrases

This action clears the definitions for the phrases that are named in the specified phrase.  The phrases continue to exist, but their definitions are empty.

delete-listed-phrases

This action deletes (removes) the phrases that are named in the specified phrase.  This phrase is related to the action clear-listed-phrases except that instead of just clearing the definition, this delete version removes (deletes) the phrase so that it will not be recognized.  This action is useful when the text being expanded contains phrases that should remain in the text if they are not defined, instead of being replaced by their empty definitions.

Decision-related phrases

if-yes-begin

This action looks at the first space-delimited word, and if it is yes (or contains that word) then this action removes all the text between the next occurrences of [-if-else-] and [-if-end-] (and removes the [-if-else-] and [-if-end-] text items).  Otherwise (if the first word that follows does not contain yes) then this action removes all the text between itself (the action name) and the next occurrence of [-if-else-] (and removes the [-if-else-] and [-if-end-] text items).  This action provides a major branching capability.  However, the action if-yes-begin and the text [-if-else-] and the text [-if-end-] cannot be nested (as allowed in most programming languages).  Specifically, an inner if action must not appear within an outer if action within the same Dashrep code.  The functional nesting of if branches is allowed if the inner if action appears within a separate phrase that is not expanded until after the outer if directive is handled.

if-no-begin

This action works similar to the action if-yes-begin except that the word no is used instead of the word yes.

if-else

This special text is recognized by the action if-yes-begin and the action if-no-begin.  It must be enclosed by parameter brackets in order to be recognized.

if-end

This special text is recognized by the action if-yes-begin and the action if-no-begin.  It must be enclosed by parameter brackets in order to be recognized.

yes-or-no-empty-phrase

This action supplies yes if the following specified phrase is empty, and supplies no otherwise.  A phrase is empty if it contains nothing, or if it contains only spaces, or if it has not yet been defined.  If no operand is supplied (which occurs if the intended operand is a parameter phrase that supplies no text), then this action supplies yes.

yes-or-no-same-two-phrase-definitions

This action supplies yes if the following two phrase contain the same text, and supplies no otherwise.

yes-or-no-same-two-words

This action supplies yes if the following two space-delimited words are the same, and supplies no otherwise. If only one word is supplied, or if no word is supplied, then this action supplies no.

yes-or-no-opposite

This action supplies no if the text that follows contains the word yes, and otherwise this action supplies yes.  If no operand is supplied (which occurs if the intended operand is a parameter phrase that supplies no text), then this action supplies yes.

yes-if-all-yes

This action supplies yes if the following text contains the text yes or any number of yes words (either with or without separating spaces) and no other (non-space) characters, and supplies no otherwise.  This action is similar to the logic AND operator in other languages.  If there are no operands, this action supplies no.

yes-if-any-yes

This action supplies yes if the following text contains the text yes, and supplies no otherwise.  This action is similar to the logic OR operator in other languages.  If there are no operands, this action supplies no.

no-if-any-no

This action supplies no if the following text contains the text no, and supplies yes otherwise.  If there are no operands, this action supplies yes.

yes-if-not-no

This action supplies no if the following word (space-delimited characters) is no, and supplies yes otherwise.  This action is useful if the word can be something other than yes or no, but only no is significant.  If there are no operands, this action supplies yes.

no-if-not-yes

This action supplies yes if the following word (space-delimited characters) is yes, and supplies no otherwise.  This action is useful if the word can be something other than yes or no, but only yes is significant.  If there are no operands, this action supplies no.

Loop-related phrases

use-handler-with-each-word-in-phrase

This action expands the named handler (which is just a named phrase) multiple times, once for each word in the second phrase.  Each time the handler is expanded, the phrase 53 contains the next word.  Nothing is supplied as a result.  Instead, the handler needs to store any changes in specified phrases (or in specified files).  The content in the second phrase must not change during the time this expansion is being done.  If the content in the second phrase begins or ends with a space, the leading and trailing spaces will be removed (even though this content is otherwise treated as a read-only list).

Most commonly this action is used to generate a list, in which case the handler either appends text to a single phrase, or generates multiple new phrases (which are typically named using the content of the phrase word-to-use-in-handler as part of the phrase name).  Internally this action inserts parameter phrases that make use of an internal dashrep action named use-handler-with-each-word-in-phrase-currently-at-character-position.

word-to-use-in-handler

This phrase is used with the action use-handler-with-each-word-in-phrase.

Word-related phrases

get-count-of-words

This action counts the number of words in the definition of a specified phrase, and supplies the count as its result.  Words are regarded as text items that do not contain any spaces, and which are separated by one (or more) spaces.  If the definition contains only spaces, or is empty, the value 0 (zero) is supplied.

get-word-at-position

This action supplies a word that is contained at the specified word position (not character position) within the second phrase.  The word position is supplied as an integer number.  The word positions are numbered starting with 1 at the first word position.  Words are regarded as text items that do not contain any spaces, and which are separated by one (or more) spaces. Example: If the first phrase contains whale dolphin starfish jellyfish dolphin and the second operand is 2 then the supplied value is dolphin.

get-position-of-word

This action searches for a specified word within text that contains the space-delimited word, and supplies the word position (not character position) of the first match.  If there is no match, a 0 (zero) is supplied.  The word positions are numbered starting with 1 at the first word position.  The supplied word is the word in the first phrase. Example: If the first phrase contains the word dolphin and the second phrase contains whale dolphin starfish jellyfish dolphin then the supplied value is 2.

copy-word-at-position

This action copies one word from the definition of the first phrase into the definition of the second phrase, with the word position being specified by a number.  A position number of 1 indicates the first word in the definition.  The words are any sequence of characters that does not include a space, and spaces are regarded as the separation between each pair of words.

copy-words-from-position-to-position

This action gets the space-delimited words from the first phrase starting at the position indicated by the integer number in the third parameter, and ending at the position indicated by the integer number in the fourth parameter.  The word positions are numbered starting with 1 at the beginning.  If the ending number is greater than the number of words, then the entire remainder of the phrase is retrieved (which means that using a large second number such as 9999 eliminates needing to know how many words are in the phrase).  The first two phrase names can be the same.

copy-words-offset-skip

This action copies some space-delimited words from the first phrase to the second phrase using the skip interval specified by the integer number in the fourth operand, starting with the offset integer number specified in the third operand.  The skip interval is the distance between copied words.  If the offset position and skip interval are both zero, then all the words are copied.  The word positions are numbered starting with 1 at the beginning.  The first two phrase names can be the same.

Example: If the first phrase contains 1 2 3 4 5 6 7 8 and the third operand is 3 and the fourth operand is 1 then the second phrase will contain 3 5 7.

List-manipulation phrases

copy-words-found-in-both-lists

This action copies into the definition of the third phrase any words that appear in both of the indicated phrase definitions.  If a word appears more than once in either list, and it appears in both lists, it appears only once in the result.  The order of the words in the result matches the order in which those words first appear in the first list.

Example: If the first phrase definition is abc 123 def 456 and the second definition is def 789 xyz 123 then the third phrase is defined as 123 def.

copy-words-found-in-either-list

This action copies into the definition of the third phrase the words that appear in either of the indicated phrase definitions, without repeating any word.

Example: If the first phrase definition is abc 123 def 456 and the second definition is def 789 xyz 123 then the third phrase is defined as abc 123 def 456 xyz 789 (although the word order can be different).

copy-words-found-only-in-first-list

This action copies into the definition of the third phrase any words that appear in the first phrase definition but do not appear in the second phrase definition.  The order of words in the target phrase matches the order of words in the first list.  If a word appears multiple times in the first list and it qualifies to appear in the result, that word appears multiple times, in the same order as in the first list.  The action copy-words-unique-only can be used to eliminate duplicate words.

Example: If the first phrase definition is abc 123 def 456 abc and the second definition is def 789 xyz 123 then the third phrase is defined as abc 456 abc.

copy-words-that-begin-with-text

This action looks at all the words in the first phrase and identifies the words that begin with the text in the third phrase, and puts those partially (or fully) matching words into the second phrase, with a space between each phrase name.

Example: If the first phrase contains honeybees bees honey hives beehives and the third phrase contains bee then the second phrase will contain bees beehives.

copy-words-that-begin-with-listed-words

This action looks at all the words in the first phrase and identifies the words that begin with text that match any of the words listed in the third phrase, and puts those partially (or fully) matching words into the second phrase, with a space between each phrase name.

Example: If the first phrase contains honeybees bees honey hives beehives and the third phrase contains bee hive then the second phrase will contain bees hives beehives.

copy-words-that-contain-listed-words

This action looks at all the words in the first phrase and identifies the words that contain text that match any of the words listed in the third phrase, and puts those partially (or fully) matching words into the second phrase, with a space between each phrase name.

Example: If the first phrase contains honeybees bees honey hives beehives and the third phrase contains bee hive then the second phrase will contain honeybees bees hives beehives (but not honey ).

copy-words-unique-only

This action copies from the definition of the first phrase all the words that appear in that definition, but without repeating any words that are repeated in the definition.  The position of the first occurrence of a word determines the position of that word in the result list.  In addition, the special phrase list-of-unique-word-counts contains a list of counts that indicate how many times each word (in the result list) occurs in the original list.  In addition, the special phrase list-of-pointers-to-unique-words contains a list of pointers to the space-delimited words in the original list, and these pointers are in the same sequence as the result list, but without including any positions of words that are duplicate words.  The pointer list is useful when the original list is in the same sequence as other lists that contain other information about the same items, and a specific number of unique items at the beginning of the result list need to be identified in a way that does not lose the association between the unique items and the other information in the other lists.

Example: If the first phrase definition is dolphin whale whale starfish dolphin then the second phrase is defined as dolphin whale starfish.  In addition, the phrase list-of-unique-word-counts contains 2 2 1.  In addition, the phrase list-of-pointers-to-unique-words contains 1 2 4.

list-of-unique-word-counts

This phrase contains a list of word counts for the unique words found by the most recent use of the action copy-words-unique-only.  If that action has not yet been used, this phrase is empty.  See copy-words-unique-only for details.

list-of-pointers-to-unique-words

This phrase contains a list of word pointers for the unique words found by the most recent use of the action copy-words-unique-only.  If that action has not yet been used, this phrase is empty.  See copy-words-unique-only for details.

copy-words-order-reversed

This action gets the space-delimited words in the first phrase, and reverses their order (sequence), and puts those reverse-ordered words into the second phrase.  The two phrase names can be the same.

Example: If the first phrase contains dolphin whale octopus then the second phrase will contain octopus whale dolphin.

copy-words-sort-numeric

This action copies from a phrase definition to the specified phrase and numerically sorts the list of (space-delimited) numbers.  The two phrase names can be the same.

Example: If the first phrase contains the text 7 1 5 3 12 then the text placed into the second phrase will be 1 3 5 7 12.

copy-words-rearrange-using-order-sort-numeric

This action gets the space-delimited words in the first phrase, and moves those words into the second phrase using the numeric sort order specified in the third phrase.  The first two phrase names can be the same.

Example: If the first phrase contains the text seven one five three twelve and the third phrase contains the text 7 1 5 3 12 then the text placed into the second phrase will be one three five seven twelve.

copy-words-sort-alphabetic

This action gets the space-delimited words in the first phrase, and sorts those words alphabetically, and puts those sorted words into the second phrase.  The two phrase names can be the same.

Example: If the first phrase contains the text dolphin whale seal then the text placed into the second phrase will be dolphin seal whale.

copy-words-rearrange-using-order-sort-alphabetic

This action gets the space-delimited words in the first phrase, and moves those words into the second phrase using the alphabetical sort order specified by the words in the third phrase.  The first two phrase names can be the same.

Example: If the first phrase contains the text Nikola_Tesla Abe_Lincoln Thomas_Jefferson Paul_MacCready and the third phrase contains the text tesla_nikola jefferson_thomas da_vinci_leonardo maccready_paul then the text placed into the second phrase will be Leonardo_da_Vinci Thomas_Jefferson Paul_MacCready Nikola_Tesla.

generate-counts-from-integer-to-integer

This action generates a list of integers and puts them into the definition of the third phrase.  The supplied integers indicate the starting and ending values.

Example: generate-counts-from-integer-to-integer 1 10 one-to-ten defines the phrase one-to-ten as 1 2 3 4 5 6 7 8 9 10.

generate-every-pairwise-combination-of-words

This action generates two word-based lists that contain every possible pair of words in the first phrase and the second phrase.

Example: If the first phrase contains dolphin eagle bear and the second phrase contains leaps flies ambles then the third phrase will contain dolphin dolphin dolphin eagle eagle eagle bear bear bear and the fourth phrase will contain leaps flies ambles leaps flies ambles leaps flies ambles.

generate-every-ordered-pairwise-combination-of-words

This action generates two word-based lists that are pairs of the words in the first phrase, but in each pair of words the word in first list appears before the word in the second list.-This action is useful for doing pairwise counting.

Example: If the first phrase contains dolphin whale starfish octopus then the second phrase will contain dolphin dolphin dolphin whale whale starfish and the third phrase will contain whale starfish octopus starfish octopus octopus.

generate-list-of-all-dashrep-phrases

This action generates a list of all the defined phrase names, using a space between adjacent phrase names, and puts that list into the specified phrase name.  For security purposes this action can be disabled.  The generated list excludes the phrase name four-hyphens.

Character-related phrases

get-count-of-characters

This action counts the number of characters in the definition that is associated with the specified phrase, and supplies the number as its result.  Spaces and non-visible characters (such as the newline character) are included in the count.

get-characters-from-position-to-position

This action gets the characters from the specified phrase starting at the position indicated by the first number, and ending at the position indicated by the second number.  The character positions are numbered starting with 1 at the first character position.  If the second number is greater than the number of characters, then the entire remainder of the phrase is retrieved (which means that using a large second number such as 9999 eliminates needing to know how many characters are in the phrase).

copy-characters-from-position-to-position

This action copies specified characters from the first phrase to the second phrase.  The third and fourth operands indicate the starting and ending character positions, with the first character position being numbered one (1).  The starting character position must not be larger than the ending character position.  The first two phrase names can be the same.

copy-without-extra-spaces

This action removes multiple adjacent spaces so that only single spaces occur, and removes all spaces at the beginning and end of the text.  The first phrase specifies the source text, and the second phrase specifies the destination.  The two phrase names can be the same.

copy-lowercase-only

This action copies the definition of the first phrase into the definition of the second phrase, but changes any uppercase characters (such as A and B) into lowercase characters (such as a and b).  The two phrase names can be the same.

copy-uppercase-only

This action copies the definition of the first phrase into the definition of the second phrase, but changes any lowercase characters (such as a and b) into uppercase characters (such as A and B).  The two phrase names can be the same.

copy-initial-caps

This action copies the definition of the first phrase into the definition of the second phrase, but changes the first letter of each space-delimited word into its equivalent uppercase letter.  The remaining letters within the same word are not changed.  If the first character after a space is a symbol or digit, that word remains unchanged.  If the definition begins with a letter, that letter is converted to uppercase, even though it does not follow a space.  The two phrase names can be the same.

copy-zero-pad-left-to-length

This action copies text from the definition of the first phrase into the definition of the second phrase and inserts zeros (0) to the left of the copied characters.  The resulting padded text has the length specified by the number in the third operand.  Normally this action is used with numbers, but the action does not check whether the copied text is a number.

encode-as-cgi-parameter

This action converts symbols and other non-alphabetic and non-digit characters into the special format that allows the text to be passed to a web server as a CGI parameter.  As an example, a comma is represented as %2c.  The two phrase names can be the same.

decode-from-cgi-parameter

This action converts a CGI parameter into normal (non-encoded) characters.  This action is the inverse of the copy-from-phrase-to-phrase-and-encode-as-cgi-parameter action.  As an example, the text %2c is converted into a space character.  The two phrase names can be the same.

convert-unicode-to-html-entities

This action copies all the text from the first phrase into the second phrase but converts non-ASCII characters into HTML entities.  The HTML entities use decimal numbers, which means that open double quotation marks become “ and ”.

Search-and-replace-related phrases

get-position-of-matching-text

This action searches for the characters from the first phrase, and performs the search within the second phrase, and supplies the character position of the first match.  If there is no match, a 0 (zero) is supplied.  The character positions are numbered starting with 1 at the first character position.

copy-and-replace

This action replaces each occurrence of the third phrase with the text in the fourth phrase, based on the text in the first phrase, and places the result into the second phrase.  If the replacement phrase contains the search phrase, nothing is changed, and a warning is put into the trace information because that could cause an endless loop.  The special phrases character-space and character-hyphen and character-newline are useful here (because the language does not have ways to define those characters).  The first two phrase names can be the same.

copy-and-replace-using-paired-listed-words

This action copies the definition of the first phrase into the definition of the second phrase, but replaces some text strings with associated text strings, using paired words in the third operand.  The paired words in the third operand are delimited by spaces, and the first word in each pair specifies what text to find, and the second word in each pair specifies the replacement text for that found word.

Example: To replace named HTML entities and some special characters with their unicode equivalent entities, the third phrase can contain text such as the following: &amp; &#38; &lt; &#60; < &#60 &gt; &#62; > &#62; &ldquo; &#8220; &rdquo; &#8221; &lsquo; &#8216; &rsquo; &#8217; &quot; &#34; " &#34; &apos; &#39; ' &#39; &nbsp; &#160;

Another example: To identify a numeric pattern by converting all digits into the digit nine, the third phrase can contain the following text: 0 9 1 9 2 9 3 9 4 9 5 9 6 9 7 9 8 9 

As these examples illustrate, the words can include single characters.  Obviously none of the words in the third phrase can contain a space.  If any searched words or any inserted words contain text that matches other searched words, the result becomes unpredictable.  The first two phrase names can be the same.

generate-positions-of-delimiter

This action searches for the text contained in the first phrase, and performs repeated searches within the second phrase, and puts into the third phrase the list of character positions of all the matches.  If there is no match, the list is empty.  The character positions are numbered starting with 1 at the first character position, and the numbers indicate the position of the first character in the matching text.

generate-positions-of-listed-words

This action searches for any of the space-delimited words contained in the first phrase, and finds those text items within the second phrase, and puts into the third phrase the list of beginning and ending character positions of all the matches.  The spaces in the first phrase are needed to separate the text items, but spaces in the second phrase are not needed in order for a text item to match.  If there is no match, the generated list is empty.  The character positions are numbered starting with 1 at the first character position, and the listed numbers indicate the beginning and ending character positions of any matching text.

Example: If the first phrase contains fish bird and the second phrase contains birds songbird fish clownfish then the third phrase will contain 1 4 11 14 16 19 26 29.

generate-positions-of-first-matching-delimiter-after-listed-positions

This action searches for the text contained in the first phrase, and performs repeated searches within the second phrase, but starts each search at the positions listed in the third phrase, and only finds the first match after that position, and puts into the fourth phrase the list of character positions of all the matches.  If there is no match, the list is empty.  The character positions are numbered starting with 1 at the first character position, and the numbers indicate the position of the first character in the matching text.

Time-related phrases

get-current-time-in-epoch-seconds

This action gets the current time as an integer number that indicates the number of seconds since January 1, 1970 at midnight GMT (UTC).  This convention matches the convention used in Linux and Windows, but not the convention used by Apple.

split-epoch-seconds-into-named-components

This action uses the supplied epoch seconds to put appropriate numbers into the phrases that begin with the word time.  The results are specific to local time at the server location.  Simple Dashrep definitions can use these values to easily generate nearly any date and time format.  See also split-epoch-seconds-into-named-components-for-zero-meridian, which applies to the time at zero meridian.

split-epoch-seconds-into-named-components-for-zero-meridian

This action uses the supplied epoch seconds to put appropriate numbers into the phrases that begin with the word time.  The results are specific for UTC.  Addition and substraction can be used to convert to a specific time zone.  Simple Dashrep definitions can use these values to easily generate nearly any date and time format.  See also split-epoch-seconds-into-named-components, which applies to local time at the server.

time-day-of-month

This phrase contains the day of the month (such as 1, 2, ... 31), based on the epoch seconds supplied to the action split-epoch-seconds-into-named-components or split-epoch-seconds-into-named-components-for-zero-meridian.

time-day-of-week

This phrase contains the numerical day of the week where 1 indicates Monday, 2 indicates Tuesday, and so on, based on the epoch seconds supplied to the action split-epoch-seconds-into-named-components or split-epoch-seconds-into-named-components-for-zero-meridian.

time-day-of-year

This phrase contains the numerical day of the year (1, 2, ... 365, 366), based on the epoch seconds supplied to the action split-epoch-seconds-into-named-components or split-epoch-seconds-into-named-components-for-zero-meridian.

time-hour

This phrase contains the hour of the day, based on the epoch seconds supplied to the action split-epoch-seconds-into-named-components or split-epoch-seconds-into-named-components-for-zero-meridian.  The 24-hour notation is used.  If a 12-hour format is needed, this can be done by defining phrases that handle each case for the 24 cases, such as by defining am-or-pm-for-hour-17 to equal pm and defining adjusted-hour-for-hour-17 to equal 5.

time-minute

This phrase contains the minute of the hour, based on the epoch seconds supplied to the action split-epoch-seconds-into-named-components or split-epoch-seconds-into-named-components-for-zero-meridian.

time-month-number

This phrase contains the numerical month number where 1 indicates January, 2 indicates February, and so on, based on the epoch seconds supplied to the action split-epoch-seconds-into-named-components or split-epoch-seconds-into-named-components-for-zero-meridian.

time-second

This phrase contains the seconds of the minute (0, 1, 2, ... 59), based on the epoch seconds supplied to the action split-epoch-seconds-into-named-components or split-epoch-seconds-into-named-components-for-zero-meridian.

time-year

This phrase contains the year (such as 2012), based on the epoch seconds supplied to the action split-epoch-seconds-into-named-components or split-epoch-seconds-into-named-components-for-zero-meridian.

Number-related phrases

zero-or-nonzero

This action supplies either zero or nonzero depending upon whether the following integer number equals zero.  This phrase is useful when a value of zero requires special handling.

zero-one-multiple

This action supplies either zero or one or multiple depending upon whether the following integer number equals zero, one, or multiple (more than one).  This phrase is very useful for choosing between singular and plural forms of words based on a data-supplied count.

numeric-equal-greater-less-compare

This action supplies the word equal if the two numbers that follow are numerically equal, or supplies the word greater if the first number is greater than the second number, or supplies the word less if the first number is less than the second number.

numeric-add

This action adds the numbers that follow, and supplies the result.  The numbers can be positive or negative integers, or they can be positive or negative decimal numbers, but floating-point numbers are not recognized.  As applies to all Dashrep numeric calculations, each calculation converts the text-based digits into binary values, and the result is converted back into text-based digits, so the calculations are slow compared to the speed of most programming languages.  If more than a few simple calculations are being done, consider doing the intensive numerical processing in a different programming language.

numeric-minus

This action subtracts the second number from the first number, and supplies the result.  See numeric-add for additional information.

numeric-multiply

This action multiplies the first number times the second number, and supplies the result.  See numeric-add for additional information.

numeric-divide-by

This action divides the first number by the second number, and supplies the result.  See numeric-add for additional information.

numeric-maximum

This action determines the maximum value of the numbers that follow, and supplies the result.  See numeric-add for additional information.

numeric-minimum

This action determines the minimum value of the numbers that follow, and supplies the result.  See numeric-add for additional information.

numeric-increment

This action increments (increases by one) the integer value in the named phrase.  This action does not insert the result into text being expanded.  The number in the specified phrase is incremented each time this special action is encountered.  Use of this action should be avoided.  Usually the action use-handler-with-each-word-in-phrase, or the action generate-counts-from-integer-to-integer, or the action unique-value can be used instead.

numeric-decrement

This action decrements (reduces by one) the integer value in the named phrase.  Use of this action should be avoided.  Usually the actions generate-counts-from-integer-to-integer and copy-words-order-reversed can be used instead. This action is useful for debugging situations that loop many more times than expected.

numeric-integer

This action calculates the integer value of a real number, and supplies the result.  If an integer is supplied, the same integer is returned (although leading zeros, if present, are removed).

numeric-absolute

This action calculates the absolute value of the number that follows, and supplies the result.

numeric-odd-or-even

This action supplies the word odd or even based on whether the value of the following operand is an odd or even integer.  It is useful for handling row (or column) numbers in a table.  The result is unpredictable if the operand is not a positive integer.

numeric-sine

This action calculates the (trigonometric) sine of the number that follows, and supplies the result.

numeric-cosine

This action calculates the (trigonometric) cosine of the number that follows, and supplies the result.

numeric-logarithm-base-e

This action calculates the base-e logarithm of the specified number, and supplies the result.  The number is assumed to be a positive number.  If the supplied value is a very small number less than one (typically less than 0.000001) then the result is a large negative number such as -999999.

numeric-logarithm-base-10

This action calculates the base-10 logarithm of the specified number, and supplies the result.  The number is assumed to be a positive number.  If the supplied value is a very small number less than one (typically less than 0.000001) then the result is a large negative number such as -999999.

numeric-pi

This action supplies the text representation for the value of pi.

numeric-vector-add-number

This action adds a single number to each number in the supplied vector and produces a vector sum.  Each vector is a space-delimited list of numbers.  The vector in the definition of the first operand is added to the single number that is supplied as the second operand.  The resulting vector is put into the definition of the third operand.  The numbers can be positive or negative integers, or they can be positive or negative decimal numbers, but floating-point numbers are not recognized.  If subtraction is needed, either insert a minus sign in front of a positive integer, or multiply the single number times minus one before using it in this action.  As applies to all Dashrep numeric calculations, each calculation converts the text-based digits into binary values, and the result is converted back into text-based digits, so the calculations are slow compared to the speed of most programming languages.

numeric-vector-multiply-by-number

This action multiplies a vector times a single number and produces a resulting vector.  Each vector is a space-delimited list of numbers.  The vector in the definition of the first operand is multiplied by the second operand, and the resulting vector is put into the definition of the third operand.  The numbers can be positive or negative integers, or they can be positive or negative decimal numbers, but floating-point numbers are not recognized.  As applies to all Dashrep numeric calculations, each calculation converts the text-based digits into binary values, and the result is converted back into text-based digits, so the calculations are slow compared to the speed of most programming languages.

numeric-vectors-add

This action adds two vectors and produces a vector sum.  Each vector is a space-delimited list of numbers.  The vector in the definition of the first operand is added to the vector in the definition of the second operand, and the resulting vector is put into the definition of the third operand.  The numbers can be positive or negative integers, or they can be positive or negative decimal numbers, but floating-point numbers are not recognized.  If vector subtraction is needed, use the action numeric-vector-multiply-by-number to multiply one of the vectors by minus one, and then add the resulting vector to the positive-sign vector.  As applies to all Dashrep numeric calculations, each calculation converts the text-based digits into binary values, and the result is converted back into text-based digits, so the calculations are slow compared to the speed of most programming languages.

numeric-vectors-multiply

This action multiplies two vectors and produces a vector result.  See the description of the action numeric-vectors-add for additional information.

numeric-vectors-divide-by

This action divides two vectors and produces a vector result.  To prevent dividing by zero, if a calculation involves dividing by a very small decimal number, a very large number is supplied as a result (regardless of the size of the other number).  See the description of the action numeric-vectors-add for additional information.

numeric-vector-integers

This action converts into integers the real numbers that are supplied in the vector that is named in the first operand.  The vector is a space-delimited list of numbers, which can include integers as well as real numbers.  The resulting vector is put into the definition of the second operand.  Floating-point numbers are not recognized.

numeric-vector-absolutes

This action converts a list of numbers within a vector into their absolute values, and puts the resulting list into the definition of the second operand.  The vector is a space-delimited list of numbers, which can include integers as well as real numbers.  Floating-point numbers are not recognized.

numeric-vectors-from-delta-values-calculate-distances

This action gets the list of space-delimited delta X integer numbers in the definition of the first operand and gets the list of space-delimited delta Y integer numbers in the definition of the second operand, and calculates a list of integer distances that are put into the definition of the third operand.  The numbers can be positive or negative integers.  Although decimal numbers can be supplied, the resulting values are truncated to integer values, so the decimal portion is lost.  Floating-point numbers are not recognized.  As applies to all Dashrep numeric calculations, each calculation converts the text-based digits into binary values, and the result is converted back into text-based digits, so the calculations are slow compared to the speed of most programming languages.

numeric-two-dimensional-sort-into-columns-and-rows

This action arranges a set of items into a table of rows and columns based on numeric values along two dimensions.  The resulting arrangement roughly arranges the items from left to right according to one set of numeric values and arranges the items from bottom to top according to a second (independent) set of numeric values.  This action requires four operands, where the first operand is the number of columns, the second operand is the name of a phrase that contains space-delimited numbers that affect horizontal (left-to-right) placement, the third operand is the name of a phrase that contains space-delimited numbers that affect vertical (top-to-bottom) placement, and the fourth operand is the name of the phrase into which the results are placed.  The result contains a sequence of words such as row-3-column-2 that indicate the sorted position of each item, with the result sequence being the same sequence as the two lists of numeric values.  The number of items to be sorted is determined by the number of values in the two numeric lists (which must be the same length).  The items with the largest vertical values appear at the top, the items with the smallest vertical values appear at the bottom, the items with the largest horizontal values appear at the right, and the items with the smallest horizontal values appear at the left.  This vertical convention is the opposite of the document-oriented convention of placing larger vertical values at the bottom, and instead this convention matches the natural-world-oriented convention of placing larger vertical values at the top.

numeric-y-map-tile-number-based-on-latitude

This action calculates the "y" value for the upper-left corner of the Open Street Maps map tile, based on the latitude that is supplied, and based on the zoom value in the phrase numeric-map-tile-zoom, and supplies the result.

numeric-map-tile-zoom

This action specifies the zoom level that is used in the action numeric-y-map-tile-number-based-on-latitude.

XML-related & HTML-related phrases

copy-and-move-attributes-into-xml-tags

This action copies the content of the first phrase to the second phrase but with the content of each attribute tag or a specify tag inside the preceding XML (or HTML) tag.

Example: If the first phrase contains the text <img /><attribute href="image.jpg"><attribute alt="image"> then the definition of the second phrase will be the text <img href="image.jpg" alt="image" />.

The word specify can be used instead of attribute.  This functionality is useful for generating XML and HTML code by using hyphenated phrases such as image-here specify-href image.jpg specify-end specify-alt image specify-end.  Without this approach the generation of HTML and XML code would require specifying the nesting of the beginning and ending of a tag, such as image-here-begin and image-here-end.

copy-and-remove-attributes-from-xml-tags

This action removes attributes from XML and HTML tags, and also removes RSS-style CDATA strings.  The first phrase specifies the source text, and the second phrase specifies the destination.  The two phrase names can be the same.

Example: If the specified phrase contains and a <span style="whatever">dolphin</span>, the result is and a <span>dolphin</span>.

The change assumes that none of the tag's attributes contain a close angle bracket (>).  The result is not intended to be valid XML or HTML or RSS code.  Instead the intended purpose is to simplify the text as preparation for further manipulations.

File-related phrases

yes-or-no-permission-to-append-to-files

If this phrase equals yes then actions have permission to append to existing files.  Any other value indicates that actions do not have this permission.  This value can be changed as needed.  For security purposes this value should be set to no before translating (or expanding) Dashrep code that might be tainted by outside users.

yes-or-no-permission-to-delete-or-overwrite-files

If this phrase equals yes then actions have permission to delete or overwrite existing files.  Any other value indicates that actions do not have these permissions.  This value can be changed as needed.  For security purposes this value should be set to no before translating (or expanding) Dashrep code that might be tainted by outside users.

dashrep-path-prefix-for-file-reading

This phrase specifies a different (non-local-folder) path for file read operations.  If this definition is empty (which is the default value), the local directory is used.  If a path prefix is included with any of the file-reading actions, that path is ignored and this path is used instead.  This approach limits the chances of intentional or accidental access to files that should not be accessed.  A different path is used for file-writing actions.

dashrep-path-prefix-for-file-writing

This phrase specifies a different (non-local-folder) path for file write operations.  If this definition is empty (which is the default value), the local directory is used.  If a path prefix is included with any of the file-writing actions, that path is ignored and this path is used instead.  This approach limits the chances of intentional or accidental access to files that should not be accessed.  A different path is used for file-reading actions.

generate-list-of-files-in-current-read-directory

This action puts into the specified phrase a list of all the files that are in the current directory, where the current directory is specified by the value of phrase dashrep-path-prefix-for-file-reading.

generate-list-of-folders-in-current-read-directory

This action puts into the specified phrase a list of all the folders (directories) that are in the current directory, where the current directory is specified by the value of phrase dashrep-path-prefix-for-file-reading.

yes-or-no-file-exists

This action determines whether the specified file exists, and supplies either yes or no to indicate whether the file exists.  The location of the source file is specified by the phrase dashrep-path-prefix-for-file-reading.

yes-or-no-folder-exists

This action determines whether a folder exists and supplies either yes or no to indicate whether the folder exists.  The folder name, without any path, is specified in the supplied phrase.  The location in which to look for the folder is specified by the phrase dashrep-path-prefix-for-file-reading.

size-of-file

This action gets the file size — in bytes — of the specified file.  The location of the source file is specified by the phrase dashrep-path-prefix-for-file-reading.

modification-time-of-file

This action gets the modification time — in epoch seconds — of the specified file.  The location of the source file is specified by the phrase dashrep-path-prefix-for-file-reading.

set-file-permission-public-read

This action changes the protection of the specified file to allow global access.  It is equivalent to the Linux command i-b chmod 0644 i-e.  The location of the source file is specified by the phrase dashrep-path-prefix-for-file-reading.

create-empty-file

This action creates an empty file using the specified file name, and erases the file if it already exists.  The location of the target file is specified by the phrase dashrep-path-prefix-for-file-writing.

rename-file

This action renames the specified file.  The first operand is the old filename, and the second operand is the new filename.  The location of the file is specified by the phrase dashrep-path-prefix-for-file-writing.

delete-file

This action deletes the specified file.  The location of the target file is specified by the phrase dashrep-path-prefix-for-file-writing.

create-empty-sub-folder

This action creates an empty folder (directory) using the specified folder name, or does nothing if the sub-folder (directory) already exists.  The sub-folder must be directly beneath the directory specified by the phrase dashrep-path-prefix-for-file-writing.  The specified name must contain only letters (a to z and A to Z) and digits and underscores and hyphens; any other characters, including slashes or backslashes, are not allowed.

copy-from-file-to-phrase

This action copies the text in the specified file to the definition of the specified hyphenated phrase (without preserving the previous definition).  The phrase dashrep-yes-indicate-line-endings can be defined as yes to insert the phrase end-of-line-here at each line break that is encountered.  If it is important to keep newline characters (at the end of each line), consider using the action copy-append-file-to-file.  The location of the source file is specified by the phrase dashrep-path-prefix-for-file-reading.

copy-from-phrase-append-to-file

This action copies the definition of the hyphenated phrase onto the end of the specified file.  No separation is inserted (either at the beginning or at the end.  The location of the target file is specified by the phrase dashrep-path-prefix-for-file-writing.

copy-append-file-to-file

This action gets the text from the source file and appends a copy of that text to the end of the target file.  The location of the source file is specified by the phrase dashrep-path-prefix-for-file-reading, and the location of the target file is specified by the phrase dashrep-path-prefix-for-file-writing.

linewise-read-from-file-and-use-handler

This action reads each and every line from the text file whose name is specified by the first phrase, and that expands the handler specified by the second phrase.  When the handler phrase is expanded, the contents of the current line is available in the phrase named storage-input-line-from-file, and the current line number (starting at one for the first line in the file) is available in the phrase named linewise-input-line-count.  The location of the source file is specified by the phrase dashrep-path-prefix-for-file-reading.

linewise-input-line-from-file

See the description for linewise-read-from-file-and-use-handler.

linewise-input-line-count

See the description for linewise-read-from-file-and-use-handler.

get-definitions-from-file

This action reads the Dashrep definitions from the specified file.  This action overwrites any existing definitions that have the same phrase name.  The location of the source file is specified by the phrase dashrep-path-prefix-for-file-reading.

dashrep-phrase-prefix-for-imported-phrases

This prefix is placed at the beginning of each newly defined phrase imported from a file.  This capability is useful to prevent user-written phrase names from overwriting phrase names that are executed with special permissions.  Also this capability is useful for importing phrases from separate files that otherwise might have overlapping phrase names.

dashrep-phrase-suffix-for-imported-phrases

This suffix is placed at the end of each newly defined phrase imported from a file.  See the phrase prefix-for-imported-phrases for more details.

write-dashrep-definitions-listed-in-phrase-to-file

This action writes (in Dashrep-readable form) the definitions of the phrases that are named in the definition of the phrase that follows this action name, and writes those definitions to the named file that follows the specified phrase.  The location of the target file is specified by the phrase dashrep-path-prefix-for-file-writing.

find-line-in-file-that-begins-with-text

This action reads the specified file (named in the first phrase) and finds the first line that begins with the text in the second phrase, and puts the found line into the third phrase.  If none of the lines in the file begin with the specified text, then the third phrase will be empty.  The text being searched for can contain a trailing space, which is useful when full-word matches are needed.  The location of the source file is specified by the phrase dashrep-path-prefix-for-file-reading.

find-lines-in-file-that-begin-with-any-listed-word

This action reads the specified file (named in the first phrase) and finds all the lines that begin with any word in the second phrase, and appends to the third phrase hyphenated phrase names that contain the matching lines.  If none of the lines in the file begin with any of the specified words, then the third phrase will be empty.  The location of the source file is specified by the phrase dashrep-path-prefix-for-file-reading.

find-lines-in-file-that-begin-with-any-two-words-listed

This action reads the specified file (named in the first phrase) and finds all the lines that begin with any of the words in the second phrase, and puts into the third phrase a list of hyphenated phrases that contain the matching lines.  If none of the lines in the file begin with any two of the specified words, then the third phrase will be empty.  A line is regarded as a match if the first two words are the same, and if that word is in the specified word list.  The location of the source file is specified by the phrase dashrep-path-prefix-for-file-reading.

Data-related phrases

copy-from-columns-in-file-to-named-phrases

This action reads from the specified file all the spreadsheet-like lines of text, and puts each (space-delimited) word into a phrase that has a special name.  The specified phrase must begin with the (space-delimited) prefix for all the names, is followed by the (space-delimited) name of each column.  The third operand is the name of a phrase that will contain the list of unique values that come from the first word in each line.  This action is useful for reading spreadsheet-like data.  If a unique value is used more than once, the information in the last occurrence overwrites the earlier information.  The filename is specified by the first operand, and the location of that file is specified in the phrase dashrep-path-prefix-for-file-reading.

Example: If the second operand is a phrase that contains cell-contents-for-nickname phone-number city state and one line of text in the file is flipper 123-456-7890 san_diego ca then the phrase cell-contents-for-nickname-flipper-phone-number will contain 123-456-7890 and the phrase cell-contents-for-nickname-flipper-city will contain san_diego and the phrase cell-contents-for-nickname-flipper-state will contain ca.

If the phrase dashrep-use-two-spaces-as-column-delimiter is defined as yes, then two spaces (instead of one) are required between cells.  This option is useful if the spreadsheet-like cell of data might contain any spaces.

If the second phrase contains only a single word, then the file is assumed to contain only two columns of data on each line, and a suffix is not appended to the end of the generated phrase names.

copy-from-columns-in-file-to-column-lists

This action reads from the specified file all the spreadsheet-like lines of text, and puts the first (space-delimited) word from each line into one list, and puts the second word from each line into another list, and puts the third word from each line into yet another list, and so on.  The generated lists are given the phrase name specified by the second operand (not by the definition in the second operand) followed by a hyphen and the column number.  This action is useful for reading spreadsheet-like data that contains columns of values, where each column of values is meaningful, such as for doing numeric vector calculations and finding the unique values in each column.  Empty lines are ignored.  The line of data with the fewest words determines how many lists are generated, and words beyond that number are ignored.  The filename is specified by the first operand, and the location of that file is specified in the phrase dashrep-path-prefix-for-file-reading.

Example: If the second operand is the phrase list-of-values-in-column and the specified file contains three lines of text, with flipper 123 234 san_diego in the first line, and adolph 456 567 miami fl in the second line, and dory 789 890 los_angeles in the third line, then the phrase list-of-values-in-column-1 will contain flipper adolph dory and the phrase list-of-values-in-column-2 will contain 123 456 789 and the phrase list-of-values-in-column-3 will contain 234 567 890 and the phrase list-of-numbers-in-column-4 will contain san_diego miami los_angeles.

yes-or-no-use-two-spaces-as-column-delimiter

If this phrase equals yes then the action copy-from-columns-in-file-to-named-phrases regards two adjacent spaces as the delimiter between words.  Any other value for this phrase causes a single space to be regarded as the delimiter between words.  This adjustment enables the text in any column of (text) data to contain single spaces.  This adjustment avoids the complications that arise from using a tab character as a column delimiter, such as in exported spreadsheet data.

gather-tagged-info-from-file

This action reads from the specified file all the lines in that text file, and creates phrase definitions that are based on the first word in each line.  When the first word (of a line) matches the definition of the dashrep-gather-tag-begin phrase (which has a default value of entry_begin ), a new set of related items begins, and when the first word (of a line) matches the definition of the dashrep-gather-tag-end phrase (which has a default value of entry_end ), that set of items ends.  When the first word (of a line) matches the definition of the dashrep-gather-tag-unique phrase (which has a default value of url, and which must appear within a set of items), the next (space-delimited) word in that line is used as the unique identifier for the items in that set.  If the same unique identifier appears in a later set, the items in the new set overwrite the previous items that have the same identifier.  Each generated phrase name begins with the tag name (that preceded that item) followed by the text -value-for-unique-id- and then followed by the unique value.  The list of encountered unique values is put into the second-operand phrase.

If the text multi_line_begin immediately follows an item's name, the lines that follow, up to a line that contains (only) multi_line_end, are combined (with a space between each line's content) into a long value for that named item.

If a normal (non-multi) line begins with the definition of the dashrep-gather-tag-delete phrase (which has a default value of delete_id ) then the unique value in the second word (of that line) is omitted from the list of encountered unique values.  If a later entry specifies a definition for an entry that was requested to be deleted, the later entry overrides the deletion request.  A deletion request does not delete any of the already-defined phrases, but those phrases will not be accessed if the created phrases are only accessed using the list of encountered unique values.  As an example, an entry with the unique ID of 1776 can be deleted by appending (to the file) the line delete_id 1776.

A list of the encountered tag names is put into the phrase dashrep-gathered-tag-names.  The order of the list is the order in which the tag names were first encountered.

This "gather" action is useful for accessing database-like text files where the first word in each line acts as the "field" name for a database record, and each set of items corresponds to one database record.  This action is also useful for spreadsheet-like information where the tag names are analogous to single-word column titles, and one row of spreadsheet data is stored in multiple lines, with each cell's content on a separate (labelled) line.  The order of the items within each set is not significant, and the order does not need to be the same from one set to another.  This action does not require that each set of items use the same first words that are used in other sets, but in that case the generated phrases should be checked for undefined (empty) phrase definitions.

The location of the source file is specified by the phrase dashrep-path-prefix-for-file-reading.

gather-from-tagged-file-one-entry

This action reads from a file that also can be read by the action gather-tagged-info-from-file-and-put-unique-values-into-phrase but only gets a single entry and puts that entry into the phrase that is named as the second operand.  The first operand is the name of the file.  The selected entry is specified by a value in the phrase dashrep-gather-tag-matching-id.  If the text that is defined in the phrase dashrep-gather-tag-delete appears within the file and applies to the selected entry, then the content prior to that point is deleted, although later entries (after the last deletion) with the same matching value are recognized.

write-gathered-listed-items-to-end-of-file

This action writes to the end of the specified file all or most of the information that was recently gathered using the action gather-tagged-info-from-file.  The first operand specifies a phrase that contains the list of unique values for the gathered items to be written, which allows some of the items to be omitted.  This action, unlike the "gather" action, does not support the use of multi-line entries.  The second operand is the name of the target file.  The location of the source file is specified by the phrase dashrep-path-prefix-for-file-reading.  This action uses the list of tag names in the phrase dashrep-gathered-tag-names-in-sequence to determine which tag names to use, and the sequence in which they are written.

dashrep-gather-tag-begin

See the description for the action gather-tagged-info-from-file.

dashrep-gather-tag-end

See the description for the action gather-tagged-info-from-file.

dashrep-gather-tag-unique

See the description for the action gather-tagged-info-from-file.

dashrep-gather-tag-delete

See the description for the action gather-tagged-info-from-file.

dashrep-gather-tag-matching-id

See the description for the action gather-from-tagged-file-one-entry.

Debugging-support phrases

trace-show

This action inserts into the trace log the definition of the specified phrase.  These insertions are highlighted with multiple asterisks (*******).  The requested information appears in the trace log regardless of whether the dashrep-action-trace-on-yes-or-no definition is yes or no.

trace-show-where

This action inserts into the trace log the name of the phrase currently being expanded.  These insertions are highlighted with multiple asterisks (*******).  The requested information appears in the trace log regardless of whether the dashrep-action-trace-on-yes-or-no definition is yes or no.

dashrep-comments-ignored

This phrase contains text that the translation process has identified as comments.  Comments are contained within the text *--- and ---*, but these delimiters cannot be nested, so this definition can be useful for debugging.

yes-or-no-count-phrase-usage

generate-phrase-usage-counts

This action puts into the specified phrase a list of counts for how many times each phrase name was replaced.  Each count and its associated phrase name are separated from the next count and phrase name by a newline character.  The phrases are sorted by the count number, with the highest counts appearing first.  Within each count, the order is alphabetical.

Advanced phrases

dashrep-language-yes

This phrase is written to the beginning of the file created by the action write-all-dashrep-definitions-to-file so that the first word identifies the file contents to be written in the Dashrep language.  The default value for this phrase is yes, but this definition is not used.

dashrep-version

This pre-defined phrase contains the Dashrep version number.  This number is not changed with every change in the Dashrep language, but rather tracks major Dashrep changes.

dashrep-undefined

This phrase contains the text that is inserted in some cases when the result of an action is undefined.  The default value is dashrep_undefined.

delayed-nospace

This phrase is not defined, but this name is reserved for use as a placeholder where the phrase no-space needs to be inserted later, after other replacements have been done.  When ready, this phrase should be defined as no-space just before the final translation step.

delayed-newline

This phrase is not defined, but this name is reserved for use as a placeholder where the phrase new-line needs to be inserted later, after other replacements have been done.  Normally this phrase is not needed because the text serves this purpose.  When this phrase is used, this phrase should be defined as new-line just before the final translation step.

dashrep-endless-loop-counter-limit

This phrase specifies the maximum number of replacements allowed during a Dashrep translation.  This number can be redefined, such as to a larger number.  If this limit is exceeded, Dashrep translation is stopped and an error message indicates which phrase was replaced the most number of times.  If large amounts of data are processed, the default number is not going to be large enough.  This limit interrupts endless loops, which can occur if a phrase is defined in a way that (either directly or indirectly) includes its own name.

dashrep-time-limit

This phrase contains the current number of seconds for use as a time limit.  When the time limit is exceeded, translation ends.  The default value is 300 seconds, which equals 5 minutes.  A different value can be specified, although the changed time limit may not take effect immediately.

insert-codeview-tags

This action inserts into the specified phrase definition special tags that enable the raw Dashrep code to be displayed, such as on a web page.  The special inserted tags, such as <dashrep_codeview_action_begin> and <dashrep_codeview_action_middle_1>, are expected to be replaced by the text items in phrases such as dashrep-codeview-action-begin and dashrep-codeview-action-middle-1.

end-of-line-here

This phrase contains text that is inserted at the end of each line when the action copy-from-file-to-phrase is used, and if the phrase yes-or-no-indicate-line-endings equals yes.

yes-or-no-indicate-line-endings

If this phrase equals yes then the action copy-from-file-to-phrase inserts the text end-of-line-here at line-break positions.  The end-of-line-here phrase does not have a default definition.

Special Dashrep spoken words

dashbee

(described in table above)

dashenn

(described in table above)

dashnex

(described in table above)

ambee

(described in table above)

amenn

(described in table above)

combee

(described in table above)

comenn

(described in table above)

fen

(described in table above)

fenambee

(described in table above)

amennfen

(described in table above)

amennfenambee

(described in table above)

linbray

(described in table above)

 

Language Perspective

Functionality

Although Dashrep code is not directly executable, it can generate executable code.  Although it has only one kind of loop directive, namely the action named use-handler-with-each-word-in-phrase (which is similar to a foreach directive), additional Dashrep actions can generate lists (such as generating a list of integers) and manipulate lists (such as finding space-delimited words that appear in one list but not the other list).  Although the Dashrep language has only one simple kind of if directive, advanced branching structures can be implemented without using the if directive.  Although Dashrep code can implement simple templates that involve simple replacements, the Dashrep language also can specify advanced context-specific templates.  Very significantly, the Dashrep language makes it easy to move data out of executable code (where data does not belong).

Dashrep design goals

Future developments

A desirable future development of the Dashrep language would be an editing environment that graphically displays the code as a 3-dimensional representation, with enhancements such as:

Most programming languages have goals regarding best coding practices, so what "should" be the ideal goal for Dashrep code?  Simplicity or "conceptual efficiency" of the code when viewed in a well-designed graphical ("visual") editing environment.  This goal does not imply attempting to minimize any measurement such as fewest lines of code, fewest phrase definitions, or smallest size of the graphical version.  Instead, writing simple, understandable, unambiguous, conceptually efficient Dashrep code is an art, not a science, and not a skill that can be completely automated (although partial automation through the use of Dashrep code is very appropriate).

Another desired future development is the use of new language-specific words for each of the action phrases.  For example, the action "copy-lowercase-only" could become something like "cofraylowcase" in English and "cofrasminusc" in Spanish.  Ideally these new words (or at least their concepts) would merge into existing spoken languages, in order to allow spoken languages to become more conceptually complete, and less ambiguous.

Hopefully future developments in voice-recognition software will support dictation of the Dashrep language.  Specifically this includes recognizing special Dashrep words, automatically inserting hyphens where appropriate, and yet also recognizing the use of single words such as "hyphen" and "space" without translating them into characters.

When voice-recognition technology has evolved even further, special words or phrases will be spoken to control the graphical display of Dashrep code.  For example, a special phrase such as "show ids" can display temporary identification numbers on the displayed lines and boxes, and then speaking a number (such as "74") can shift editing focus to the item with that number.  Eventually it will become possible to do computer programming (and create business documents and diagrams) entirely by voice, without the need to use keyboards or touchscreens.

 

What is the origin of the Dashrep language?

The Dashrep language was developed by Richard Fobes, author of The Creative Problem Solver's Toolbox, over many years of personal use.  A Perl-language, open-source implementation was released on 2009-May-7.

Early versions of the Dashrep language were used to write two books, The Creative Problem Solver's Toolbox and Ending The Hidden Unfairness In U.S. Elections.  At www.VoteFair.org and www.NegotiationTool.com Dashrep code is interpreted to dynamically generate each interactive HTML (web) page (with Perl code providing all the executable functionality).  The language was used to generate JavaScript code that Adobe Illustrator executed to generate vector graphics for use in the book titled Ending The Hidden Unfairness In U.S. Elections.  And an early version of the Dashrep language is still used to generate invoices and packing slips for the publishing business named Solutions Through Innovation.

Obviously the letters “dash” in the name Dashrep refer to the use of dashes (which are the same as hyphens).  Less obviously, the letters “rep” in the name Dashrep refer to the first letters in the words “replace” and “replacement”.

Copyright and trademark notices

© Copyright 2009, 2011, 2012, 2013, 2014, 2015, 2016, 2017 by Richard Fobes at www.Dashrep.org.  All rights reserved.

The Dashrep language is now in the public domain.

The name Dashrep™ is trademarked by Richard Fobes at www.Dashrep.org to prevent attempts to co-opt the name.  The name Dashrep may be used—as an adjective (but not a noun)—to identify the Dashrep language on the condition that the trademark ownership is clearly indicated.

Copyright protection for any code written in the Dashrep language, and for any code that is written to implement the Dashrep language, is specified within that code.

 

Top of Page                © Copyright 2009 through 2017 by Richard Fobes at www.Dashrep.org.