modulefdoc_fypp

A port to Fortran of the parts of Fypp, the preprocessor by Bálint Aradi, that the Fortran standard library needs, so that fdoc can read Fypp sources without running Python.

Fypp's directives hold Python expressions. A small evaluator here covers the ones in use: literals, lists, tuples, comprehensions, f-strings, slices, conditional expressions, and the functions and string methods listed in call_builtin and call_method. Anything else stops with an error that names it, and is left for later, as are the directives del, global, stop, nextarg and contains, direct calls with @: and @{...}@, and line numbering.

All state is in a fypp_t made for each file, so that files can be processed in parallel. As in the rest of fdoc, no function returns a deferred-length string (see example/slen_race.f90).

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Uses

Graphs

Uses

Used by

Variables

Name	Type	Attributes	Default	Description
C_EQ	integer	privateparameter	1
C_GE	integer	privateparameter	6
C_GT	integer	privateparameter	4
C_IN	integer	privateparameter	7
C_LE	integer	privateparameter	5
C_LT	integer	privateparameter	3
C_NE	integer	privateparameter	2
C_NOT_IN	integer	privateparameter	8
E_ADD	integer	privateparameter	5
E_AND	integer	privateparameter	10
E_CALL	integer	privateparameter	14
E_CLAUSE	integer	privateparameter	19
E_COMP	integer	privateparameter	18
E_COMPARE	integer	privateparameter	12
E_CONST	integer	privateparameter	1
E_FSTRING	integer	privateparameter	20
E_IF	integer	privateparameter	13
E_INDEX	integer	privateparameter	16
E_LIST	integer	privateparameter	3
E_METHOD	integer	privateparameter	15
E_MUL	integer	privateparameter	7
E_NAME	integer	privateparameter	2
E_NEG	integer	privateparameter	8
E_NOT	integer	privateparameter	9
E_OR	integer	privateparameter	11
E_SLICE	integer	privateparameter	17
E_SUB	integer	privateparameter	6
E_TUPLE	integer	privateparameter	4
FOLD_INDENT	integer	privateparameter	4	Fypp's default indentation of continuation lines
MAX_FRAMES	integer	privateparameter	256	how deeply scopes can nest
MAX_LINE	integer	privateparameter	132	Fypp's default longest line
N_ASSERT	integer	privateparameter	9
N_CALL	integer	privateparameter	7
N_DEF	integer	privateparameter	6
N_EVAL	integer	privateparameter	2
N_FOR	integer	privateparameter	4
N_IF	integer	privateparameter	3
N_MUTE	integer	privateparameter	8
N_SET	integer	privateparameter	5
N_TEXT	integer	privateparameter	1
NL	character(len=1)	privateparameter	achar(10)
T_END	integer	privateparameter	0
T_FSTR	integer	privateparameter	4
T_INT	integer	privateparameter	2
T_NAME	integer	privateparameter	1
T_OP	integer	privateparameter	5
T_STR	integer	privateparameter	3
TAB	character(len=1)	privateparameter	achar(9)
V_BOOL	integer	privateparameter	1
V_DICT	integer	privateparameter	6
V_INT	integer	privateparameter	2
V_LIST	integer	privateparameter	4
V_MACRO	integer	privateparameter	7
V_NONE	integer	privateparameter	0
V_STR	integer	privateparameter	3
V_TUPLE	integer	privateparameter	5

Types

block_tprivate

The parts of a directive.

body_tprivate

The nodes of a block.

expr_tprivate

An expression, compiled.

frame_tprivate

Local variables.

fypp_tprivate

The state of processing a file.

macro_tprivate

A macro.

node_tprivate

A piece of the document.

scan_tprivate

Reading an expression.

span_tprivate

Where a result of evaluation is in the output.

value_tprivate

A Python value.

Functions

at_wordpureprivate

pure logical function at_word(s, word)

True if the current token is word, as an operator or keyword.

end_of_linepureprivate

pure integer function end_of_line(text, from) result(at)

The position of the end of the line with position from: of its newline, or after the last line.

equalpurerecursiveprivate

pure recursive logical function equal(a, b) result(same)

True if a equals b.

find_namepureprivate

pure integer function find_name(c, name) result(id)

The number of name name, or 0.

fold_positionpureprivate

pure integer function fold_position(line, first, last) result(at)

Where to end the part of line after first, at most at last. Positions count from 0.

in_nameelementalprivate

elemental logical function in_name(ch)

True if ch can be part of a name.

is_blankelementalprivate

elemental logical function is_blank(ch)

True if ch is a blank or a tab.

is_spaceelementalprivate

elemental logical function is_space(ch)

True if ch is white space.

new_exprprivate

integer function new_expr(c, kind, a, b, third) result(id)

A new expression.

new_nodeprivate

integer function new_node(c, kind) result(id)

A new node.

skip_blankspureprivate

pure integer function skip_blanks(text, from) result(at)

The first position from from that is not a blank.

starts_nameelementalprivate

elemental logical function starts_name(ch)

True if ch can start a name.

trim_lengthpureprivate

pure integer function trim_length(text) result(n)

The length of text without blanks at its end.

trim_rightpureprivate

pure character(len=trim_length(text)) function trim_right(text) result(out)

text without blanks at its end.

truth_ofpureprivate

pure logical function truth_of(v) result(truth)

The truth of v.

Subroutines

add_bodyprivate

subroutine add_body(c, node, condition)

Add a block to node, with condition condition.

appendprivate

subroutine append(c, node)

Put node at the end of the block being read.

arithmeticrecursiveprivate

recursive subroutine arithmetic(c, kind, a, b, v)

a + b, a - b or a * b.

assign_targetsprivate

subroutine assign_targets(c, targets, v)

Set the variables targets to v, unpacking it if there are several.

bind_oneprivate

subroutine bind_one(c, id, v)

Bind one name in a comprehension.

bind_targetsprivate

subroutine bind_targets(c, targets, v)

Bind the names of a loop to v in a comprehension.

call_builtinrecursiveprivate

recursive subroutine call_builtin(c, name, args, v)

A builtin function: defined, dict, len, list, range, reversed, str, zip.

call_directiveprivate

subroutine call_directive(c, param, on_lines)

#:call name(arguments) or #:block name(arguments).

call_macrorecursiveprivate

recursive subroutine call_macro(c, which, positional, keywords, by_keyword, v)

Call macro which.

call_methodrecursiveprivate

recursive subroutine call_method(c, id, v)

A method: of strings startswith, format, join, strip and split, and of dicts get.

close_blockprivate

subroutine close_block(c, kind, word)

Leave a block, which must be of kind kind.

close_scopeprivate

subroutine close_scope(c)

Close the current scope.

comparerecursiveprivate

recursive subroutine compare(c, id, v)

A chain of comparisons.

compare_twoprivate

subroutine compare_two(c, op, a, b, holds)

One comparison.

compileprivate

subroutine compile(c, text, id)

Compile expression text.

control_directiverecursiveprivate

recursive subroutine control_directive(c, word, param, on_lines, path)

Act on control directive word.

copy_itemspureprivate

pure subroutine copy_items(from, to)

Copy from to the new array to.

copy_valueelementalrecursiveprivate

elemental recursive subroutine copy_value(to, from)

Copy a value, with what it holds.

def_directiveprivate

subroutine def_directive(c, param)

#:def name(arguments). Each argument's default is compiled to an entry of args, or 0 if none.

defineprivate

subroutine define(c, id, v)

Set variable id in the current scope.

define_macrorecursiveprivate

recursive subroutine define_macro(c, id)

Define the macro of node id, evaluating its defaults now.

evaluaterecursiveprivate

recursive subroutine evaluate(c, id, v)

Evaluate expression id.

evaluate_argsrecursiveprivate

recursive subroutine evaluate_args(c, id, positional, num_positional, keywords, by_keyword)

Evaluate the arguments of call id.

evaluate_callrecursiveprivate

recursive subroutine evaluate_call(c, id, v)

A call of a macro or a builtin function.

evaluate_fstringrecursiveprivate

recursive subroutine evaluate_fstring(c, id, v)

An f-string.

evaluate_slicerecursiveprivate

recursive subroutine evaluate_slice(c, id, v)

a[first:last].

expectprivate

subroutine expect(c, s, word)

Go past token word, which must come next.

failprivate

subroutine fail(c, message)

Record the first problem.

flush_textprivate

subroutine flush_text(c, text, first, last)

Add the text between first and last as a text node.

fold_linepureprivate

pure subroutine fold_line(line, b)

Fold a line in Fypp's default way, at a blank near the end of the line if there is one.

fold_outputprivate

subroutine fold_output(c, text, out)

Fold the long lines of text that hold results of evaluation. Others stay as they are.

fold_regionpureprivate

pure subroutine fold_region(text, b)

Fold each line of text.

for_directiveprivate

subroutine for_directive(c, param)

#:for names in iterable.

format_stringprivate

subroutine format_string(c, text, args, v)

text.format(args), for fields {} and {n}.

frame_roomprivate

subroutine frame_room(frame)

Make sure that one more variable fits in frame.

fypp_process

subroutine fypp_process(path, defines, includes, text, stat, errmsg)

The output of Fypp for file path. Each of defines is NAME or NAME=expression.

handle_directiverecursiveprivate

recursive subroutine handle_directive(c, kind, content, on_lines, path)

Act on a directive of type kind, which is $, # or @.

include_directiverecursiveprivate

recursive subroutine include_directive(c, param, path)

#:include "file".

internprivate

subroutine intern(c, name, id)

The number of name name, added if it is new.

items_ofprivate

subroutine items_of(c, v, list)

The items of v, which is iterated over.

lookupprivate

subroutine lookup(c, id, v, found)

Find the value of name id.

make_boolpureprivate

pure subroutine make_bool(truth, v)

Make a bool value.

make_intpureprivate

pure subroutine make_int(number, v)

Make an integer value.

make_rangeprivate

subroutine make_range(c, args, v)

range(...), as a list.

make_stringpureprivate

pure subroutine make_string(text, v)

Make a string value.

make_zipprivate

subroutine make_zip(c, args, v)

zip(...), as a list of tuples.

move_exprpureprivate

pure subroutine move_expr(from, to)

Move an expression, without copying what it holds.

move_nodepureprivate

pure subroutine move_node(from, to)

Move a node, without copying what it holds.

move_valuepureprivate

pure subroutine move_value(from, to)

Move a value, without copying what it holds.

next_tokenprivate

subroutine next_token(c, s)

Go to the next token.

open_blockprivate

subroutine open_block(c, node)

Enter block node.

open_scopeprivate

subroutine open_scope(c, up)

Open a scope that also sees frame up.

parse_andrecursiveprivate

recursive subroutine parse_and(c, s, id)

Operands of and.

parse_argumentsrecursiveprivate

recursive subroutine parse_arguments(c, s, id, closing)

The arguments of call id, up to closing.

parse_comparerecursiveprivate

recursive subroutine parse_compare(c, s, id)

Comparisons.

parse_comprehensionrecursiveprivate

recursive subroutine parse_comprehension(c, s, element, id)

The for clauses after the item element.

parse_filerecursiveprivate

recursive subroutine parse_file(c, path)

Read file path into the block being read.

parse_fstringrecursiveprivate

recursive subroutine parse_fstring(c, text, id)

An f-string, whose quotes and escapes are already gone.

parse_itemsrecursiveprivate

recursive subroutine parse_items(c, s, id, first, closing)

The items of a list or tuple, after the first, which is first.

parse_listrecursiveprivate

recursive subroutine parse_list(c, s, id)

An expression, or several separated by commas, which make a tuple.

parse_notrecursiveprivate

recursive subroutine parse_not(c, s, id)

An operand of not.

parse_orrecursiveprivate

recursive subroutine parse_or(c, s, id)

Operands of or.

parse_postfixrecursiveprivate

recursive subroutine parse_postfix(c, s, id)

A primary with what follows it: calls, subscripts and methods.

parse_primaryrecursiveprivate

recursive subroutine parse_primary(c, s, id)

A primary: a literal, a name, or something in brackets.

parse_productrecursiveprivate

recursive subroutine parse_product(c, s, id)

Factors multiplied.

parse_subscriptrecursiveprivate

recursive subroutine parse_subscript(c, s, object, id)

A subscript of object, or a slice.

parse_sumrecursiveprivate

recursive subroutine parse_sum(c, s, id)

Terms added and subtracted.

parse_testrecursiveprivate

recursive subroutine parse_test(c, s, id)

An expression, which may be conditional.

parse_textrecursiveprivate

recursive subroutine parse_text(c, text, path)

Split text, the contents of file path, into text and directives.

parse_unaryrecursiveprivate

recursive subroutine parse_unary(c, s, id)

A factor, perhaps negated.

push_idpureprivate

pure subroutine push_id(list, value)

Append value to list.

read_line_directivepureprivate

pure subroutine read_line_directive(text, from, content, next)

Read a line directive whose text starts at from, joining continuation lines.

read_namepureprivate

pure subroutine read_name(s)

Read a name.

read_stringprivate

subroutine read_string(c, s)

Read a string in quotes, undoing its escapes.

read_targetsprivate

subroutine read_targets(c, text, targets, next)

Read the names separated by commas at the start of text.

record_spanprivate

subroutine record_span(c, first, last)

Record that the output from after first to last was evaluated.

render_bodyrecursiveprivate

recursive subroutine render_body(c, body, out, top)

Render the nodes of body. With top, what is evaluated is recorded for line folding.

render_callrecursiveprivate

recursive subroutine render_call(c, id, out, top)

Render a call: the block is the last positional argument.

render_looprecursiveprivate

recursive subroutine render_loop(c, id, out, top)

Render a loop.

render_noderecursiveprivate

recursive subroutine render_node(c, id, out, top)

Render a node.

run_clauserecursiveprivate

recursive subroutine run_clause(c, id, k, items, n)

Run clause k of comprehension id, collecting items.

set_directiveprivate

subroutine set_directive(c, param)

#:set names = expression.

split_stringpureprivate

pure subroutine split_string(text, separator, v)

text.split(separator).

subscriptprivate

subroutine subscript(c, a, index, v)

Item index of a, counting from 0, and from the end if negative.

without_carriage_returnspureprivate

pure subroutine without_carriage_returns(text)

Turn the line ends of text into a line feed, as Python does when it reads text.

write_valuepurerecursiveprivate

pure recursive subroutine write_value(v, quoted, b)

Write v as str() does, or as repr() does if quoted.