Dirst

From Esolang
Jump to: navigation, search

Dirst is an Esoteric programming language by David Catt (user:David.werecat) where the source code is a directory.

Introduction

Dirst is the first language that takes directories as input, and is made to be both extensive and filesystem-centric. Since each program is a directory, programs will often be distributed in either script or archive form. Execution times are very IO bounded, so fast disks will significantly improve the execution speed.

Language Basics

Getting Started

The basic building block of Dirst is files and directories. Each file or directory in the program will be executed alphabetically, taking into account directory recursion. Files represent operations, and are executed according to their file name and extension. The extension specifies a subset of instructions and the file name specifies the instruction from that subset and its parameters. Directories represent conditional statements or loops. The directory name will give the condition and specifications for the loop. All subfiles/subdirectories of that directory will be conditionally executed or looped when the directory is executed. Since all looping and conditionals are bounded in scope, jumps (or GOTOs) are not directly allowed. These constructs must be emulated using explicit looping or conditionals. Where a file or directory is to be executed, its creation time is checked first. If the creation time has not already passed, the file or directory will not be executed. As such, programs can implement time activated functionality.

Exception Handling

There are several features to aid in exception handling. There are two types of exception handling: local and global. Exception handling defaults to global, but may be changed at run time. Global exceptions are shared between each directory. Therefore, an exception that occurs in one directory will change the last error code for globally. If an exception is uncaught with global exception handling active, the program will fail and report the exception code. Local exceptions are local to only the current directory. Therefore, an exception that occurs in one directory will only change the last error code for that directory. If an exception is uncaught with local exception handling active, the exception will be thrown up each level of recursion until it is caught or until it reaches the top of the stack, in which case the program fails and an exception code is reported. Exception handling can be enabled or disabled on a per-directory or global basis. To enable exception handling, the appropriate exception toggle must be set to false (0). Setting the toggle to true (-1) will disable exception handling.

Variable Types

There are several types of variables available, split into two main categories: values and arrays. Values are used for all operations and are considered the "active" variable type. Arrays are used for dynamic storage and are considered the "passive" variable type. Of these two categories, variables may be signed 32-bit integers, single precision floating point values, or unicode variable length strings. Type safety is enforced strongly and conversion between types must be performed using the conversion instruction subset. Variables must be created before use. Array variables initialize to a default size of zero, although the size may be modified through the proper instructions. Array variables cannot be used with regular computations, so are recommended for storage only. Variable names are case sensitive and are unlimited in scope, therefore a variable created in any part of the program can be used throughout the program. Variables should be deleted when they are no longer needed to improve performance.

Instructions

Syntax

Each file or directory name may optionally start with a comment terminated with an exclamation point (!). This can be used to ensure proper sequential execution as well as providing source code commenting mechanics. There may be multiple comments prepended to any file or directory name. After the conditional comment, the instruction follows. Instructions are three letters long and are followed by an underscore (_) and a parameter list also delimited with underscores. Instruction names are not case sensitive and are matched using an invariant locale. Since certain characters are not allowed in filesystem names or are reserved (such as exclamation points, underscores and periods (.)), escape sequences are used. These escape sequences are discussed later. Each parameter represents a variable name or a literal value. When a parameter is parsed, it is first checked as a variable name. If no matching variable name is found, it is then interpreted as a literal value. An exception is thrown if both attempts fail. String interpretation will never fail when retrieving a value, so it is recommended that string variables names are made recognizable to aid maintainability. All variable names are case sensitive. After the instruction and parameters, a file extension is appended to the end of the file name. The extension is prefixed with a period and is a three letter string. File extensions are case insensitive and are matched using an invariant locale. The file extension specifies one of the instruction subsets in which to find the instruction. An invalid or nonexistent file extension will throw an exception. If any directory or file does not contain an instruction or definition, an exception is also thrown. Therefore comments must be mixed in with the source code. It is important to remember to keep file or directory names concise, since some filesystems limit the maximum length of a file or directory path.

Escape Codes

Escape codes are expanded before interpreting a name. Invalid escape codes are kept as their literal values. Escape codes are case insensitive.

Escape Code Literal Value
-- -
-c :
-s *
-u ?
-g >
-l <
-p |
-e !
-d _
-t Tab
-r Carriage Return
-n Newline/Linefeed
-q "

Instruction Subsets Reference

The following subsets are defined:

Subset Name Description
Directory Handles looping, conditionals and code separation
.DAT Contains all integer functionality and logic
.TXT Contains all string functionality and logic as well as advanced console IO
.BIN Contains all floating point functionality and logic as well as advanced math operations
.ZIP Manages arrays and array values
.EXE Handles type conversion and value/array transcoding
.DLL Contains all extensions and specialized instructions, such as exception handling and abstract data structures
.CSV Manages, creates, and destroys variables and arrays

When a value is set as part of an instruction, that value will most likely reside in the first parameter of the instruction. In all examples, the following notations are used:

  • $ : Integer variable or literal integer
  • # : String variable or literal string
  •  % : Float variable of literal float

Any variable surrounded by square brackets ([]) is an array variable of the specified type. There are no literal array values.

Instruction Subset Instruction Syntax Description
Directory fnc Execute all subitems in the directory
dif_$ Execute directory subitems only if the specified integer value is not zero
nif_$ Execute directory subitems only if the specified integer value is zero
lpc_$ Loop through directory subitems while the specified integer value is not zero
lpn_$ Loop through directory subitems while the specified integer value is zero
dlw_$ Do loop through directory subitems while the specified integer value is not zero (loop at least once)
dlu_$ Do loop through directory subitems while the specified integer value is zero (loop at least once)
.DAT abs_$_$ Sets parameter 1 to the absolute value of parameter 2
neg_$_$ Sets parameter 1 to the negative value of parameter 2
add_$_$_$ Sets parameter 1 to the value of parameter 2 plus parameter 3
sub_$_$_$ Sets parameter 1 to the value of parameter 2 minus parameter 3
mul_$_$_$ Sets parameter 1 to the value of parameter 2 times parameter 3
div_$_$_$ Sets parameter 1 to the value of parameter 2 divided by parameter 3
mod_$_$_$ Sets parameter 1 to the value of parameter 2 modulo parameter 3
and_$_$_$ Sets parameter 1 to the value of parameter 2 bitwise and parameter 3
orb_$_$_$ Sets parameter 1 to the value of parameter 2 bitwise or parameter 3
xor_$_$_$ Sets parameter 1 to the value of parameter 2 bitwise xor parameter 3
xad_$_$_$ Sets parameter 1 to the value of parameter 2 bitwise xand parameter 3
nad_$_$_$ Sets parameter 1 to the value of parameter 2 bitwise nand parameter 3
nor_$_$_$ Sets parameter 1 to the value of parameter 2 bitwise nor parameter 3
not_$_$ Sets parameter 1 to the value of the bitwise not of parameter 2
mor_$_$_$ Sets parameter 1 to -1 if parameter 2 is greater than parameter 3, otherwise 0
les_$_$_$ Sets parameter 1 to -1 if parameter 2 is less than parameter 3, otherwise 0
equ_$_$_$ Sets parameter 1 to -1 if parameter 2 is equal to parameter 3, otherwise 0
neq_$_$_$ Sets parameter 1 to -1 if parameter 2 is not equal to parameter 3, otherwise 0
get_$_$_$ Sets parameter 1 to -1 if parameter 2 is greater than or equal to parameter 3, otherwise 0
let_$_$_$ Sets parameter 1 to -1 if parameter 2 is less than or equal to parameter 3, otherwise 0
rdi_$ Reads an integer from the console and sets the specified integer variable to the value. If EOF is encountered, the variable is not modified and EOF is marked.
ric_$ Read a character from the console and sets the specified integer variable to the value. If EOF is encountered, the variable is set to -1.
dsi_$ Display the specified integer value to the console
dic_$ Display the character specified by the integer value to the console
set_$_$ Sets parameter 1 to the value of parameter 2
max_$_$_$ Sets parameter 1 to the higher value out of parameter 2 and parameter 3
min_$_$_$ Sets parameter 1 to the lower value out of parameter 2 and parameter 3
.TXT rdc_# Reads a character from the console and appends to the specified string. If EOF is encountered, the variable is not modified and EOF is marked.
rds_# Reads a line from the console and appends to the specified string. If EOF is encountered, the variable is not modified and EOF is marked.
eof_$ Sets the given integer variable to -1 it EOF has been reached, 0 otherwise
dsc_#_$ Displays the character from string parameter 1 at index parameter 2 (base 0) to the console
dss_# Displays the given string variable to the console with no newline following
dsl_# Displays the given string variable to the console followed by a newline
dec_#_$ Displays the character from string parameter 1 at index parameter 2 (base 0) to STDERR
des_# Displays the given string variable to STDERR with no newline following
del_# Displays the given string variable to STDERR followed by a newline
clr_# Clears the given string variable
cat_#_#_# Concats parameter 2 and parameter 3 and sets parameter 1 to the result
idx_$_#_# Set parameter 1 to the index of the first occurrence of parameter 3 in parameter 2, or -1 if not found
ids_$_#_#_$ Set parameter 1 to the index of the first occurrence of parameter 3 in parameter 2 after specified index parameter 4, or -1 if not found
lid_$_#_# Set parameter 1 to the index of the last occurrence of parameter 3 in parameter 2, or -1 if not found
rep_#_#_#_# Set parameter 1 to the value of parameter 2, replacing every occurrence of parameter 3 with parameter 4
sub_#_#_$_$ Set parameter 1 to the substring of parameter 2 from index parameter 3 (base 0) of length parameter 4
rmv_#_#_$_$ Set parameter 1 to parameter 2 removing characters from index parameter 3 (base 0) of length parameter 4
ins_#_#_$_# Set parameter 1 to parameter 2 inserting substring parameter 4 at index parameter 3 (base 0)
tou_#_# Set parameter 1 to the all uppercase value of parameter 2
tol_#_# Set parameter 1 to the all lowercase value of parameter 2
pdl_#_#_$ Set parameter 1 to parameter 2 padded on the left-hand side with spaces until length parameter 3 is reached
cpl_#_#_$_$ Set parameter 1 to parameter 2 padded on the left-hand side with the character value parameter 4 until length parameter 3 is reached
pdr_#_#_$ Set parameter 1 to parameter 2 padded on the right-hand side with spaces until length parameter 3 is reached
cpr_#_#_$_$ Set parameter 1 to parameter 2 padded on the right-hand side with the character value parameter 4 until length parameter 3 is reached
sam_$_#_# Set parameter 1 to -1 if parameter 2 is equal to parameter 3, 0 otherwise
dif_$_#_# Set parameter 1 to -1 if parameter 2 is not equal to parameter 3, 0 otherwise
hiv_$_#_# Set parameter 1 to -1 if parameter 2 is lexicographically after parameter 3, 0 otherwise
lov_$_#_# Set parameter 1 to -1 if parameter 2 is lexicographically before parameter 3, 0 otherwise
hev_$_#_# Set parameter 1 to -1 if parameter 2 is lexicographically after or equal to parameter 3, 0 otherwise
lev_$_#_# Set parameter 1 to -1 if parameter 2 is lexicographically before or equal to parameter 3, 0 otherwise
ssw_$_#_# Set parameter 1 to -1 if parameter 2 starts with parameter 3, 0 otherwise
sew_$_#_# Set parameter 1 to -1 if parameter 2 ends with parameter 3, 0 otherwise
trm_#_#_# Set parameter 1 to parameter 2 trimming all leading and trailing occurrences of the characters in parameter 3
tms_#_#_# Set parameter 1 to parameter 2 trimming all leading occurrences of the characters in parameter 3
tme_#_#_# Set parameter 1 to parameter 2 trimming all trailing occurrences of the characters in parameter 3
ses_#_# Set parameter 1 to the value of parameter 2
.BIN pls_%_%_% Set parameter 1 to the value of parameter 2 plus parameter 3
mns_%_%_% Set parameter 1 to the value of parameter 2 minus parameter 3
tms_%_%_% Set parameter 1 to the value of parameter 2 times parameter 3
dvb_%_%_% Set parameter 1 to the value of parameter 2 divided by parameter 3
pwr_%_%_% Set parameter 1 to the value of parameter 2 to the power of parameter 3
sgn_%_% Set parameter 1 to the value of the sign of parameter 2
sqr_%_% Set parameter 1 to the value of the square root of parameter 2
sin_%_% Set parameter 1 to the value of the sine of parameter 2
cos_%_% Set parameter 1 to the value of the cosine of parameter 2
tan_%_% Set parameter 1 to the value of the tangent of parameter 2
snh_%_% Set parameter 1 to the value of the hyperbolic sine of parameter 2
csh_%_% Set parameter 1 to the value of the hyperbolic cosine of parameter 2
tnh_%_% Set parameter 1 to the value of the hyperbolic tangent of parameter 2
cil_%_% Set parameter 1 to the value of the ceiling of parameter 2
flr_%_% Set parameter 1 to the value of the floor of parameter 2
log_%_% Set parameter 1 to the value of the base 10 logarithm of parameter 2
lge_%_% Set parameter 1 to the value of the natural logarithm of parameter 2
lbq_%_%_% Set parameter 1 to the value of the base parameter 3 logarithm of parameter 2
epw_%_% Set parameter 1 to the value of e to the power of parameter 2
avl_%_% Set parameter 1 to the value of the absolute value of parameter 2
rnd_% Set the given float variable to a random value between 0.0 and 1.0 inclusive
rou_%_% Set parameter 1 to the value of parameter 2 rounded to the nearest whole number
asn_%_% Set parameter 1 to the value of the inverse sine of parameter 2
acs_%_% Set parameter 1 to the value of the inverse cosine of parameter 2
atn_%_% Set parameter 1 to the value of the inverse tangent of parameter 2
mks_%_% Set parameter 1 to the value of parameter 2
fmx_%_%_% Set parameter 1 to the greater value of either parameter 2 or parameter 3
fmn_%_%_% Set parameter 1 to the lesser value of either parameter 2 or parameter 3
grt_%_%_% Set parameter 1 to -1 if parameter 2 is greater than parameter 3, 0 otherwise
lst_%_%_% Set parameter 1 to -1 if parameter 2 is less than parameter 3, 0 otherwise
eqt_%_%_% Set parameter 1 to -1 if parameter 2 is equal to parameter 3, 0 otherwise
net_%_%_% Set parameter 1 to -1 if parameter 2 is not equal to parameter 3, 0 otherwise
gte_%_%_% Set parameter 1 to -1 if parameter 2 is greater than or equal to parameter 3, 0 otherwise
lte_%_%_% Set parameter 1 to -1 if parameter 2 is greater than or equal to parameter 3, 0 otherwise
rfv_% Reads a floating point value from the console and sets the specified float variable to the value. If EOF is encountered, the variable is not modified and EOF is marked.
dfv_% Display the sepecified float value to the console
.ZIP giv_$_[$]_$ Set parameter 1 to the integer value in array parameter 2 at index parameter 3 (base 0)
siv_[$]_$_$ Set an integer value in array parameter 1 at index parameter 2 (base 0) to the value of parameter 3
gsv_#_[#]_$ Set parameter 1 to the string value in array parameter 2 at index parameter 3 (base 0)
siv_[#]_$_# Set an string value in array parameter 1 at index parameter 2 (base 0) to the value of parameter 3
gfv_%_[%]_$ Set parameter 1 to the float value in array parameter 2 at index parameter 3 (base 0)
sfv_[%]_$_% Set an float value in array parameter 1 at index parameter 2 (base 0) to the value of parameter 3
fia_[$]_$ Resizes the integer array in parameter 1 to the size parameter 2 (base 0), preserving data
zia_$_[$] Set parameter 1 to the size of the integer array in parameter 2
fsa_[#]_$ Resizes the string array in parameter 1 to the size parameter 2 (base 0), preserving data
zsa_$_[#] Set parameter 1 to the size of the string array in parameter 2
ffa_[%]_$ Resizes the float array in parameter 1 to the size parameter 2 (base 0), preserving data
zfa_$_[%] Set parameter 1 to the size of the float array in parameter 2
.EXE sia_[$]_# Converts the string value in parameter 2 into the integer array in parameter 1 where each integer represents a character code
ssa_[#]_#_# Converts the string value in parameter 2 into the string array in parameter 1 by splitting it using the string value parameter 3 as a delimiter
sti_$_# Converts the string value in parameter 2 into the integer variable in parameter 1 by interpreting the base 10 value represented by the string
stf_%_# Converts the string value in parameter 2 into the float variable in parameter 1 by interpreting the decimal value represented by the string
stc_$_#_$ Converts the string value in parameter 2 into the integer variable in parameter 1 by retrieving the character code of the character at index parameter 3 (base 0) in the string
its_#_$ Converts the integer value in parameter 2 into the string variable in parameter 1 by converting it into a base 10 string representation
itf_%_$ Converts the integer value in parameter 2 into the float variable in parameter 1 using equivalence
ias_#_[$] Converts the integer array in parameter 2 into the string variable in parameter 1 by converting each integer element of the array into a character with the character code specified by the value
aif_[%]_[$] Converts the integer array in parameter 2 into the float array in parameter 1 by transforming each element using equivalence
fts_#_% Converts the float value in parameter 2 into the string variable in parameter 1 by converting it into a standard format decimal string representation
fti_$_% Converts the float value in parameter 2 into the integer variable in parameter 1 using euqivalence
afi_[$]_[%] Converts the float array in parameter 2 into the integer array in parameter 1 by transforming each element using equivalence
.DLL psh_$ Pushes the integer value onto the stack
pop_$ Set the specified integer variable to the value popped from the stack. An exception is thrown if the stack is empty.
spk_$ Set the specified integer variable to the value peeked from the stack. An exception is thrown if the stack is empty.
ssz_$ Set the specified integer variable to the value of the size of the stack
enq_$ Euqueues the specified integer value in the queue
deq_$ Set the specified integer variable to the value dequeued from the queue. An exception is thrown if the queue is empty.
qpk_$ Set the specified integer variable to the value peeked from the queue. An exception is thrown if the queue is empty.
qsz_$ Set the specified integer variable to the value of the size of the queue
tpl Moves the tape left
tpr Moves the tape right
tsv_$ Sets the current element of the tape to the specified integer value
tgv_$ Sets the specified integer variable to the value of the current element of the tape
gbe Changes the error handling mode to global
gen Turns global errors on (exception handling off)
gef Turns global errors off (exception handling on)
lce Changes the error handling mode to local
lcn Turns local errors on (exception handling off)
lcf Turns local errors off (exception handling on)
ges_# Sets the specified string variable to the error message from the last caught exception in the given scope
ces Clears the error string in the given scope
.CSV cia_[$] Creates an integer array with the specified variable name
civ_$ Creates an integer variable with the specified variable name
csa_[#] Creates a string array with the specified variable name
csv_# Creates a string variable with the specified variable name
cfa_[%] Creates a float array with the specified variable name
cfv_% Creates a float variable with the specified variable name
dia_[$] Deletes an integer array with the specified variable name
div_$ Deletes an integer variable with the specified variable name
dsa_[#] Deletes a string array with the specified variable name
dsv_# Deletes a string variable with the specified variable name
dfa_[%] Deletes a float array with the specified variable name
dfv_% Deletes a float variable with the specified variable name

Scripting

Dirst also supports scripting. Scripts are expanded into a temporary directory and executed from there. A script is a textual representation of the directory tree that makes up a program. Each line of script is a definition for a directory or a file; although unlike the directory programming form a script may contain fully commented lines. A fully commented line must start with a tilde (~) and must maintain tabbing. Any difference in tabbing with tildes will result in directory breaking. This is useful for separating sequential directories. Also, the first line of a new directory must be the name of the directory and cannot be a comment.

Each line is the name of the file or directory. Lines are automatically prefixed with numbering comments by the interpreter when the script is expanded, so there is no need to worry about the order of execution. Each sequential entry in a directory has the same tabbing as the last entry. Whenever an extra tab is added in a line from the last line, that line represents the name of a directory and all sequential statements of the same tabbing are put in that new directory. When a line has less tabs than the last line, a number of directories are returned to their parent equal to the number of tabs lost. A directory returned to the parent directory cannot be re-entered. To separate sequential directories, put a line with one less tab starting with a tilde in between them. Remember that the first line in a new directory is the name of that directory.

The interpreter can be called with the argument "-e" to expand scripts to their full representation. There is no option to convert directories into scripts, since there are better archival options and programs should be stored in directory form.

Sample Programs

The following samples are stored in script format. Using the interpreter to expand them before running will help with a better understanding of both the directory structure and scripting.

CAT Program

civ_tmp.csv
civ_input.csv
set_tmp_1.dat
	lpc_tmp
	ric_input.dat
	neq_tmp_input_--1.dat
		dif_tmp
		dic_input.dat
div_tmp.csv
div_input.csv

Hello, World!

dss_Hello, world-e.txt

Fibonacci Sequence

civ_val1.csv
civ_val2.csv
civ_val3.csv
civ_bool.csv
set_val2_1.dat
set_bool_1.dat
	dlw_bool
	add_val3_val1_val2.dat
	set_val1_val2.dat
	set_val2_val3.dat
	dsi_val1.dat
	dsl_.txt
	les_bool_val2_1000000000.dat
div_val1.csv
div_val2.csv
div_val3.csv
div_bool.csv

Greeter

csv_name.csv
dss_What is your name-u .txt
rds_name.txt
dss_Hello .txt
dss_name.txt
dss_-e.txt
dsv_name.csv

Deadfish Interpreter

civ_value.csv
civ_char.csv
civ_boolean.csv
civ_temp.csv
cfv_fv.csv
cfv_fr.csv
	dlw_boolean
	dss_-g-g .txt
	ric_char.dat
	neq_boolean_char_-1.dat
		dif_boolean
		equ_temp_char_100.dat
			dif_temp
			sub_value_value_1.dat
		equ_temp_char_105.dat
			dif_temp
			add_value_value_1.dat
		equ_temp_char_111.dat
			dif_temp
			dsi_value.dat
			dsl_.txt
		equ_temp_char_115.dat
			dif_temp
			itf_fv_value.exe
			pwr_fr_fv_2.bin
			fti_value_fr.exe
		equ_temp_char_10.dat
			lpn_temp
			ric_char.dat
			equ_temp_char_10.dat
				nif_temp
				equ_temp_char_-1.dat
	equ_temp_value_256.dat
		dif_temp
		set_value_0.dat
	les_temp_value_0.dat
		dif_temp
		set_value_0.dat
div_value.csv
div_char.csv
div_boolean.csv
div_temp.csv
dfv_fv.csv
dfv_fr.csv

Truth Machine

civ_value.csv
civ_tmp.csv
ric_value.dat
equ_tmp_value_49.dat
	lpc_tmp
	dic_value.dat
dic_48.dat

External resources

Interpreter and sample programs, requires either the .NET framework on Windows or Mono on Linux to run (Mono untested)