Mikescher/www.mikescher.com
1
0
Fork 0
Code Actions

update BefunUtils README (only superficial)

Browse Source
This commit is contained in:
Mike Schwörer 2016-09-18 22:51:37 +02:00
parent 960feb9ed5
commit fedfffb6f2
Signed by: Mikescher
GPG Key ID: D3C7172E0A70F8CF
19 changed files with 46 additions and 2523 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -3,3 +3,4 @@ demos
#www/images/programs #www/images/programs
workspace.xml workspace.xml
*.secret *.secret
.idea/

1
.idea/.name generated
View File

@ -1 +0,0 @@
www.mikescher.de

14
.idea/codeStyleSettings.xml generated
View File

@ -1,14 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
<component name="ProjectCodeStyleSettingsManager">
<option name="PER_PROJECT_SETTINGS">
<value>
<XML>
<option name="XML_LEGACY_SETTINGS_IMPORTED" value="true" />
</XML>
</value>
</option>
<option name="PREFERRED_PROJECT_CODE_STYLE" value="Default (1)" />
</component>
</project>

2279
.idea/dataSources.ids generated
View File

File diff suppressed because it is too large Load Diff

18
.idea/dataSources.xml generated
View File

@ -1,18 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
<component name="DataSourceManagerImpl" format="xml" hash="3960530090">
<data-source source="LOCAL" name="MySQL - @localhost" uuid="c14641f8-3a7d-4423-b87f-bc19baba1a1f">
<driver-ref>mysql</driver-ref>
<synchronize>true</synchronize>
<jdbc-driver>com.mysql.jdbc.Driver</jdbc-driver>
<jdbc-url>jdbc:mysql://localhost:3306</jdbc-url>
<user-name>root</user-name>
<driver-properties>
<property name="zeroDateTimeBehavior" value="convertToNull" />
<property name="tinyInt1isBit" value="false" />
</driver-properties>
<libraries />
</data-source>
</component>
</project>

3
.idea/dictionaries/Mike.xml generated
View File

@ -1,3 +0,0 @@
<component name="ProjectDictionaryState">
<dictionary name="Mike" />
</component>

5
.idea/encodings.xml generated
View File

@ -1,5 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
<component name="Encoding" useUTFGuessing="true" native2AsciiForPropertiesFiles="false" />
</project>

19
.idea/frameworkRootSettings.xml generated
View File

@ -1,19 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
<component name="FrameworkRootSettings" id="Yii">
<option name="typedPaths">
<list>
<element elementPath="$PROJECT_DIR$/www/assets" typeId="assets_directory" />
<element elementPath="$PROJECT_DIR$/www/protected" typeId="protected_directory" />
<element elementPath="$PROJECT_DIR$/www/protected/controllers" typeId="protected_controllers_directory" />
<element elementPath="$PROJECT_DIR$/www/protected/extensions" typeId="protected_extensions_directory" />
<element elementPath="$PROJECT_DIR$/www/protected/models" typeId="protected_models_directory" />
<element elementPath="$PROJECT_DIR$/www/protected/runtime" typeId="protected_runtime_directory" />
<element elementPath="$PROJECT_DIR$/www/protected/views" typeId="protected_views_directory" />
<element elementPath="$PROJECT_DIR$/www/protected/views/layouts" typeId="protected_views_layouts_directory" />
<element elementPath="$PROJECT_DIR$/www/themes" typeId="themes_directory" />
</list>
</option>
</component>
</project>

11
.idea/inspectionProfiles/Project_Default.xml generated
View File

@ -1,11 +0,0 @@
<component name="InspectionProjectProfileManager">
<profile version="1.0" is_locked="false">
<option name="myName" value="Project Default" />
<option name="myLocal" value="false" />
<inspection_tool class="SpellCheckingInspection" enabled="false" level="TYPO" enabled_by_default="false">
<option name="processCode" value="true" />
<option name="processLiterals" value="true" />
<option name="processComments" value="true" />
</inspection_tool>
</profile>
</component>

7
.idea/inspectionProfiles/profiles_settings.xml generated
View File

@ -1,7 +0,0 @@
<component name="InspectionProjectProfileManager">
<settings>
<option name="PROJECT_PROFILE" value="Project Default" />
<option name="USE_PROJECT_PROFILE" value="true" />
<version value="1.0" />
</settings>
</component>

5
.idea/misc.xml generated
View File

@ -1,5 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
<component name="ProjectRootManager" version="2" />
</project>

9
.idea/modules.xml generated
View File

@ -1,9 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
<component name="ProjectModuleManager">
<modules>
<module fileurl="file://$PROJECT_DIR$/.idea/www.mikescher.de.iml" filepath="$PROJECT_DIR$/.idea/www.mikescher.de.iml" />
</modules>
</component>
</project>

5
.idea/scopes/scope_settings.xml generated
View File

@ -1,5 +0,0 @@
<component name="DependencyValidationManager">
<state>
<option name="SKIP_IMPORT_STATEMENTS" value="false" />
</state>
</component>

7
.idea/vcs.xml generated
View File

@ -1,7 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
<component name="VcsDirectoryMappings">
<mapping directory="$PROJECT_DIR$" vcs="Git" />
</component>
</project>

11
.idea/www.mikescher.de.iml generated
View File

@ -1,11 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<module type="WEB_MODULE" version="4">
<component name="NewModuleRootManager">
<content url="file://$MODULE_DIR$">
<excludeFolder url="file://$MODULE_DIR$/demos" />
</content>
<orderEntry type="inheritedJdk" />
<orderEntry type="sourceFolder" forTests="false" />
</component>
</module>

14
www/data/programs/desc/BefunUtils/01_Manuals/BefunExec.markdown
View File

@ -1,6 +1,6 @@
BefunExec is a fast Befunge-93 interpreter. BefunExec is a fast Befunge-93 interpreter.
![BEFUNEXEC_MAINWINDOW](/data/programs/desc/BefunGen/01_Manuals/BefunExec_Main.png) ![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/BefunExec_Main.png)
BefunExec can either be controlled over the menu or by keyboard shortcuts. BefunExec can either be controlled over the menu or by keyboard shortcuts.
You can read about the shortcuts and the command line parameters in the console window of BefunExec. You can read about the shortcuts and the command line parameters in the console window of BefunExec.
@ -43,18 +43,8 @@ Over the menu you can change a few settings:
###Extended Syntax Highlighting ###Extended Syntax Highlighting
![BEFUNEXEC_ESH](/data/programs/desc/BefunGen/01_Manuals/BefunExec_ESH_example.png) ![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/BefunExec_ESH_example.png)
BefunExec can use BefunHighlight to highlight the program (= extended Syntax highlighting). BefunExec can use BefunHighlight to highlight the program (= extended Syntax highlighting).
It will automatically choose so if the program isn't too big and you haven't explicitly specified another highlighting method. It will automatically choose so if the program isn't too big and you haven't explicitly specified another highlighting method.
Be aware that when you run on top speed and BefunExec is getting slowed down a lot by BefunHighlight it will automatically change the highlighting method. Be aware that when you run on top speed and BefunExec is getting slowed down a lot by BefunHighlight it will automatically change the highlighting method.
##Additional
###Capture GIF
![BEFUNEXEC_CAPTUREGIFDIALOG](/data/programs/desc/BefunGen/01_Manuals/BefunExec_CaptureGifDialog.png)
With the menu point "Capture GIF" you can create an animated .gif animation of your running program.
You can set the amount of steps to capture and the animation delay between the steps. You can also set the final delay before the animation restarts.
There is also the "Automatic frame count" option, only use this if your program terminates in a reasonable amount of frames.

2
www/data/programs/desc/BefunUtils/01_Manuals/BefunRep.markdown
View File

@ -1,6 +1,6 @@
BefunRep is an command line tool to calculate Befunge93 number representations BefunRep is an command line tool to calculate Befunge93 number representations
![BEFUNREP_MAINWINDOW](/data/programs/desc/BefunGen/01_Manuals/BefunRep_Main.png) ![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/BefunRep_Main.png)
To execute BefunRep you need to open the windows command line (cmd.exe). To execute BefunRep you need to open the windows command line (cmd.exe).

10
www/data/programs/desc/BefunUtils/01_Manuals/BefunWrite.markdown
View File

@ -1,6 +1,6 @@
BefunWrite is an IDE to write and compile TextFunge, once started you will see the main window: BefunWrite is an IDE to write and compile TextFunge, once started you will see the main window:
![BEFUNWRITE_MAINWINDOW](/data/programs/desc/BefunGen/01_Manuals/BefunWrite_Main.png) ![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/BefunWrite_Main.png)
You can write your code in the center and see a summary of current constants/variables/methods on the right side. You can write your code in the center and see a summary of current constants/variables/methods on the right side.
On the bottom site you can also expand the tabs `Output` and `ErrorList`. On the bottom site you can also expand the tabs `Output` and `ErrorList`.
@ -35,9 +35,9 @@ With the build configurations dialog you can modify the build process
- **Name** - **Name**
###Execution ###Execution
> BefunExec Settings ####BefunExec Settings
- **Debugging Enabled**: Enable debugging options (warnings on unexpected behaviours) - **Debugging Enabled**: Enable debugging options (warnings on unexpected behaviours)
- **Start Paused**: Starts the program non-running - **Start Paused**: Starts the program non-running
@ -51,9 +51,9 @@ With the build configurations dialog you can modify the build process
- **Lifetime Tail**: The time (in ms) until the tail has faded away - **Lifetime Tail**: The time (in ms) until the tail has faded away
- **Start zoomed in on display**: Set the initial zoom fitting for the display - **Start zoomed in on display**: Set the initial zoom fitting for the display
###Code Generation ###Code Generation
> BefunGen Settings ####BefunGen Settings
- **Number literal representation**: The used algorithm for presenting number literals - **Number literal representation**: The used algorithm for presenting number literals
- **Optimize double string-mode**: Try to combine two adjacent `"` together - **Optimize double string-mode**: Try to combine two adjacent `"` together

144
www/data/programs/desc/BefunUtils/index.markdown
View File

@ -1,12 +1,12 @@
BefunUtils BefunUtils
======== ========
This is my collection of tools and libraries for the esoteric programming language [Befunge](http://esolangs.org/wiki/Befunge). This is my collection of tools, libraries and transcompilers for the esoteric programming language [Befunge](http://esolangs.org/wiki/Befunge).
It consists of the following core components: It consists of the following core components:
###![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/icon_BefunGen.png) [BefunGen](https://github.com/Mikescher/BefunGen): ###![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/icon_BefunGen.png) [BefunGen](https://github.com/Mikescher/BefunGen):
> A library to automatically generate Befunge-93 programs out of a imperative-programming-language > A Befunge-93 to multiple procedural languages (c, java, csharp, python) transcompiler
###![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/icon_BefunWrite.png) [BefunWrite](https://github.com/Mikescher/BefunWrite): ###![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/icon_BefunWrite.png) [BefunWrite](https://github.com/Mikescher/BefunWrite):
> A small editor for Textfunge, the language used by BefunGen - use this if you want to try BefunGen for yourself > A small editor for Textfunge, the language used by BefunGen - use this if you want to try BefunGen for yourself
@ -20,128 +20,54 @@ It consists of the following core components:
###![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/icon_BefunRep.png) [BefunRep](https://github.com/Mikescher/BefunRep): ###![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/icon_BefunRep.png) [BefunRep](https://github.com/Mikescher/BefunRep):
> A tool to calculate (the best) number-representation in Befunge-93 space > A tool to calculate (the best) number-representation in Befunge-93 space
###![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/icon_BefunCompile.png) [BefunCompile](https://github.com/Mikescher/BefunCompile):
> An *(non-general)* Befunge-93 compiler. Compile your Befunge-93 code to C, C# or Python
and a few testing/debugging applications: ###![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/icon_BefunRun.png) [BefunRun](https://github.com/Mikescher/BefunRun):
> A simple terminal tool to run a befunge93 program (with extended grid size) and output its output.
###![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/icon_BefunGen.png) [BefunGenTest](https://github.com/Mikescher/BefunGenTest):
> A test set for BefunGen
###![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/icon_BefunDebug.png) [BefunDebug](https://github.com/Mikescher/BefunDebug): ###![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/icon_BefunDebug.png) [BefunDebug](https://github.com/Mikescher/BefunDebug):
> A debug and test tool for BefunGen > A debug and test tool for BefunGen, BefunCompile, BefunHighlight, etc
&nbsp;
> **NOTE:** Set up
> ==========
> If you don't know the esoteric language Befunge I can refer you to the [esolang page](http://esolangs.org/wiki/Befunge) and my own [tutorial](/blog/2/Lets_do_Befunge93)
## BefunWrite You can either download the binaries from [www.mikescher.com](http://www.mikescher.com/programs/view/BefunUtils).
BefunWrite is the main program that uses all the other parts. Or you can setup the Solution by yourself:
It's an IDE in which you can write a program in *TextFunge*, and compile it to valid Befunge-98 code.
> **NOTE:** - Clone the **BefunUtils** repository
> - Clone all the subproject repositories into subfolder *(or simply execute CLONE_ALL.bat)*
> While the generated Code practically is Befunge-98, you can use it in nearly every Befunge-93 interpreter. - *(eg clone BefunExec into the folder /BefunExec)*
> Because it doesn't use a single command, which was not defined in Befunge-93, the only non-Befunge-93 feature is the extended file size. - Open the solution file in Visual Studio *(or build all projects with the BUILD_ALL.bat script)*
> Because this tool can generate fairly big Befunge-93 code, it often exceeds the size of 80x25, and is so no longer totally valid Befunge-93 code.
> But for the sake of confusion I will refer in the rest of these documents to it as Befunge-93 code.
In BefunWrite you write your source code in the, specially for this developed, language **TextFunge**. Screenshots
BefunWrite supports you in this process with a lot of the basic IDE features you already know from other IDE's. ==========
After written you can compile your TextFunge code into BEfunge-93 code and execute it in **BefunExec**.
The main advantage for you is how you can easily generate even complex programs in Befunge. BefunExec:
Because TextFunge supports all the basic features of a procedural language you can use constructs like: ![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/BefunExec_Main.png)
- if-clauses and switch-cases BefunWrite:
- for-loops, while-loops, repeat-until-loops ![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/BefunWrite_Main.png)
- methods
- recursion
- global and local variables with different data-types
- GOTO's
- arithmetical and logical expressions
BefunWrite also provides an easy interface for the multiple compiler-settings, for more information please visit the individual manuals. BefunRep:
![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/BefunRep_Main.png)
## BefunGen BefunHighlight:
![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/BefunExec_ESH_example.png)
BefunGen is the core of this compilations. It's a compiler for for TextFunge and a code generator for Befunge. BefunCompile:
Essentially it performs the conversion between TextFunge and Befunge. Most of the generated Befunge programs could be a lot smaller if an actual person would take the time writing them. ![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/BefunCompile_Main_example.png)
That is the case because the generated Befunge code has a lot of organisation code included. It needs to manage the global variables and also the local ones. The local variables need initialization and in case of a different method call their current state needs to be saved. Also there has to be a call-stack to return to previous methods and re-initialization code when you jump back into methods.
This is important to understand, while I always try to optimize the generated code as much as I can it will always be a good amount bigger (and slower) than actual human-made code. This is also the case because there are neat little "tricks" and design concepts in Befunge that you just can't express in a procedural language. BefunCompile (Graph display of [Euler_Problem-002](https://github.com/Mikescher/Project-Euler_Befunge/blob/master/Euler_Problem-002.b93) Level **0**) *(via [BefunDebug](https://github.com/Mikescher/BefunDebug))*:
![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/BefunCompile_Graph-0_example.png)
But thats not really the problem, because the target of BefunGen is **not** generate code that could also be made by hand. The target code size is code so big that it would be totally impractical to write by hand (without spending days and weeks on it). BefunCompile (Graph display of [Euler_Problem-002](https://github.com/Mikescher/Project-Euler_Befunge/blob/master/Euler_Problem-002.b93) Level **2**) *(via [BefunDebug](https://github.com/Mikescher/BefunDebug))*:
![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/BefunCompile_Graph-2_example.png)
BefunGen itself is not a standalone program, but a simple library. You are free to use the DLL in your own program (but beware of the license, please give me credits...). If you need help how to use it you can either simply look at the source code (of BefunGen or BefunWrite) or write me a friendly mail. BefunCompile (Graph display of [Euler_Problem-002](https://github.com/Mikescher/Project-Euler_Befunge/blob/master/Euler_Problem-002.b93) Level **3**) *(via [BefunDebug](https://github.com/Mikescher/BefunDebug))*:
![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/BefunCompile_Graph-3_example.png)
## BefunExec BefunCompile (Graph display of [Euler_Problem-002](https://github.com/Mikescher/Project-Euler_Befunge/blob/master/Euler_Problem-002.b93) Level **5**) *(via [BefunDebug](https://github.com/Mikescher/BefunDebug))*:
![](https://raw.githubusercontent.com/Mikescher/BefunUtils/master/README-FILES/BefunCompile_Graph-5_example.png)
BefunExec is a fast Befunge-93 interpreter (without any program-size limitations) and a simple tool to execute and debug the generated Befunge-93 files.
While developing BefunGen I encountered the problem that not many interpreters where able to execute my programs.
Because of the properties of my generated code I needed an interpreter that was
- really fast, it needed to execute really many executions per second
- able to open and display large to *extremely* large programs
- able too zoom in programs (because they can be large)
- able to debug the program (show stack, output, input, breakpoints, single-step ...)
As you can imagine, I didn't find an interpreter that fitted my needs and so I wrote my own.
The big point that makes BefunExec unique is it's very high speed. On my machine (and its not really a good one) I reach a maximum speed of **6.5 MHz**. This are over **6 million** executions per second, enough for most of my programs :D.
Some other features are (as stated above) the ability to set breakpoints, step slowly through the program and zoom into specific parts.
Also you are able to capture the program execution as a gif animation.
One other big feature is the integration of BefunHighlight, which will be explained in the BefunHighlight section below.
## BefunHighlight
BefunHighlight is just a helper library mainly for BefunExec.
BefunExec has normal Befunge syntax-highlighting implemented, that means that every character is colored based on its function.
The problem here is that there may be code that never gets executed (not part of the real program), or there may be code that only gets used inside of string-mode (so the function doesn't matter, only the ASCII value).
BefunHighlight tries to solve this by evaluating every possible path an program can execute and so calculating the ways a single command is used.
Based on these informations it's now possible for another program to better highlight the source code.
Be aware that **p**ut and **g**et operations will invalidate the calculated values and it is needed to update them.
## BefunRep
A common problem with Befunge is the *(efficient)* representation of big numbers. *(= putting a number on the stack with the least amount of instructions)*
BefunRep is a commandline tool to generate a list of representations for all numbers in a specified range. I'm pretty sure the calculation of the optimal representation is a NP complete. But BefunRep tries to to find good representations for all numbers via various algorithms. And it does a pretty good job. It finds for all the numbers between -1 million and +1 million representations with a maximum of eleven characters.
Here an example call to BefunRep:
> **\> BefunRep.exe -lower=0 -upper=1000 -iterations=3 -stats=3 -q -safe="safe.bin" -out="out.csv" -reset**
This calculates the numbers from **0** to **1000**.
With a maximum of **3** iterations *(use -1 to calculate until no more improvmenets can be found)*
Safe the results in binary format in the file **safe.bin**
If the safe already exists it will be reseted (-**reset**)
And exports the results readable to **out.csv**
You can also update an existing safe
> **\> BefunRep.exe -safe="safe.bin" -iterations=-1**
Or don't calculate anything and only output an existing safe into another format
> **\> BefunRep.exe -safe="safe.bin" -iterations=0 -stats=3 -out="out.json"**
Here an example of a few calculated values:
Number | Representation
-------|----------------
113564 | `"tY!"**3/`
113565 | `"qC-"**3/`
113566 | `"[' "**2-`
113567 | `"[' "**1-`
113568 | `"[' "**`
113569 | `"~~U"++:*`
113570 | `"[' "**2+`
113571 | `"wj"*5+9*`
113572 | `"[' "**4+`
113573 | `"[' "**5+`
113574 | `"E~(&"*+*`