Skip to content

Lib creation

Jump to bottom
TheAssassin edited this page Jun 2, 2021 · 14 revisions

How to create an ACPL library

Table of contents

  1. Things to know
  2. How to create your lib
  3. How to publish your lib

Things to know

First thing to know, your lib has to be coded in Python.

If you use any external Python library, tell me, make sure that the library will be installed by the user once he downloads the lib.

How to create your lib

First, you need to create a Python file. This Python file follows the following conventions :

  • It has to be a python file (extension .py)
  • The name has to be in lower case, without symbols or numbers except the underline character (_).
  • If your lib has to use files, it has to create a folder with the name of lib, and the files have to be inside of that folder. If not, your lib will be rejected.

Your lib has a few elements to respect, in order for it to work. If you don't respect those rules, your lib won't work properly, or maybe won't work at all !

  • You have to import everything from recurrent_classes, by doing from recurrent_classes import *.
    • You need it for the libs to work.
    • It gives you access to a lot of functions :
      • error(line_number:int, error_type:str, message=None, *args)
        • This function allows you to throw an error when something goes wrong, and this error will stop the program automatically.
        • line_number can be accessed with the variable line_numbers if you request it (see later)
        • error_type can be whatever you want, but I recommend a CamelCase name, easily recognizable.
        • message and *args are the message you want to send to the user, with a clear explanation of the error. You can also not add this message, and in that case, it will simply say that A error_type has been raised on line line_number.
      • replace_line(file_name:str, line_num:int, text:str)
        • If your library uses files, you can use this function to replace one line of your file with another.
        • file_name : The file in which to replace the line.
        • line_num : The number of the line to replace. BEWARE ! IT STARTS BY 0 !
        • text : The text to put in that line. BEWARE ! If you only want to modify that line, don't forget the \n at the end !
      • delete_line(file_name:str, line_number:int, condition:bool=True)
        • If you want to delete a line of a file, this function is for you.
        • file_name : The file in which to delete the line.
        • line_number : The number of the line to delete. BEWARE ! IT STARTS BY 0 !
        • condition : If you want to put a condition in place of that statement, you can ! The line will only be deleted if this condition is True.
      • insert_line(path_to_file:str, index:int, value:str)
        • If you want to insert a line in a file, you can use this function.
        • file_name : The file in which to replace the line.
        • index : The number of the line to insert to. BEWARE ! IT STARTS BY 0 !
        • value : The text to put in that line.
      • And a few others, you can look them up by yourself. No I'm absolutely not tired of writing a documentation of my functions
  • Your code has to contain four functions with reserved names and parameters. Their returns have also to be fixed.
    • Function #1 : requirements(file)
      • This function gives the program the name of the variables you want to access, other than line (which is the line of code) and variables_container (which is where all the program's variables are stored).
      • The argument file tells you if the program is curently looking for the ACPL function or it's compiler equivalent. With that, you can decide which variables to choose depending on if it is equal to main (ACPL code) or compiler.
      • All the variables you can access are defined at line 73 and following in main.py.
      • You have to return a tuple containing all the variables you need to access. If you don't need any of them, return an empty tuple.
    • Function #2 : main(line, variables_container, other_args)
      • This function is basically the main function of your lib, the one that will analyse the current line of code, and act as consequence.
      • You have to return a tuple containing line, variables_container, and all the other variables you modified. For these other variables you modified, you need to return a list (or tuple) inside the tuple, as element n°2, containing the name of the variable to modify (as string) and its value.
        • Example of a correct return, if you modified the line_number and the code_lines :
        • return line, variables_container, ["line_number", line_number, "code_lines", code_lines]
      • This return has to be at the end of the function, and returned IN EVERY SINGLE CASE, EVEN IF NOTHING HAS BEEN MODIFIED.
      • All the variables you asked for in requirements() will be given as tuple in other_args, in the order you asked them.
      • For example, you asked for line_numbers and code_lines, other_args[0] will be equal to the value of line_numbers, and args[1] to the value of code_lines.
      • To begin parsing the line, I recommend using an if statement this way :
if line.startswith("<e.g. lib_name>"):
    line = line.replace("<e.g. lib_name> ", "", 1)
    # Your code
  • Function #3 : pytranslation(line, other_args)
    • In that function, you'll have to return like in the main one, parse like in the main one, but at the end, line has to be what will be inserted in the Python file.
    • For example, if I want to do the square root of a variable, line will be equal at the end to <variable> = sqrt(<value>)
    • As earlier, you have to return everything, at anytime, and to parse with the same if statement as earlier.
  • Function #4 : libs_to_import()
    • This function returns all the required libs by the final python file this way :
    • If the generated result does not require anything in order to work, just return a tuple containing to empty tuples, this way : return (tuple(), tuple())
    • If it only requires to import a full lib, (example : sys), the first tuple contains that lib : return (("sys",), tuple())
    • If you need more of those : return (("sys", "math", "tkinter"), tuple())
    • The other tuple contains all the functions from libs. If you want from json import load, then : return (tuple(), (("json", "load"),))
    • If you want from json import load, dump, then : return (tuple(), (("json", "load, dump"),))
    • And if you want from json import load and from math import * : return (tuple(), (("json", "load"), ("math", "*")))

You can do as you want for the rest of the file.

How to publish your lib

First, join the ACPL official Discord server (link here).

Then, go in the channel #lib-submitting and do as following :

  • Introduce yourself
  • Present your lib
  • Upload the lib file And wait for my answer !

In most of the cases, the lib will be accepted and will be downloadable by everyone.

Clone this wiki locally