##
# @file filestrings.py
# @author Douglas Quigg (dstroy0 dquigg123@gmail.com)
# @brief CLI filestrings
# @version 1.0
# @date 2022-08-02
# @copyright Copyright (c) 2022
# Copyright (C) 2022 Douglas Quigg (dstroy0) <dquigg123@gmail.com>
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# version 3 as published by the Free Software Foundation.
# TODO move license string to its own variable
## file construction strings
[docs]
class CLIFileStrings(object):
"""contains all cli filestrings except config.h which is read from the lib root/src/config and regenerated
Args:
object (object): base object specialization
"""
## the constructor
def __init__(self) -> None:
"""the constructor"""
super(CLIFileStrings, self).__init__()
CLIFileStrings.version = self.version
self.version = self.version
CLIFileStrings.lib_version = self.lib_version
self.lib_version = self.lib_version
## library version
lib_version = ""
## version is implanted in all docstrings
version = ""
## library license
lib_license_md = """
Copyright (c) {docs_year} Douglas Quigg (dstroy0) <dquigg123@gmail.com>
License: GNU GPL3
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
version 3 as published by the Free Software Foundation. """
lib_license_cpp = """* Copyright (c) {docs_year} Douglas Quigg (dstroy0) <dquigg123@gmail.com>
*
* License: GNU GPL3
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* version 3 as published by the Free Software Foundation."""
## library.properties
lib_properties = """name=Autogenerated InputHandler CLI
version={lib_version}
author=dstroy0, Douglas Quigg <dquigg123@gmail.com>
maintainer=dstroy0, Douglas Quigg <dquigg123@gmail.com>
sentence=An Inputhandler microcontroller human interface.
paragraph=Generated by InputHandlers cli_gen_tool, this interface is comprised of user specified commands.
category=Communications
url=https://github.com/dstroy0/InputHandler
architectures=*
"""
## README.md
readmemd = """<!-- markdownlint-disable MD041 -->
# InputHandler autogenerated CLI readme
## tool, library, and generated CLI author
Douglas Quigg (dstroy0 dquigg123@gmail.com)
## user
{user}
## brief
This file is meant to familiarize you with using cli_gen_tool to integrate the generated CLI
into your project.
This readme file was generated by InputHandler's cli_gen_tool.
## tool version
{tool_version}
## InputHandler version
{lib_version}
## date
{docs_date}
## copyright
Copyright (c) {docs_year}
## license
{lib_license}
## purpose
This tool is meant to assist in constructing/sharing interfaces using InputHandler.
## docs
Documentation for the LIBRARY is available [here](https://dstroy0.github.io/InputHandler/lib/index.html)
Documentation for the TOOL is available [here](https://dstroy0.github.io/InputHandler/cli_gen_tool/index.html)
## help
If you don't see a topic relevant to your issue, please create a new discussion here: [InputHandler help/issue discussion](https://github.com/dstroy0/InputHandler/discussions/categories/help-issue-discussion)
Debugging assistance is available here: [InputHandler help/issue discussion](https://github.com/dstroy0/InputHandler/discussions)
## feature requests
To request a new feature please create a new discussion here: [InputHandler Ideas](https://github.com/dstroy0/InputHandler/discussions/categories/ideas)
## bug reporting
Please report bugs in the TOOL using this bug report form: [tool bug report format](https://github.com/dstroy0/InputHandler/blob/main/tools/bug_report.md) [tool bug report forum](https://github.com/dstroy0/InputHandler/discussions/59)
Please report bugs in the LIBRARY using this bug report form: [library bug report format](https://github.com/dstroy0/InputHandler/blob/main/src/bug_report.md) [library bug report forum](https://github.com/dstroy0/InputHandler/discussions/60)
## disclaimer
Use this library, and any included tools at your own risk!
The library's authors are not responsible for any damages which arise from the use of this tool (cli_gen_tool.py or its binaries) or library (InputHandler and dependencies).
The software (InputHandler library and cli_gen_tool.py and associated dependencies) conveys no warranty of any kind, implied or otherwise.
The user is ultimately responsible for configuring and implementing their own interface. But I will help you when and if I can, just post in the appropriate
area in the library's discussion forum.
## interface creation instructions
When first creating an interface, it is best practice to set an output stream, buffer size, and enable all builtins.
This makes debugging commands easy, it is trivial to disable output after verifying the interface behaves as intended.
{generated_code_section}
{include_instructions}
{function_instructions}
{copy_instructions}
{functions_with_return}
{setup_instructions}
{setup_code}
{loop_instructions}
{loop_code}
"""
# instructions
rdme_gen_inst = "## generated code"
rdme_include_inst = """
// copy/paste these preprocessor statements into your include section or at the top of your *.ino
#include "CLI/setup.h" """
rdme_copy_inst = "Copy/Paste these functions into your code before setup():"
rdme_function_inst = "These are wrappers generated for argument retrieval, or to put custom statements that run on command entry."
rdme_setup_inst = "Copy/Paste this statement into your setup() function, after initializing any Streams that you plan on using with the interface you build:"
rdme_loop_inst = "Copy/Paste this statement into your loop() function:"
## Automatically generated file docstring.
docfs = """/* Generated by cli_gen_tool version <{docs_version}>; using InputHandler version <{lib_version}> */
/**
* @file {docs_filename}
* @author Douglas Quigg (dstroy0 dquigg123@gmail.com)
* @brief {docs_brief}
* @version {docs_version}
* @date {docs_date}
*
* @copyright Copyright (c) {docs_year}
*/
/*
{lib_license}
*/
"""
## cli.h filestring
cli_h_fs = """
#if !defined(__CLI_SETUP__)
#define __CLI_SETUP__
#include "InputHandler.h"{arduino_compatibility}
#include "functions.h"
#include "parameters.h"
{outputbuffer}
const PROGMEM ih::ProcessName process_name = "{processname}"; // process name
const PROGMEM ih::EndOfLineChar process_eol = "{processeol}"; // process end of line characters
const PROGMEM ih::ControlCharSeq process_ccseq = "{processinputcontrolchar}"; // input control char sequence
const PROGMEM ih::WildcardChar process_wcc = "{processwildcardchar}"; // process wildcard char
// data delimiter sequences
const PROGMEM ih::DelimiterSequences pdelimseq = {{
{numdelimseq}, // number of delimiter sequences
{delimseqlens}, // delimiter sequence lens
{delimseqs} // delimiter sequences
}};
// start stop data delimiter sequences
const PROGMEM ih::StartStopSequences process_ststpseq = {{
{numstartstoppairs}, // num start stop sequence pairs
{startstopseqlens}, // start stop sequence lens
{startstopseqs} // start stop sequence pairs
}};
const PROGMEM ih::InputParameters input_prm[1] = {{
&process_name,
&process_eol,
&process_ccseq,
&process_wcc,
&pdelimseq,
&process_ststpseq}};
// constructor
{constructor}{setupfunction}{loopfunction}
#endif
// end of file
"""
## cli.h setup function
cli_h_setup_function_string = """
void InputHandler_setup()
{{{setupfunctionentry}{defaultfunction}{commandlist}{begin}{options}{setupfunctionexit}
}}
"""
## cli.h loop function
cli_h_loop_function_string = """
void InputHandler_loop()
{{{loopstatements}
}}
"""
## functions.h filestring
functions_h_fs = """
#if !defined(__FUNCTIONS_H__)
#define __FUNCTIONS_H__
#include "InputHandler.h"
{functionprototypes}
#endif
// end of file
"""
## functions.h function format string
functions_h_function_string = """void {functionname}(ih::Input* _{objectname}){{{statements}}}
"""
## single CommandParameters format string
commandparameters_string = """
/**
@brief ih::Parameters struct for {functionname}
*/
const PROGMEM ih::Parameters {functionname}_param[1] =
{{
{functionname}, // function pointer
ih::{wildcardflag}, // wildcard flag
"{commandstring}", // command string
{lencommandstring}, // command string num characters
{parentid}, // parent id
{commandid}, // this command id (tree unique)
{commanddepth}, // command depth
{commandsubcommands}, // number of subcommands
ih::{argumenthandling}, // argument handling
{minnumargs}, // minimum expected number of arguments
{maxnumargs}, // maximum expected number of arguments
/* UITYPE arguments */
{argtypearray}
}};
{commandconstructor}{newline}"""
## nested CommandParameters format string
nested_commandparameters_string = """
/**
@brief ih::Parameters struct for {functionname}
*/
const PROGMEM ih::Parameters {functionname}_param[1 /* root */ + {numberofchildren} /* child(ren) */] =
{{
{{
{functionname}, // function pointer
ih::{wildcardflag}, // wildcard flag
"{commandstring}", // command string
{lencommandstring}, // command string num characters
{parentid}, // parent id
{commandid}, // this command id (tree unique)
{commanddepth}, // command depth
{commandsubcommands}, // number of subcommands
ih::{argumenthandling}, // argument handling
{minnumargs}, // minimum expected number of arguments
{maxnumargs}, // maximum expected number of arguments
/* UITYPE arguments */
{argtypearray}
}},
{children}
}};
{commandconstructor}
"""
## parameters.h filestring
parameters_h_fs = """
#if !defined(__PARAMETERS_H__)
#define __PARAMETERS_H__
#include "cli.h"
{parameters}
#endif
// end of file
"""
## InputHandler return function
ih_return_function_code_fs = """
void {functionname}(ih::Input* _{objectname})
{{
// your statements here
}}
"""
cpp_md_tag = """
```cpp
{statements}
```"""
## file construction strings database
fsdb = {
"readme": {
"md": {
"filestring components": {
"cpp md tag": cpp_md_tag,
"return function code": ih_return_function_code_fs,
}
}
},
"CLI": {
"h": {
"filestring components": {
"arduino compatibility": '\n #include "InputHandler.cpp"\n',
"outputbuffer": "\nchar {outputbuffername}[{buffersize}] = {bufferchar}; // output buffer size\n",
"classoutput": "({input_prm}, {outputbuffer}, buffsz({outputbuffer}))",
"constructor": "ih::Input {objectname}{classoutput};\n",
"setup function": cli_h_setup_function_string,
"loop function": cli_h_loop_function_string,
"addCommand": {
"call": "\n {objectname}.addCommand({commandparametersname});"
},
"defaultFunction": {
"call": "\n {objectname}.defaultFunction({defaultfunctionname}); // default function is called when user input has no match or is not valid"
},
"listCommands": {
"call": "\n {objectname}.listCommands(); // formats {outputbuffer} with the command list"
},
"listSettings": {
"call": "\n {objectname}.listSettings(); // formats {outputbuffer} with the process settings (uses a lot of ram; for setting and testing)"
},
"outputToStream": {
"call": "\n {objectname}.outputToStream({stream}); // class output"
},
"getCommandFromStream": {
"call": "\n {objectname}.getCommandFromStream({stream}); // parse input"
},
"begin": {
"call": "\n {objectname}.begin(); // Required. Returns true on success."
},
"setup function output": {
"stream": {
"entry": '\n {stream}.println(F("{outputstring}"));',
"exit": '\n {stream}.println(F("{outputstring}"));{ls}\n {objectname}.outputToStream({stream});{lc}\n {objectname}.outputToStream({stream});',
},
"buffer": {
"entry": '\n if ((buffsz({outputbuffer})-outputIsAvailable()) > strlen("{outputstring}")+1) {{\n snprintf_P({outputbuffer} + outputIsAvailable(), "{outputstring}");\n }}',
"exit": '\n if ((buffsz({outputbuffer})-outputIsAvailable()) > strlen("{outputstring}")+1) {{\n snprintf_P({outputbuffer} + outputIsAvailable(), "{outputstring}");\n }}{ls}{lc}',
},
},
},
"filestring": cli_h_fs,
}, # end setup h
}, # end setup
"functions": {
"h": {
"filestring components": {
"outputToStream": {
"call": " _{objectname}->outputToStream({stream});"
},
"listCommands": {"call": " _{objectname}->listCommands();"},
"listSettings": {"call": " _{objectname}->listSettings();"},
"function": functions_h_function_string,
"return function prototype": "\nextern void {functionname}(ih::Input* _{objectname});",
},
"filestring": functions_h_fs,
}, # end functions h
}, # end functions
"parameters": {
"h": {
"filestring components": {
"nested child": " *{functionname}_param{comma} // pointer to {functionname}_param{newline}",
"command constructor": "ih::Command {functionname}_({functionname}_param); // {functionname}_ command constructor",
"nested command constructor": "ih::Command {functionname}_({functionname}_param, nprms({functionname}_param), {maxdepth}); // {functionname}_ command constructor",
"parameters": commandparameters_string,
"nested parameters": nested_commandparameters_string,
},
"filestring": parameters_h_fs,
} # end parameters h
}, # end parameters
"library": {"properties": {"filestring": lib_properties}},
}
# end of file