This script transforms bash scripts into php-ish that Doxygen can parse. More...

Functions
	test ()
	This is a function just to test the function declaration option not used in the rest of this document.
	test2 ()
	This is a function just to test the function declaration option not used in the rest of this document.
	test3 ()
	This is a function just to test the function declaration option not used in the rest of this document.
	get_next_char ()
	Reads the next character from the input stream.
	strip_quotes_if_variable ($arg1)
	Removes the leading and trailing double quotes " from the given string.
	consume_whitespaces ($arg1)
	Discard whitespaces (except newline) from the input stream.
	consume_until_cmd_separator ()
	Append everything to $token untill a command separator is encountered.
	consume_until_non_word_char ()
	Append everything to $token untill a non word character is encountered.
	consume_until_closing_quote ($arg1)
	Append everything to $token untill a closing quote is encountered.
	consume_until_closing_square_bracket ()
	Append everything to $token until the matching closing bracket (']') is encountered.
	consume_until_closing_parenthesis ()
	Consumes all characters until a matching closing parenthesis is found.
	consume_until_space ()
	Append everything to $token untill a whitespace is encountered.
	parse_comment ()
	Parse the comment and add it to the inherited composition array.
	parse_variable ()
	Parse a variable and add it to the inherited composition array.
	parse_function ()
	Parse a function declaration and add it to the inherited composition array.
	parse_command ()
	Parse a function or command call and add it to the inherited composition array.
	consume_until_keyword ()
	consumes input until the keyword ($arg1) has been found.
	parse_flow_control ()
	Parse a flow control statement and add it to the inherited composition array.
	parse_case ()
	Gets the condition of the switch.
	parse_case_option ()
	Gets the value of the switch case.
	parse_assignment ()
	Extract variable name and value from assignment statements.
	parse ()
	Parses an sh file into a composition.
	get_composition_element_size ($arg1)
	Calculate the offset of the next element in components based on the current one.
	update_function ($arg1)
	Extract function arguments ($n) and updates the function accordingly.
	analyse ()
	Analyses the composition and updates information if required.
	parse_condition ()
	Helper for sanitize_condition, parses the condition into variables and operators.
	sanitize_condition ()
	Helper for write_as_php, cleans up the conditionals.
	sanitize_var ($arg1)
	Sanitize a variable.
	sanitize_assignment ($arg1)
	Sanitize an assignment (right hand side argument of assignment).

Variables
const	$C_SUCCESS = 0
	Return value for success.
const	$C_PARSE_ERROR = 1
	Return value on parse error.
const	$C_ANALYSIS_ERROR = 2
	Return value on error when analysing parsed composition.
const	$C_WRITE_ERROR = 3
	Return value on error when writing result.

Detailed Description

This script transforms bash scripts into php-ish that Doxygen can parse.

Author: Pieter van der Star (info@.nosp@m.piet.nosp@m.ervan.nosp@m.ders.nosp@m.tar.n.nosp@m.l)
Modifications by: (unmodified)

Warning: Do not use this script if your input is large and you are impatient.

Copyright: This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Todo

Review function documentation.

Add support for [[ regex without if.

Add support for "source <script>".

Add support for line continuation ("\" followed by newline).

Add return type other than int if the function doesn't contain a return statement. (Also handle return void.)

Count the newlines in multiline condition (when using heredocs) for linenumber in error messages.

Bug

The line number for variable errors (such as incorrect flag to declare) seems to be one line too early.

When the source document is updated while the filter is running the filter sometimes ends up in an endless loop showing the error "Unknown item in get_composition_element_size".

This script works by parsing the Bash script file and then outputting matching PHP code on stdout. The parsing stores each tokens in one big flat array. This array is called composition. To identify each kind of token the first element is an identifier, which determines how many elements follow. Thy are stored as listed in the table below:

Purpose	Identifier	Elements[1]	Purpose of element
shebang	!	1	Contents of the shebang
Doxygen comment	d	1	Contents of the comment
comment	#	1	Contents fo the comment
newline	n	-
variable	v	1	Indicates readonly variable
		2	Type of the variable
		3	Name of the variable
		4	Assigned value, or empty if not assigned
function	f	1	Name of the function
		2	Number of parameters, can be 0 if none
		>2 (odd)	Name of the parameter
		>2 (even)	Type of the parameter
scope opening	{	-
scope closing	}	-
command/function call	c	1	The command
		2	Number of arguments, can be 0 if none
		>2	Parameter values
flow control	j	1	Type of control (if, while else etc)
		2	The condition
return statement	r	-
variable assignment	=	1	The operand
		2	The operator
		3	The value
whitespace	w	1	The value
switch option	o	1	The value
break statement (;;)		-

1 Elements is the index of the element after the identifier.

Note: The matching code may not be valid php but is good enough for Doxygen to parse.; Not all traits of the bash language map to php. This script tries to map as close as possible, and otherwise discards this information.

Definition in file doxygen-bash-filter.sh.

Function Documentation

◆ analyse()

analyse ( )

Analyses the composition and updates information if required.

Returns: Error code (for now always success) according to Return values.

Todo: Add error checking where applicable.

Definition at line 934 of file doxygen-bash-filter.sh.

Here is the call graph for this function:

◆ consume_until_closing_parenthesis()

consume_until_closing_parenthesis ( )

Consumes all characters until a matching closing parenthesis is found.

Returns: Error code according to Return values.

Postcondition: Updates inherited $token with all characters until the matching closing bracket is encountered.; Sets the inherited $char to the closing parenthes.

Definition at line 335 of file doxygen-bash-filter.sh.

◆ consume_until_closing_quote()

consume_until_closing_quote ( $arg1 )

Append everything to $token untill a closing quote is encountered.

Parameters

$arg1 Should the characters be appended to $token? (1 yes, !=1 no)

Returns: Error code according to Return values.

Postcondition: Updates inherited $token (depending on $arg1) with all characters until a closing quote is encountered.; Sets the inherited $char to the closing quote.

Definition at line 279 of file doxygen-bash-filter.sh.

Here is the caller graph for this function:

◆ consume_until_closing_square_bracket()

consume_until_closing_square_bracket ( )

Append everything to $token until the matching closing bracket (']') is encountered.

Returns: Error code according to Return values.

Postcondition: Updates inherited $token with all characters until the matching closing bracket is encountered.; Sets the inherited $char to the closing bracket.

Definition at line 305 of file doxygen-bash-filter.sh.

◆ consume_until_cmd_separator()

consume_until_cmd_separator ( )

Append everything to $token untill a command separator is encountered.

Returns: Error code according to Return values.

Postcondition: Updates inherited $token with all characters until a command separator is encountered.; Sets the inherited $char to the separator character (except when "<space>#", then sets to "#".

Note

Separators are:

"\n"
";"
"<non-newline whitespace>#"

Definition at line 234 of file doxygen-bash-filter.sh.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ consume_until_keyword()

consume_until_keyword ( )

consumes input until the keyword ($arg1) has been found.

Parameters

$arg1 Keyword to search for.

Returns: Error code according to Return values.

Return values

$C_SUCCESS	if keyword found.
$C_PARSE_ERROR	if keyword not found before end of file occurred.

Postcondition: Sets the inherited $token to everything before the keyword. Sets the inherited $char to the first whitespace following the keyword.

Todo: handle parenthesis, if keyword is within the parenthesis it doesn't count.

Definition at line 567 of file doxygen-bash-filter.sh.

Here is the call graph for this function:

◆ consume_until_non_word_char()

consume_until_non_word_char ( )

Append everything to $token untill a non word character is encountered.

Returns: Error code according to Return values.

Postcondition: Updates inherited $token with all characters until a non word character is encountered.; Sets the inherited $char to the non word character

Note

Word characters are:

Letters A to Z both upper and lowercase
The underscore character ("_")

Definition at line 266 of file doxygen-bash-filter.sh.

Here is the call graph for this function:

◆ consume_until_space()

consume_until_space ( )

Append everything to $token untill a whitespace is encountered.

Returns: Error code according to Return values.

Postcondition: Updates inherited $token with all characters until a whitespace is encountered.; Sets the inherited $char to the first whitespace.

Definition at line 362 of file doxygen-bash-filter.sh.

Here is the call graph for this function:

◆ consume_whitespaces()

consume_whitespaces ( $arg1 )

Discard whitespaces (except newline) from the input stream.

Parameters

$arg1 Should the characters be appended to token? (1 yes, !=1 no)

Returns: Error code according to Return values.

Postcondition: Sets the inherited $char to the first non-whitespace character gotten via get_next_char().; Updates inherited $token (depending on $arg1) with all characters until a closing quote is encountered.

Note: For the purposes of this function "\n" is not a whitespace character.

Definition at line 208 of file doxygen-bash-filter.sh.

Here is the caller graph for this function:

◆ get_composition_element_size()

get_composition_element_size ( $arg1 )

Calculate the offset of the next element in components based on the current one.

Parameters

$arg1 Index of the composition element to get the offset for.

Returns: The offset for this element.

Definition at line 825 of file doxygen-bash-filter.sh.

Here is the caller graph for this function:

◆ get_next_char()

get_next_char ( )

Reads the next character from the input stream.

Postcondition: Sets inherited $char with the next character, unless it is an escaped char in which case it.; Sets the char variable to two chars ( '\' and <char>).

Definition at line 183 of file doxygen-bash-filter.sh.

Here is the caller graph for this function:

◆ parse()

parse ( )

Parses an sh file into a composition.

Returns: Error code (for now always success) according to Return values.

the input script. Call like parse < "inputfile.sh".

Todo: make this a switch for use during debugging?

Todo: why do we have an extra space between return and value?

Definition at line 696 of file doxygen-bash-filter.sh.

◆ parse_assignment()

parse_assignment ( )

Extract variable name and value from assignment statements.

Returns: Error code (for now always success) according to Return values.

Precondition: Expects the inhertied $token to be filled with the value being assigned.

Postcondition: Clears the inherited $token.

Adds the assignment information to the composition.

Definition at line 666 of file doxygen-bash-filter.sh.

◆ parse_case()

parse_case ( )

Gets the condition of the switch.

Returns: Error code (for now always success) according to Return values.

Postcondition: Updates the condition field in the composition element.

Definition at line 633 of file doxygen-bash-filter.sh.

Here is the call graph for this function:

◆ parse_case_option()

parse_case_option ( )

Gets the value of the switch case.

Returns: Error code according to Return values.

Postcondition: Adds the case option to the composition.

Definition at line 649 of file doxygen-bash-filter.sh.

◆ parse_command()

parse_command ( )

Parse a function or command call and add it to the inherited composition array.

Returns: Error code according to Return values.

Precondition: Expects inherited $token to be set to the function name.; Expects inherited $char to be set to the first char after the function name.

Todo: conditionally add the thing being piped as argument based on command line parameter.

Definition at line 501 of file doxygen-bash-filter.sh.

◆ parse_comment()

parse_comment ( )

Parse the comment and add it to the inherited composition array.

Returns: Error code according to Return values.

Postcondition: Upon successful paring of the comment the inherited $token is cleared.; Sets the inherited $char to the first character after the comment.

Definition at line 378 of file doxygen-bash-filter.sh.

◆ parse_condition()

parse_condition ( )

Helper for sanitize_condition, parses the condition into variables and operators.

Definition at line 955 of file doxygen-bash-filter.sh.

Here is the call graph for this function:

◆ parse_flow_control()

parse_flow_control ( )

Parse a flow control statement and add it to the inherited composition array.

Returns: Error code according to Return values.

Precondition: Expects the inherited $token to contain the control flow keyword.

Postcondition: Clears the inherited $token upon successful return.

Definition at line 591 of file doxygen-bash-filter.sh.

◆ parse_function()

parse_function ( )

Parse a function declaration and add it to the inherited composition array.

Postcondition: Updates char to the last char of the function.

Definition at line 474 of file doxygen-bash-filter.sh.

◆ parse_variable()

parse_variable ( )

Parse a variable and add it to the inherited composition array.

Returns: Error code according to Return values.

Precondition: Expects the inherited $char to be set to the first character of the function to handle.

Postcondition: Clears the inherited $token upon completion. Sets the inherited char to the first char after the variable

Todo: add support for global

Todo: how to handle this? Seems only interesting with regards to arguments which then get a reference instead of value.

Todo: Change name handling so a name of the shape "$name" (including the quotes is allowed. Quick fix now allows both " and $ everywhere in the name.

Definition at line 409 of file doxygen-bash-filter.sh.

Here is the call graph for this function:

◆ sanitize_assignment()

sanitize_assignment ( $arg1 )

Sanitize an assignment (right hand side argument of assignment).

Parameters

$arg1 Assignment to sanitize

Returns: Error code according to Return values.

Postcondition: Updates inherited $assignment to the sanitized value.

clean the switch option value and replace single | or operator with phps dual ||.

Parameters

$arg1 The option string to sanitize.

Precondition: Expects to inherit clean variable named option to polate with the sanitized option.

Write the php

Parameters

$arg1 Include the <?php and ?> tags. If value is 1 then the tags are included,

Returns: Error code (for now always success) according to Return values.

Writes the inherited composition as php to stdout.

Variable for iterating over the composition.

Todo: When parsing, exclude trailing ;

Todo: Add check on value being * and insert default: instead.

Todo

Todo: Add check on value being multiple (using |) and insert "||" instead.

Main function

Parameters

$arg1 Input file to rewrite to doxygen parsable php.

Returns: Error code according to Return values.

Todo: Add flag to write to file instead of stdout (for uses outside doxgen and debugging).

Todo

Todo: Add getopt.

Definition at line 1129 of file doxygen-bash-filter.sh.

◆ sanitize_condition()

sanitize_condition ( )

Helper for write_as_php, cleans up the conditionals.

Returns: Error code according to Return values.

Precondition: Expects the inherited $condition variable to be populated with the condition to sanitize.

Postcondition: Updates the inherited $condition variable with the sanitized version.

Removes bash brackets around condition. The behaviour is too tightly coupled to the writing of php for this to be part of tha analysis stage, in practise this function is doing both analysis and writing.

Definition at line 1021 of file doxygen-bash-filter.sh.

◆ sanitize_var()

sanitize_var ( $arg1 )

Sanitize a variable.

Parameters

$arg1 Variable to sanitize

Returns: Error code according to Return values.

Postcondition: Updates inherited $variable to the sanitized value.

The behaviour is too tightly coupled to the writing of php for this to be part of tha analysis stage, in practise this function is doing both analysis and writing.

Todo: test this

Definition at line 1101 of file doxygen-bash-filter.sh.

◆ strip_quotes_if_variable()

strip_quotes_if_variable ( $arg1 )

Removes the leading and trailing double quotes " from the given string.

Parameters

$arg1 Name of the string variable to remove the quotes from

Postcondition: The string named by $arg1 has its leading and trailing double quotes removed.

Definition at line 193 of file doxygen-bash-filter.sh.

◆ test()

test ( )

This is a function just to test the function declaration option not used in the rest of this document.

Definition at line 167 of file doxygen-bash-filter.sh.

◆ test2()

test2 ( )

This is a function just to test the function declaration option not used in the rest of this document.

Definition at line 171 of file doxygen-bash-filter.sh.

◆ test3()

test3 ( )

This is a function just to test the function declaration option not used in the rest of this document.

Definition at line 176 of file doxygen-bash-filter.sh.

◆ update_function()

update_function ( $arg1 )

Extract function arguments ($n) and updates the function accordingly.

Parameters

$arg1 Index of the fuction in the composition.

Returns: Error code according to Return values (for now always success).

Updates the function in the composition.

Definition at line 869 of file doxygen-bash-filter.sh.

Here is the call graph for this function:

Here is the caller graph for this function:

Functions

Variables

Detailed Description

Function Documentation

◆ analyse()

◆ consume_until_closing_parenthesis()

◆ consume_until_closing_quote()

◆ consume_until_closing_square_bracket()

◆ consume_until_cmd_separator()

◆ consume_until_keyword()

◆ consume_until_non_word_char()

◆ consume_until_space()

◆ consume_whitespaces()

◆ get_composition_element_size()

◆ get_next_char()

◆ parse()

◆ parse_assignment()

◆ parse_case()

◆ parse_case_option()

◆ parse_command()

◆ parse_comment()

◆ parse_condition()

◆ parse_flow_control()

◆ parse_function()

◆ parse_variable()

◆ sanitize_assignment()

◆ sanitize_condition()

◆ sanitize_var()

◆ strip_quotes_if_variable()

◆ test()

◆ test2()

◆ test3()

◆ update_function()