Package: cScell
cScellA framework written with python, in order to quickly create C shell projects on Linux envinronment.InstallNote: this package is thought to be used byLinuxplatforms.You can install cScell withpiporpip3:$pip3installcScellThe package is usually used as a global module. It is possible that a warning will appear during the installation, saying that the location of the package is not on the$PATHvariable. In order to be able to use it from any directory, add that location to the$PATHvariable.UsageSyntaxThe syntax of the command is:cScell[app_name][commands_json_path][output_dir_path]The three parameters are:app_name: The name of the project. Default:scell_project.commands_json_path: The path to the json file describing the commands of the shell program. Default:./commands.json.output_dir_path: The path where the project directory will be created. Default:./.ExamplesThis example will create in the current folder a project called "myProject":cScellmyProjectThis example will create in the parent folder a project called "myProject", with the commands described in "my-commands.json":cScellmyProject./my-commands.json../Usage as local module:The module could be actually used also as a local module, here is an example:fromcScell.cScellimportgenerate_scellAPP_NAME='myProject'JSON_COMMANDS='./my-commands.jsonOUTPUT_PATH='../'generate_scell(APP_NAME,JSON_COMMANDS,OUTPUT_PATH)Json formatYou can describe thecommandsof your c shell program with ajson file.In the commands json file:Each rootkeyis the name of acommandof the shell. Its value must be anobject.The special_argumentscommandis the command that could be executed when the user passes command line arguments to the program.An exception for what was said above is thepromptSymbolkey, that specifies thesymboldisplayedbefore each line of the prompt. Ifnot specified, its value will be>>.Foreach command, thefunctionproperty indicates thenameof the function thathandlesthat command.Foreach command, theargumentsproperty indicates the arguments accepted by that command. Its value must be anobject.Foreach arguments object, everykeyis thenameof an argument and its value must be anobject.Foreach argument value, the keytypeis mandatory and describes thevariable typeof the argument. The possible options are:int,long,float,double,char,char*,array<type>(wheretypeis one of the precedent types).Foreach argument value, the keyaliasis not mandatory and describes analias(single character) that could be used instead of the extended argument name.Foreach argument value, the keydefaultis not mandatory. If it is not specified, the argument is mandatory when the command is typed by the user. NB: Thebooltype isalways false as default. Thearraytypecan only be "NULL"as default if it is not a required argument.Foreach argument value, the keyminis not mandatory. It can be used withnumerictypes and indicates that the passed argument value must bebigger or equalthan the value ofmin.Foreach argument value, the keymaxis not mandatory. It can be used withnumerictypes and indicates that the passed argument value must belower or equalthan the value ofmax.Foreach argument value, the keydescriptionis not mandatory. It is the displayeddescription for the argumentwhen the commandhelpis executed.Foreach command, the keydescriptionis not mandatory. It is the displayeddescription for the commandwhen the commandhelpis executed.An example:{"promptSymbol":">>>","_arguments":{"function":"arguments","arguments":{"thing":{"type":"int","alias":"t","default":1,"min":0,"description":"The thing argument description"},"stuff":{"type":"float","alias":"s","max":10,"description":"The stuff argument description"},"ware":{"type":"array<char*>","alias":"w","default":"NULL","description":"The ware argument description"}}},"increment":{"function":"inc","arguments":{"number":{"type":"int","alias":"n","description":"The number to increment"},"amount":{"type":"int","alias":"a","default":1,"description":"How much will the number incremented"}},"description":"Increments a number"},"add":{"function":"add","arguments":{"first":{"type":"int","alias":"x","description":"The first addend"},"second":{"type":"int","alias":"y","description":"The second addend"}},"description":"Adds two addends"},"concat":{"function":"concat","arguments":{"strings":{"type":"array<char*>","default":"NULL","description":"The strings to concat"},"reverse":{"type":"bool","alias":"r","description":"If the strings will be in reversed order"}},"description":"Concats an array of strings"},"quit":{"function":"quit","description":"closes the program"}}ResultAt the end of execution, aproject foldercalled as you specified for theapp_nameargument will be created in theoutput_dir_paththat you specified.That folder isstructuredas specified below:There will be acompile.shbash script. It is the script tocompilethec generated source code. If it is not already executable, you can executesudo chmod +x compile.sh.There will be a[app_name].cfile, named as thename of the project. It will contain themain functionof the program, it imports thecommands interpretergenerated by the module and thecommands handlersthat you should implement and willrun the shell loop.There will be theshellutilsfolder, containing all thelibrariesthat make the shell work. These libraries are:colour, for a coloured outputconstructs, containing only header files, aboolean.hfor the boolean enum and ash_state.hfor the state of a command enum.logger, used by the shell to log errors or warnings.text, containing all the text functions and the advanced terminal.shell_utils, used by the shell_commands libraryshell_commands, the only one thatdependson thecommands.jsonfile passed before creating the project. It will contain the code thatparses the shell commandsprompted by the user andcalls the right function handlerThere will be thehandlersfolder, containing thehandlers.handhandlers.cfiles. You willeditthehandlers.cfiles in order to define the code that will be executed when the user prompts a specific command.There will be alsothreevariables exported byshell_commands.h:char *sh_last_command: It is the string variable containing the last prompted commandchar *sh_prompt_symbol: It is the variable whose value is the string that specifies thesymboldisplayedbefore each line of the prompt.bool sh_use_advanced_terminal: It is the boolean variable that determines if theadvanced terminalwill be used. The advanced terminal makes possible to the user to use theup and down arrowsto navigate thecommands cronology. Its default value istrue, but you can change it before thesh_loop();call in the[app_name].cfile.To start the program you just need to execute:cd[your_project_dir]sudochmod+x./compile.sh
./compile.sh
./[your_app_name]This will compile the c code and start the generate executable program.You shouldeditthehandlers.cfile to define the behaviour of each command.What the framework doesUnder the hood:All arguments containinghyphensin the name will be purged withunderscores.If the_argumentscommand was defined, if the users passescommand line argumentsthey will be parsed and the corrispondent handler executed.Aninfinite loopthatlistensfor the user's commands will be then executed.Allempty prompted lineswill be ignored.After a command is prompted, the program willcheck if the command exists. If not, it willdisplay a proper error message.If the command exists, it will beproperlyparsed.If arequired argumentmisses, avalueis invalid, avaluemisses or does not matchesprovided numerical ranges, an error will be displayed.Theextendedargument names should be preceded by two hyphens--while thealiasedargument names by a single hyphen-.If avalue without argumentwill be passed, a warning will be displayed, but it will not block the command.If all checks pass and the command is correctly parsed, the corrispondenthandler functionis called with the parsed arguments. You can easilyeditthehandlers.cfile and implement the handlers, which by default print the command name.If thehelpcommand is prompted, the documentation for all the commands will be displayedIf thehelp [command]command is prompted, the documentation for the given command will be displayedNotesThis framework works only forLinux.Onlynamedarguments are allowed. This means that all commands will be likeadd -x 1 -y 2orconcat --strings first second thirdbut commands likeadd 1 2will not be allowed.If a string parametercontains spaces, you can include it inside double apix such asconcat --strings "first string" "second string"