yisusgaming / term

Term is a library that provides ways to read data from text files and convert it for use in CSharp.

Save configs in text files and use them in C#!

Term is a simple interpreter that can convert key-value pairs defined in text to C# dictionaries.

You can find here:

• Setup
• Docs
• Term's Syntax
• Features coming soon
• License

---

Getting Started

<!> This guide assumes that your project contains a csproj file.

1. Setup

First, you have to download the Term.zip zip file from the latest release. Once it's downloaded, unzip it.

There's also another method you could use, see it here.

Once you have the unzipped folder, place it inside your project.

Next, you have to add a reference to the file (Term.dll).

To do that, add this to your csproj:

<ItemGroup>
    <Reference Include="Term">
        <HintPath>PATH/TO/TERM.dll</HintPath>
    </Reference>
</ItemGroup>

<!> Replace "PATH/TO/TERM.dll" with the path where the dll is in your project.

<!> If you're using Visual Studio, you can add the reference via Visual Studio's GUI.

That's it! You've successfully finished the setup. Continue in the docs.

Any problems during the setup? Check the setup guide again. Still have problems? Post an issue so I can help you!

---

Docs

Jump to the example.

Namespaces

namespace Term;

---

Classes

namespace Term;

public static class TermInterpreter { }

The interpreter itself.

Methods:

1.  public static Dictionary<string, string> Interpret(string path)

   The Interpreter's method. This method reads a Term file located at a specified path and returns a Dictionary containing the keys and values that were found.

   1. Parameters:

      1. path
         Type: string
         Description: The absolute path to the file that will be interpreted.

   2. Returns

      new Dictionary<string, string>

      A dictionary containing the keys and values that were found in the file.

2.  public static void WriteToFile(string path, Dictionary<string, string>  termContent, bool replaceContent = true)

   Writes a dictionary into a term file.

   It automatically generates Term configs based on the dictionary provided.

   The method will also format correctly any key in the dictionary. So if the dictionary contains a key named "My Key" it will be formatted to "my_key" before writing it to the file.

   1. Parameters:

      1. path
         Type: string
         Description: The absolute path to the term file to write into.
      2. termContent
         Type: Dictionary<string, string>
         Description: The content that will be written in the file.
      3. replaceContent
         Type: bool
         Description: If true, replace all the contents in the term file.
         
         if false, append all the contents to the end of the file with a comment "# Written from C#:".
         
         This parameter is optional. Defaults to true.

---

Term's syntax

1. Comments

   Comments in Term are really simple.

   Every line starting with a # it's a comment and it's going to be ignored by the Interpreter.

   Example:

   # This is a comment
   

2. Configs

   Configs are made of key-value pairs.

   A config is how we call these key-value pairs in Term.

   The key is separated from the value by this symbol: ->

   Example:

   my_key -> My value
   

   It's important that these configs are declared on a single line, otherwise it can cause errors.

Important aspects:

1. Any empty line found in the Term file is going to be ignored by the Interpreter.
2. The keys should be named using snake_case.
3. string values don't need to be surrounded by "".

---

Example

Let's code a simple example using Term.

Assuming we already created a dotnet project and we did the setup...

First, let's start by creating our Term file and writing some configs:

# Epic configs going here

# Window
window_title -> My Window
window_color -> LIMEGREEN

# User
username -> YisusGaming
epic_stuff -> Yes it's epic

Now, let's save this file, in my case, I'm saving the Term file next to my Program.cs file.

The file structure is something like this:

Project Folder
    | Program.cs
    | Term.dll
    | test.term
    | project.csproj

Note: test.term is the name I gave to the file.

Ok, let's go into the Program.cs.

First, we have to make sure the Term namespace is being use in the C# file:

using Term;

That way, we can use the Interpret method from the TermInterpreter class.

Now, the Interpret method needs one argument: The path to the file that will be interpreted. In order to give it the path, we can use the Path.GetFullPath() method included in C#.

In my case, It will be something like this:

string path = Path.GetFullPath("test.term");

Note: This is inside of C#'s Main method.

We call Path.GetFullPath and we pass in the path to our Term file, relative to the project's folder.

<!> Remember: The file structure in this example is like this.

Now that we got the Term's file path, we can call TermInterpreter.Interpret and give it the path!

Dictionary<string, string> load = TermInterpreter.Interpret(path);

Notice that, I'm creating a variable called load to store the Dictionary that this method returns.

And we're done! The Interpret method does everything for us and returns a Dictionary with the keys and values in our term file!

That means: Now we can access these values using the keys.

For example: We can now access the config we created before called window_title and print the value in console:

Console.WriteLine(load["window_title"]);

<!> Remember: load was the name I give to my Dictionary with all the keys and values.

And should print us the value of window_title!

Full code of the Example:

using System;
using System.Collections.Generic;
using Term;

namespace MyProgram
{
    class Program
    {
        public static void Main(string[] args)
        {
            string path = Path.GetFullPath("test.term"); // Get the full path from a path relative to our project's folder
            Dictionary<string, string> load = TermInterpreter.Interpret(path); // Interpret the file
            Console.WriteLine(load["window_title"]); // Should print the value!
        }
    }
}

Important notes

1. You may get errors by trying to accessing a keys that isn't in the returned dictionary. This can happen for reasons like the key being not defined at the term file.

   You can manage these errors as you want.

Any problems during the example? Check the example again. Still have problems? Post an issue so I can help you!

---

Coming soon

1. Arithmetic operations in Term values.

---

License

Term by YisusGaming is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.