Package: zsim-cli
zsim-cliA simulator for an assembly like toy-languageExplore the docs »View Demo·Report Bug·Request FeatureTable of ContentsAbout The ProjectBuilt WithGetting StartedPrerequisitesInstallationUsageTokenizationValidationSimulatingUsing interactive modeRoadmapContributingLicenseContactAcknowledgmentsAbout The ProjectImplemented for the compiler building course after the winter semester 2020 on the Aachen University of Applied Sciences.Z-Code is a simplified assembly like toy language created to prove that compiling to a temporary language like Java-Bytecode can be much easier than going from a high-level language directly to assembly.Check out the syntax diagrams for detailed information on how the syntax of Z-Code is definedhere.Sublime syntax highlighting for Z-Code availablehere!It even works onTermux!(back to top)Built Withzsim-cli relies heavily on the following libraries.Clickpytest(back to top)Getting StartedTo get a local copy up and running follow these simple steps.PrerequisitesPython 3.6Head over tohttps://python.organd install the binary suitable for your operation system. Make sure you can run it:python--versionpipCheck if pip is already installed:pip--versionIf your python installation does not come with pip pre-installed visithttps://pip.pypa.ioto install it and then check again.InstallationClone the repositorygitclonehttps://gitlab.com/justin_lehnen/zsim-cli.gitcdzsim-cli(Optionally) create a python virtual environment and enter itpython-mvenvvenv# Windowsvenv/Scripts/activate.bat# Unix or MacOSsourcevenv/bin/activateInstall using pippipinstall-e.Run unit testspytestAnd you're set!(back to top)UsageFor more examples, please refer to theDocumentationTokenizationzsim-cli tokenize [ZCODE]--json / --no-jsonType:BooleanDefault:FalseIf the flag is set, the output will be in JSON format.The JSON schema is[ { "type": "<type>", "value": "<value>" }, ... ].Examples:# Tokenize code in JSONzsim-clitokenize"LIT 7; PRT;"--json# Pipe output to a JSON parser like jq for powerful postprocessing!zsim-clitokenize"LIT 7; PRT;"--json|jq-r.[].type-i, --input FILENAMEType:StringDefault:NoneSet an input file to read the Z-Code from.-will use the stdin.If you're using Windows, remember that the defaultcmd.exerequires two EOF characters followed by return (see examples).Examples:# Tokenize file programs/test.zczsim-clitokenize-iprograms/test.zc# Tokenize from stdinzsim-clitokenize-i-
LIT7;PRT;# Windows^Z<ENTER>
^Z<ENTER># Unix or MacOS^D^D--encoding TEXTType:StringDefault:"utf_8"Encoding to use when opening files with-i, --input.Refer to thePython docsfor possible values.Examples:# Use ASCII encodingzsim-clitokenize-iascii_encoded.zc--encodingasciiValidationzsim-cli validate [ZCODE]--json / --no-jsonType:BooleanDefault:FalseIf the flag is set, the output will be in JSON format.The JSON schema is{ "success": <boolean>, "message": "<string>" }.Examples:# Validate code in JSONzsim-clivalidate"LIT 7; PRT;"--json# Pipe output to a JSON parser like jq for powerful postprocessing!zsim-clivalidate"LIT 7; PRT;"--json|jq-r.message-i, --input FILENAMEType:StringDefault:NoneSet an input file to read the Z-Code from.-will use the stdin.If you're using Windows, remember that the defaultcmd.exerequires two EOF characters followed by return (see examples).Examples:# Validate file programs/test.zczsim-clivalidate-iprograms/test.zc# Validate from stdinzsim-clivalidate-i-
LIT7;PRT;# Windows^Z<ENTER>
^Z<ENTER># Unix or MacOS^D^D--encoding TEXTType:StringDefault:"utf_8"Encoding to use when opening files with-i, --input.Refer to thePython docsfor possible values.Examples:# Use ASCII encodingzsim-clivalidate-iascii_encoded.zc--encodingasciiSimulatingzsim-cli run [ZCODE]--json / --no-jsonType:BooleanDefault:FalseIf the flag is set, the output will be in JSON format.This flag isnot compatiblewith--step!The JSON schema is either{ "success": <boolean>, "message": "<string>" }for invalid zcode or{"success":true,"instruction_set":"<z|zfp|zds|zfpds>","initial_memory":{"..."},"code":"...","final_state":{"m":1,"d":[],"b":[],"h":{},"o":"",},"states":[{"state":{"Same as final_state"},"next_instruction":{"command":"...","mnemonic":"...","parameters":[1,2,3],},},"..."],}when the execution was successful.Examples:# Run code and output information about the states in JSONzsim-clirun"LIT 7; PRT;"--json# Pipe output to a JSON parser like jq for powerful postprocessing!zsim-clirun"LIT 7; PRT;"--json|jq-r.final_state.o-i, --input FILENAMEType:StringDefault:NoneSet an input file to read the Z-Code from.-will use the stdin.If you're using Windows, remember that the defaultcmd.exerequires two EOF characters followed by return (see examples).Examples:# Run file programs/test.zczsim-clirun-iprograms/test.zc# Run from stdinzsim-clirun-i-
LIT7;PRT;# Windows^Z<ENTER>
^Z<ENTER># Unix or MacOS^D^D--encoding TEXTType:StringDefault:"utf_8"Encoding to use when opening files with-i, --input.Refer to thePython docsfor possible values.Examples:# Use ASCII encodingzsim-clirun-iascii_encoded.zc--encodingascii-h, --memory TEXTType:StringDefault:"[]"Optionally overwrite the memory configuration for the executing code.The format is[ <addr>/<value>, ... ].Examples:# 10 + 5zsim-clirun"LOD 1; LOD 2; ADD;"-h"[1/10, 2/5]"--instructionsetType:StringDefault:"zfpds"Set the instruction set. Each instruction set has different available instructions to use.For exampleLODIcomes fromzds, whileLODLOCALis defined inzfp.When you are unsure, stick withzfpdswhere all instructions are available.Examples:# Use a specific instruction-setzsim-clirun"LIT 7; LIT 3; ADD;"--instructionset"z"--step / --no-stepType:BooleanDefault:FalseIf this flag is set, the execution will ask for confirmation after each step of the execution.This flag isnot compatiblewith--jsonor--full-output!Examples:# Go through Z-Code instruction by instructionzsim-clirun"LIT 7; POP;"--step--formatType:StringDefault:"({m}, {d}, {b}, {h}, {o})"The--formatoption allows you to customize the regular output of the simulation.Available placeholders:{m}= instruction counter{d}= data stack{b}= procedure stack{h}= heap memory{o}= outputExamples:# Use less components from the machine. This will yield "m: 5, h: [1/7], output: '7'"zsim-clirun"LIT 7; STO 1; LOD 1; PRT;"--format"m: {m}, h: {h}, output: '{o}'"--full-output / --no-full-outputType:BooleanDefault:FalseIf this flag is given, all states are printed on the standard output.--stepwill ignore this option.Examples:# This will print all five states on the standard outputzsim-clirun"LIT 7; STO 1; LOD 1; PRT;"--full-output-it, --interactive / --no-interactiveType:BooleanDefault:FalseUse this flag to start a Z-Code interpreter.Only--format,--instructionsetand-h, --memoryare compatible with this option.Examples:zsim-clirun-it(back to top)Using interactive modeWithzsim-cli run -ityou can start an interactive interpreter to execute Z-Code line by line.Using the interactive mode might present you with difficulties when using jumps or function calls.The following code willnotwork in interactive mode:LIT 6;
CALL(increment, 1,);
HALT;
increment: LODLOCAL 1;
LIT 1;
ADD;
RET;CALL(increment, 1,);will fail sinceincrementis not defined until later.To circumvent this issue two special commands have been added:#noexecand#exec.These commands push and pop frames in which commands are not directly executed but parsed and saved.
The following example does the same as the Z-Code above, but uses#noexecand#exec:> LIT 6;
> #noexec
#> f: LODLOCAL 1;
#> LIT 1;
#> ADD;
#> RET;
#> #exec
> CALL(f, 1,);Note the#in front of the prompt that tell how many#noexecframes are running.You are not limited to defining functions that way either! The next example uses#noexecdifferently:> #noexec          
#> add_and_sto: ADD;
#> STO 1;
#> HALT;     
#> #exec           
> LIT 4;           
> LIT 1;
> JMP add_and_sto;
> LOD 1;
> PRT;In the standard simulation modeHALTwould jump afterPRTbut since the last typed command wasJMP add_and_sto;it will jump continue right after the instruction we just sent off!(back to top)RoadmapCode executionMemory allocation in codeCommentsInteractive modeBetter -h, --memory parsingError handlingMore instruction setsDocumentationMore sample programsSee theopen issuesfor a full list of proposed features (and known issues).(back to top)ContributingContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make aregreatly appreciated.If you have a suggestion that would make this better, please fork the repo and create a merge request. You can also simply open an issue with the label "enhancement".
Don't forget to give the project a star! Thanks again!Fork the projectCreate your feature branch (git checkout -b feature/AmazingFeature)Commit your changes (git commit -m 'Add some AmazingFeature')Use pytest to run unit tests (pytest)Push to the branch (git push origin feature/AmazingFeature)Open a merge requestCodestyleFour space indentationOne class per fileVariables and functions are written insnake_caseClass names are written inPascalCase(back to top)LicenseDistributed under the Unlicense license. SeeLICENSEfor more information.(back to top)ContactJustin Lehnen -justin.lehnen@alumni.fh-aachen.de-justin.lehnen@gmx.deProject Link:https://gitlab.com/justin_lehnen/zsim-cli(back to top)AcknowledgmentsAachen University of Applied SciencesChoose an Open Source LicenseGitHub Emoji Cheat SheetImg Shields(back to top)