SYCPOL

SYCPOL (System card programming language, pronounced /'sɪkpɔl/) is a mildly esoteric programming language created by User:Fergusq in 2014 inspired by COBOL (not Card Orientations Based Object Language). The program is a set of system cards which are interpreted by a "system card machine".
== Terminology ==
A system card machine (sometimes called a system card interpreter machine, SCIM /'ʃkɪm/) is a machine that reads system cards and interprets the code. A SCIM that interprets SYCPOL is called a SYCPOL-SCIM. A SCIM emulator is called a VISCIM /'vɪʃ.kɪm/, virtual SCIM.
Word file in this article means a physical file or envelope which contains cards. That's why VISCIMs usually call directories files.
== System cards ==
For some reason, all system card machines only accept one type of cards, The Standard System Card I (SSC-M1). The M1 card is a sized 22x22.
The first line is either PROGRAM CARD or COMMENT CARD. It is important that there are spaces between words, see below for an example. The second line is always STANDARD SYSTEM CARD I. This is called a card declaration. After it there are 20 lines of other code.
 COMMENT CARD
 STANDARD SYSTEM CARD I
 
 THIS IS COMMENT
 
 C
 O
 M
 M
 E
 N
 T
 
 .
 .
 .
 
 
 
 
 
 THE LAST LINE
== System card machines ==
=== Hardware and devices ===
As SCIMs are multi-purpose devices there is no standard hardware. When used in offices, a SCIM-computer usually has a printer, an input card reader and a program card reader. Sometimes there is also a keyboard.
=== Computer architecture ===
Because SCIMs are used to interpret code only from system cards, manufacturers don't usually release too much documentation about the architecture or machine language.
=== Extensions and compatibility ===
All manufacturers usually provide full compatibility with standard SYCPOL. Extensions contain instructions used to command specific devices, perform scientific calculations, etc.
== Datatypes ==
=== Strings ===
* STRING 8 – A 8 characters long string.
* STRING 16
* STRING 32
=== Integers ===
* INTEGER 8 – A byte.
* INTEGER 16 – Two bytes.
=== Streams ===
* STREAM – Super type of all streams.
* OUTPUT STREAM – Output only.
* INPUT STREAM – Input only.
* IO STREAM – Both.
=== Lists ===
Prefixed with +. Example: +INTEGER 8 is a list of integers and ++STRING 16 is a list of lists of strings.
=== Structures ===
Structures are programmer-defined data types prefixed with % and declared in the LAYOUT DIVISION.
== The structure of the program ==
The program is split to various divisions, which contain information about the program. The DOCUMENTATION DIVISION contains the name of the program and the author. The IMPORTS DIVISION contains a list of external procedures and variables. The INPUT OUTPUT DIVISION contains a list of open I/O streams, files etc. The STORAGE DIVISION contains all constants and static variables. The PROGRAM CODE DIVISION contains all procedures.
Divisions contain declarations. They can be for example constants, variables or procedures.
Sections are parts of declarations. The most declarations contain only one section, but some, like procedures, contain many.
=== DOCUMENTATION DIVISION ===
This division starts a module and cannot begin in the middle of a card. Following declarations are supported:
* IDENTIFIER STRING N – The name of the module.
* AUTHOR NAME STRING N – The name of the author.
* DESCRIPTION STRING N – General information about the module.
=== IMPORTS DIVISION ===
Following declarations are supported:
* !NM EXTERNAL PROCEDURE – An external procedure. NM is an identifier. Contains following subdeclarations:
** IDENTIFIER STRING N – The name of the procedure.
** MODULE NAME STRING N – The name of the module.
* %NM EXTERNAL STRUCTURE – An external structure. NM is an identifier. Contains following subdeclarations:
** IDENTIFIER STRING N – The name of the structure.
** MODULE NAME STRING N – The name of the module.
=== INPUT OUTPUT DIVISION ===
Following declarations are supported:
* OPEN STREAM / CLOSE STREAM – Opens or closes a stream. STREAM is either STANDARD INPUT or STANDARD OUTPUT.
* .NM INPUT STREAM / .NM OUTPUT STREAM / .NM IO STREAM – Declares a new stream. NM is an identifier. Contains following subdeclarations:
** OUTS DEVICE – Declares the output part of a stream. DEVICE is the name of the device.
** OUTS STANDARD OUTPUT – Declares the output part to the standard output.
** INS DEVICE – Declares the input part of a stream. DEVICE is the name of the device.
** INS STANDARD INPUT – Declares the input part to the standard input.
=== LAYOUT DIVISION ===
Following declarations are supported:
* %NAME STRUCTURE – Declares a new structure. Supports following sections:
** DOCUMENTATION SECTION
*** IDENTIFIER STRING N – The name of the structure for exporting.
*** AUTHOR NAME STRING N – The author name. Optional.
*** DESCRIPTION STRING N – Information about the structure. Optional.
** FIELD SECTION – The default section. Doesn't have to specified if is the only one.
*** NAME DATATYPE – Declares a field. NAME can't be any of following:
**** CARD DIVISION PROCEDURE SECTION STREAM STRUCTURE
=== STORAGE DIVISION ===
Following declarations are supported:
* .NAME DATATYPE – Declares a new constant.
* $NAME DATATYPE – Declares a new global variable.
=== PROGRAM CODE DIVISION ===
Following declarations are supported:
* MAIN PROCEDURE – Declares the main procedure.
* !NAME PROCEDURE – Declares a procedure. Following sections are supported:
** DOCUMENTATION SECTION – The default section. Doesn't have to be specified if starts the procedure.
*** IDENTIFIER STRING N – The name of the procedure for exporting. Optional.
*** AUTHOR NAME STRING N – The author name. Optional.
*** DESCRIPTION STRING N – Information about the procedure. Optional.
** PARAMETER SECTION – Declares all parameters. Following subdeclarations are supported:
*** $NAME DATATYPE – Declares a new mutable parameter.
*** .NAME DATATYPE – Declares a new immutable parameters.
** VARIABLE SECTION – Declares all variables. Following subdeclarations are supported:
*** $NAME DATATYPE – Declares a new variable.
** PROCEDURE CODE SECTION – Declares the procedure code.
----
=== Imperative code ===
MAIN PROCEDURE and PROCEDURE CODE SECTION contain imperative program code. For example, from the hello world below:
PROCEDURE CODE SECTION
(1) CHANGE $L
 TO THE LENGTH
 OF $TEXT
(2) IF $I=$L (6)
(3) SEND THE CHARACTER
 AT $I
 IN $TEXT
 TO $STREAM
(4) INCREMENT $I
(5) JUMP (2)
(6) RETURN
 WITH SUCCESS
STANDARD SYCPOL supports following statements:
* CHANGE $VAR – Assigns a variable a new value. Requires following arguments:
** TO VAL – The new value. VAL is an expression.
* INCREMENT $VAR – Increments a variable.
* DECREMENT $VAR – Decrements.
* CHANGE THE FIELD – Assigns a new value to a field. FIELD is the name of the field. Requires:
** OF VAL – The structure.
** TO VAL – The new value.
* ADD VAL – Adds a value to the end of a list. Requires:
** TO VAL – The list.
* REMOVE – Remove a value from the end of a list. Requires:
** FROM VAL – The list.
* SEND VAL – Sends a value to a stream. Requires:
** TO VAL – The stream.
* IF VAL=VAL – Conditional jump.
* JUMP – Jump.
* PROCEED – Proceeds to a procedure.
** TO !PRC – The procedure.
** WITH – Arguments, a list of values separated by newlines. See examples.
* RETURN – Ends the procedure. Requires one of:
** WITH SUCCESS – Exits from the procedure normally.
** WITH FAILURE – Terminates the program.
And following expressions:
* THE NEXT – Reads a value from a stream. Requires:
** FROM VAL – The stream.
* THE LENGTH – The length of a string. Requires:
** OF VAL – The string.
* THE CHARACTER – Character at.
** AT VAL – The position.
** IN VAL – The string.
* THE ELEMENT – Reads from a list.
** AT VAL – The position.
** IN VAL – The list.
* THE FIRST – The first element of a list.
** OF VAL – The list.
* THE LAST – The last element of a list.
** OF VAL – The list.
* THE FIELD – Reads a field from a structure. Replace FIELD with the name of the field.
** OF VAL – The structure.
TODO more.
----
=== Simple declarations ===
A simple declaration has form
 NAME TYPE
 VALUE
where TYPE is a datatype listed in SYCPOL#Datatypes section.
==== STRING N declarations ====
A string value is surrounded by "-characters. Escape character is " too.
 NAME STRING 32
 """String8"" is a "
 "datatype."
==== INTEGER N declarations ====
An integer value is a sequence of number characters (0-9).
 NAME INTEGER 8
 42
==== STREAM declarations ====
These declarations may only occur in the INPUT OUTPUT DIVISION.
 .NAME IO STREAM
 OUTS DEVICE
 INS DEVICE
The standard declares only two valid DEVICEs:
STANDARD INPUT for input and STANDARD OUTPUT for output.
An input+output stream has both INS and OUTS.
Input only stream has only INS and output only has only OUTS.
 .STDIO IO STREAM
 OUTS STANDARD OUTPUT
 INS STANDARD INPUT
VISCIMs may allow FS (file system) devices:
 .OUT OUTPUT STREAM
 OUTS FS OUTPUT.TXT
----
=== Procedures ===
Procedures are used to perform various tasks in SYCPOL. While they can't return values as in many other languages, all parameters are passed by reference so that they can be modified.
The MAIN PROCEDURE is in many ways more limited that other procedures. It can't have local variables and can't be called from the program.
----
=== Structures ===
An example structure, PERSON:
PROGRAM CARD
STANDARD SYSTEM CARD I
LAYOUT DIVISION
%PERSON STRUCTURE
NAME STRING 8
AGE INTEGER 8
FRIENDS +%PERSON
An example constructor procedure, CREATE:
PROGRAM CARD
STANDARD SYSTEM CARD I	CREATE PROCEDURE
PARAMETER SECTION
$P %PERSON
$NAME STRING 8
$AGE INTEGER 8
PROCEDURE CODE SECTION
(1) CHANGE $P
 TO A NEW %PERSON
(2) CHANGE THE NAME
 OF $P
 TO $NAME
(3) CHANGE THE AGE
 OF $P
 TO $AGE
(4) RETURN
 WITH SUCCESS
And how these two are used:
PROGRAM CARD
STANDARD SYSTEM CARD I
STORAGE DIVISION
$BOB %PERSON
$ANNA %PERSON
.BOB STRING 8
"BOB"
.ANNA STRING 8
"ANNA"
.SIXTEEN INTEGER 8
16
.SEVENTEEN INTEGER 8
17	
PROGRAM CARD
STANDARD SYSTEM CARD I
MAIN PROCEDURE
(1) PROCEED TO !CREATE
 WITH
 $BOB
 .BOB
 .SIXTEEN
(2) PROCEED TO !CREATE
 WITH
 $ANNA
 .ANNA
 .SEVENTEEN
(3) ADD $ANNA TO
 THE FRIENDS
 OF $BOB
(4) ADD $BOB TO
 THE FRIENDS
 OF $ANNA
(5) RETURN
 WITH SUCCESS
----
=== Standard SYCPOL formatting rules ===
==== Character set ====
The character set is not specified, but the standard enforces support for following characters:
* A-Z – Uppercase letters
* 0-9 – Numerals
* .:,;!?-="'$%&|<>()/*^+ – A selection of the most useful special characters, mostly for string literals.
* Empty space – This is obvious. Note that a special "newline" character is not required, it is automatically inserted by the printer after printing 22 other characters.
It recommended for system card and machine manufacturers to NOT include support for other letters, as that would break compatibility. Anyway, why would someone use other card than SSC-M1? The Standard System Card I supports all these characters and is certainly the best choice for all.
==== Newlines ====
At the third line of a card, there should be a newline if the card is continuation to the previous card. As only the DOCUMENTATION DIVISION may start a new module, only it can be at the third line.
After a single-section declaration is a newline. For example, the next line after a constant contains the value and the second next the newline.
 .CONSTANTA STRING 8
 "VALUE"
 
 .CONSTANTB STRING 8
 "VALUE"
==== Indentation rules ====
Prepositions starts a new indentation layer. If a statement is continued to the next lines, they are in a new indentation layer.
Example, (c) means "there is an indentation layer because the statement continued to this line" and (p) "a prepositons introduced this layer".
 (1) CHANGE $L 
 TO THE LENGTH 
 OF $S 
 
 (3) SEND THE CHARACTER
 AT $I 
 IN $S 
 TO .OUT	
 The first indentation layer.
 (c)
 (c)(p) TO-preposition introduced a new layer.
 
 The first layer.
 (c)
 (c)
 (c)
== Extensions ==
=== RS-SYCPOL ===
RS-SYCPOL was designed to make storing and using cards easier, allowing cards to be in any order.
In RS things can be declared again, with more information. It also supports MODULE-declarations.
See examples.
==== Changes compared to the standard ====
* All divisions, declarations and sections can be respecified.
* LAYOUT DIVISION, PROGRAM CODE DIVISION or PROCEDURE CODE SECTION are not required to be specified, if it would appear at the top of a card.
* A MODULE declaration may appear immediately after the CARD declaration.
== VISCIMs and other implementations ==
=== VISCIM-JA ===
VISCIM-JA (Virtual system card interpreter machine in Java, /'vɪʃ.kɪm.jɑ/) is a VISCIM by fergusq.
Although not strictly compatible with RS-SYCPOL, it shares many same formatting rules and other constructs. The SYCPOL dialect of this SCIM is called VISCIM-JA-SYCPOL. See external resources for downloads.
==== Indentation rules ====
If a statement continues to the next line, the continuation should be on the next indentation layer. No other indentation is required.
 (1) CHANGE $A 
 TO THE NAME
 OF THE OBJ
==== MODULE declaration ====
As in RS-SYCPOL, there is an optional MODULE declaration. While it should be used at the top of a card, VISCIM-JA allows it to occur at the middle of a card.
==== Multiple declarations ====
Allowing cards to be supplied in any order, modules, divisions, procedures, structures, sections and all other kind of declarations may be declared multiple times. The new declaration doesn't replace the old but complements it.
The DOCUMENTATION DIVISION cannot be respecified as in RS-SYCPOL.
PROGRAM CARD
STANDARD SYSTEM CARD I
NAME MODULE
NAME DIVISION
NAME DECLARATION
NAME SUBDECLARATION
VALUE
It is not required to specify LAYOUT DIVISION, PROGRAM CODE DIVISION or PROCEDURE CODE SECTION, if it would appear at the top of a card.
PROGRAM CARD
STANDARD SYSTEM CARD I
NAME MODULE
MAIN PROCEDURE
(1) DO SOMETHING
(2) DO SOMETHING OTHER	
PROGRAM CARD
STANDARD SYSTEM CARD I
NAME MODULE	NAME PROCEDURE
(1) DO SOMETHING
(2) DO SOMETHING OTHER	
PROGRAM CARD
STANDARD SYSTEM CARD I
NAME MODULE
NAME STRUCTURE
NAME TYPE
OTHERNAME OTHERTYPE
== Examples ==
=== Hello world ===
COMMENT CARD
STANDARD SYSTEM CARD I
THESE CARDS PROVIDED
IN THIS FILE ARE THE
IMPLEMENTATION OF THE
FAMOUS "HELLO WORLD"
PROGRAM IN SYCPOL.
THE IMPLEMENTATION OF
THE "PRINT TO STREAM"
PROCEDURE FROM THE
STANDARD LIBRARY IS
INCLUDED FOR THOSE WHO
DON'T HAVE IT ALREADY.
THESE CARDS ARE
RELEASED IN SO CALLED
"PUBLIC DOMAIN".	COMMENT CARD
STANDARD SYSTEM CARD I
A SHORT NOTE ABOUT THE
FORMAT OF THE PROGRAM.
ALL SPACES INCLUDED
ARE MANDATORY.
THIS PROGRAM DOESN'T
CONTAIN THE WHOLE
STANDARD LIBRARY, ONLY
THE "PRINT TO STREAM"
PROCEDURE.
THIS PROGRAM USES ONLY
DATATYPES "INTEGER 8",
"STRING 8" AND "STRING
16".	PROGRAM CARD
STANDARD SYSTEM CARD I
DOCUMENTATION DIVISION
IDENTIFIER STRING 16
"HELLO WORLD"
AUTHOR NAME STRING 16
"FERGUSQ"
IMPORTS DIVISION	PS EXTERNAL PROCEDURE
MODULE NAME STRING 8
"STDIO"
IDENTIFIER STRING 16
"PRINT TO STREAM"
INPUT OUTPUT DIVISION	PROGRAM CARD
STANDARD SYSTEM CARD I
OPEN STANDARD OUTPUT
CLOSE STANDARD INPUT
.STDOUT OUTPUT STREAM
OUTS STANDARD OUTPUT
STORAGE DIVISION
.TEXT STRING 16
"HELLO WORLD!"
PROGRAM CODE DIVISION
PROGRAM CARD
STANDARD SYSTEM CARD I
MAIN PROCEDURE
(1) PROCEED TO !PS
 WITH ARGUMENTS
 .TEXT
 .OUTPUT
(2) RETURN
 WITH SUCCESS	PROGRAM CARD
STANDARD SYSTEM CARD I
DOCUMENTATION DIVISION
IDENTIFIER STRING 8
"STDIO"
AUTHOR NAME STRING 16
"FERGUSQ"
STORAGE DIVISION
.ZERO INTEGER 8
0
PROGRAM CODE DIVISION	PROGRAM CARD
STANDARD SYSTEM CARD I	PRINTTS PROCEDURE
IDENTIFIER STRING 16
"PRINT TO STREAM"
PARAMETER SECTION
$TEXT STRING 32
$STREAM OUTPUT STREAM
VARIABLE SECTION
$I INTEGER 8
0
$L INTEGER 8
UNDEFINED	PROGRAM CARD
STANDARD SYSTEM CARD I
PROCEDURE CODE SECTION
(1) CHANGE $L
 TO THE LENGTH
 OF $TEXT
(2) IF $I=$L (6)
(3) SEND THE CHARACTER
 AT $I
 IN $TEXT
 TO $STREAM
(4) INCREMENT $I
(5) JUMP (2)
(6) RETURN
 WITH SUCCESS
=== Fibonacci sequence ===
Fibonacci sequence in RS-SYCPOL.
PROGRAM CARD
STANDARD SYSTEM CARD I
FIBONACCI MODULE	ADD PROCEDURE
PARAMETER SECTION
$OUT INTEGER 8
.A INTEGER 8
.B INTEGER 8
VARIABLE SECTION
$B INTEGER 8
PROCEDURE CODE SECTION
(1) CHANGE $OUT TO .A
(2) CHANGE $B TO .B
(4) IF $B=.ZERO (8)
(5) INCREMENT $OUT
(6) DECREMENT $B
(7) JUMP (4)
(8) RETURN
 WITH SUCCESS	
PROGRAM CARD
STANDARD SYSTEM CARD I
FIBONACCI MODULE
STORAGE DIVISION
$A INTEGER 8
0
$B INTEGER 8
1
$C INTEGER 8
0
$I INTEGER 8
0
.TEN INTEGER 8
10
.SEPARATOR STRING 8
"/"	
PROGRAM CARD
STANDARD SYSTEM CARD I
FIBONACCI MODULE
DOCUMENTATION DIVISION
IDENTIFIER STRING 16
"FIBONACCI"
AUTHOR NAME STRING 16
"FERGUSQ"
IMPORTS DIVISION	PS EXTERNAL PROCEDURE
IDENTIFIER STRING 16
"PRINT TO STREAM"
MODULE NAME STRING 16
"STDIO"
PROGRAM CARD
STANDARD SYSTEM CARD I
FIBONACCI MODULE
MAIN PROCEDURE
(5) PROCEED TO !PS
 WITH
 $A
 .OUT
(6) PROCEED TO !PS
 WITH
 .SEPARATOR
 .OUT
(7) JUMP (1)
(8) RETURN
 WITH SUCCESS	
PROGRAM CARD
STANDARD SYSTEM CARD I
FIBONACCI MODULE
STORAGE DIVISION
.ZERO INTEGER 8
0
PROGRAM CODE DIVISION
MAIN PROCEDURE
(1) IF $I=.TEN (8)
(2) PROCEED TO !ADD
 WITH
 $C
 $A
 $B
(3) CHANGE $A TO $B
(4) CHANGE $B TO $C	
PROGRAM CARD
STANDARD SYSTEM CARD I
FIBONACCI MODULE
INPUT OUTPUT DIVISION
OPEN STANDARD OUTPUT
CLOSE STANDARD INPUT
.OUT OUTPUT STREAM
OUTS STANDARD OUTPUT		
== External resources ==
* VISCIM-JA – The first known implementation.
Category:LanguagesCategory:2014Category:Implemented