| Name | zpp JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | None |
| Summary | a Bash Pre-Processor for Fortran.ZPP is useful in order to build clean Fortran90 interfaces.It allows to generate Fortran code for all types, kinds, and array rankssupported by the compiler. |
| upload_time | 2024-08-12 10:43:48 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
bash
fortran
pre-processor
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<!----------------------------------------------------------------------------
| SPDX-FileCopyrightText: 2014-2024 Centre national de la recherche scientifique (CNRS)
| SPDX-FileCopyrightText: 2014-2024 Commissariat a l'énergie atomique et aux énergies alternatives (CEA)
| SPDX-FileCopyrightText: 2014-2024 Julien Bigot <julien.bigot@cea.fr>
| SPDX-FileCopyrightText: 2014-2024 Université Paris-Saclay
| SPDX-FileCopyrightText: 2014-2024 Université de Versailles Saint-Quentin-en-Yvelines
|
| SPDX-License-Identifier: MIT
----------------------------------------------------------------------------->
# zpp
This is zpp, the Z Pre-Processor.
Zpp transforms bash in a pre-processor for F90 source files.
It offers a set of functions specifically tailored to build clean Fortran90
interfaces by generating code for all types, kinds, and array ranks supported by
a given compiler.
## Syntax
Zpp files are typically named `*.F90.zpp`.
In these files, the lines that start with `!$SH` are interpreted as bash lines.
Other lines are copied as-is, except that variable substitution is operated as
in a double-quoted string, including bash commands `${VAR}` or `$(command)`.
If inside a bash control block (`if`, `for`, etc.), the output generation obeys
the control statement.
For example, this code:
```
!$SH for GREETED in world universe multiverse ; do
print *, "Hello ${GREETED}"
!$SH done
```
Would produce the following result:
```
print *, "Hello world"
print *, "Hello universe"
print *, "Hello multiverse"
```
### Support functions
Predefined bash functions, variable and code can be provided in `.zpp.sh` files
that can be included with `#!SH source <filename>.zpp.sh`.
**Beware**: a file NEEDs to have the `.zpp.sh` extension to be included from
zpp.
Zpp provides a standard library of functions tailored to build clean Fortran90
interfaces by generating code for all types, kinds, and array ranks supported by
a given compiler.
#### zpp_str_repeat
Found in `base.zpp.sh`
Outputs a string multiple times.
Parameters:
1. the string to Repeat
2. the lower bound of the iterations (inclusive)
3. the upper bound of the iterations (inclusive)
4. the string separator
5. the string starter
6. the string ender
Repeats string `$1` (`$3`-`$2`+1) times, separated by string `$4` inside `$5`
`$6`.
* If the number of repetitions is negative, the result is empty.
* If `$1` contains the '@N' substring, it will be replaced by the iteration
number (from `$2` to `$3`).
example:
```
#!SH source base.zpp.sh
zpp_str_repeat v@N 5 7 '...' '<<' '>>'
zpp_str_repeat w@N 1 1 '...' '<<' '>>'
zpp_str_repeat x@N 1 0 '...' '<<' '>>'
```
output:
```
<<v5...v6...v7>>
<<w1>>
```
#### zpp_str_repeat_reverse
Found in `base.zpp.sh`
Outputs a string multiple times in reverse order.
Parameters:
1. the string to Repeat
2. the upper bound of the iterations (inclusive)
3. the lower bound of the iterations (inclusive)
4. the string separator
5. the string starter
6. the string ender
Repeats string `$1` (`$2`-`$3`+1) times, separated by string `$4` inside `$5`
`$6`.
* If the number of repetitions is negative, the result is empty.
* If `$1` contains the '@N' substring, it will be replaced by the iteration
number (from `$2` to `$3`, i.e. upper to lower).
example:
```
#!SH source base.zpp.sh
zpp_str_repeat_reverse v@N 5 7 '...' '<<' '>>'
zpp_str_repeat_reverse w@N 1 1 '...' '<<' '>>'
zpp_str_repeat_reverse x@N 1 0 '...' '<<' '>>'
```
output:
```
<<v7...v6...v5>>
<<w1>>
```
#### ZPP_FORT_TYPES
Found in `fortran.zpp.sh`
The list of types supported by the fortran compiler as zpp:typeIDs.
The compiler ID should be provided in `ZPP_CONFIG` as `config.<ID>`.
The supported predefined IDs are: `Gnu`, `Intel`, `PGI` and `XL`.
You can also provide definitions for an additional compiler by defining
`ZPP_FORT_TYPES` in a file named `config.<ID>.zpp.sh`.
If you use cmake, it will automatically generate such a file for your compiler
and define `ZPP_CONFIG` so you don't have to handle it.
### zpp_fort_array_desc
Found in `fortran.zpp.sh`
Outputs an assumed shaped array descriptor of the provided size.
Parameters:
1. the size of the assumed shaped array
example:
```
#!SH source fortran.zpp.sh
integer:: scalar$(zpp_fort_array_desc 0)
integer:: array1d$(zpp_fort_array_desc 1)
integer:: array2d$(zpp_fort_array_desc 2)
```
output:
```
integer:: scalar
integer:: array1d(:)
integer:: array2d(:,:)
```
### zpp_fort_ptype
Found in `fortran.zpp.sh`
Outputs the type associated to a zpp:typeID.
Parameters:
1. a zpp:typeID
example:
```
#!SH source fortran.zpp.sh
!$SH for T in ${ZPP_FORT_TYPES} ; do
$(zpp_fort_ptype $1)
!$SH done
```
example output:
```
CHARACTER
COMPLEX
COMPLEX
INTEGER
INTEGER
INTEGER
INTEGER
LOGICAL
REAL
REAL
```
### zpp_fort_kind
Found in `fortran.zpp.sh`
Outputs the kind associated to a zpp:typeID.
Parameters:
1. a zpp:typeID
example:
```
#!SH source fortran.zpp.sh
!$SH for T in ${ZPP_FORT_TYPES} ; do
$(zpp_fort_kind $1)
!$SH done
```
example output:
```
1
4
8
1
2
4
8
1
4
8
```
### zpp_fort_type
Found in `fortran.zpp.sh`
Outputs the full type (with kind included) associated to a zpp:typeID.
Parameters:
1. a zpp:typeID
2. additional attributes for the type
example:
```
#!SH source fortran.zpp.sh
!$SH for T in ${MY_CHAR_TYPES} ; do
$(zpp_fort_type $1)
$(zpp_fort_type $1 "len=5")
!$SH done
```
example output:
```
CHARACTER(KIND=1)
CHARACTER(KIND=1,len=5)
```
### zpp_fort_sizeof
Found in `fortran.zpp.sh`
Outputs the size in bits associated to a zpp:typeID.
Parameters:
1. a zpp:typeID
### zpp_fort_io_format
Found in `fortran.zpp.sh`
Outputs an IO descriptor suitable for a zpp:typeID.
Parameters:
1. a zpp:typeID
### ZPP_HDF5F_TYPES
Found in `hdf5_fortran.zpp.sh`
A list of zpp:typeIDs supported by HDF5.
### hdf5_constant
Found in `hdf5_fortran.zpp.sh`
Outputs the HDF5 type constant associated to a zpp:typeID.
Parameters:
1. a zpp:typeID
example:
```
#!SH source hdf5_fortran.zpp.sh
!$SH for T in ${ZPP_HDF5F_TYPES} ; do
$(hdf5_constant $1)
!$SH done
```
example output:
```
H5T_NATIVE_INTEGER
H5T_NATIVE_REAL
H5T_NATIVE_REAL
H5T_NATIVE_CHARACTER
```
## Command-line interface
Zpp basic usage is as follow:
```
Usage: zpp [Options...] <source> [<destination>]
use `zpp -h' for more info
Preprocesses BASH in-line commands in a source file
Options:
--version show program's version number and exit
-h, --help show this help message and exit
-I DIR Add DIR to search list for source directives
-o FILE Place the preprocessed code in file FILE.
-D OPTION=VALUE Set the value of OPTION to VALUE
```
## CMake interface
Support is provided for using zpp from CMake based projects, but you can use
it from plain Makefiles too.
There are two ways you can use zpp from your CMake project:
* with `add_subdirectory`: include zpp in your project and use it directly from
there,
* with `find_package`: install zpp and use it as an external dependency of your
project.
#### CMake subdirectory usage
Using zpp with `add_subdirectory` is very simple.
Just copy the `zpp` directory in your source and point to it with
`add_subdirectory(zpp)`.
The `zpp_preprocess` then becomes available to process zpp files.
This is demonstrated in `example/cmake_subdirectory`.
#### CMake find usage
Using zpp with `find_package` is no more complex.
If zpp is installed, just add a `find_package(zpp REQUIRED)`.
The `zpp_preprocess` then becomes available to process zpp files.
This is demonstrated in `example/cmake_find`.
## GMake usage
Using zpp from a GNU Makefile is slightly less powerful than from CMake.
The types and kinds supported by the Fortran compiler will not be automatically
detected.
Predefined lists of supported types for well known compilers are provided
instead.
To use zpp from a Makefile, include the `share/zpp/zpp.mk` file (either from an
installed location or from a subdirectory in your project).
You can then set the `zpp_COMPILER_ID` variable to the compiler you use and
`.F90` files will be automatically generated from their `.F90.zpp` equivalent.
The `zppFLAGS` variable is automatically passed to zpp similarly to `CFLAGS` or
`CXXFLAGS` for `cc` and `cxx`.
This is demonstrated in `example/cmake_makefile`.
## Installation
Zpp can be installed using the usual python way with `setup.py`.
```
./setup.py --help
```
The cmake approach is deprecated.
## FAQ
Q. Isn't zpp redundant with assumed type parameters?
A.
The assumed type parameters functionality allows to implement part of what can
be done with zpp (support for all kinds of a type). However as of 2013 it was
not correctly supported on most compilers installed on the supercomputers.
In addition, many things can be done with zpp but not with assumed type
parameters, such as support for variable array rank or small variations of the
code depending on the kind.
Raw data
{
"_id": null,
"home_page": null,
"name": "zpp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "bash, Fortran, pre-processor",
"author": null,
"author_email": "Julien Bigot <julien.bigot@cea.fr>",
"download_url": "https://files.pythonhosted.org/packages/a5/c3/74bb0058ed4b031a19aed84ceaf844fa10984f8fe899e2124bb64ffafd4f/zpp-1.1.0.tar.gz",
"platform": null,
"description": "<!----------------------------------------------------------------------------\n| SPDX-FileCopyrightText: 2014-2024 Centre national de la recherche scientifique (CNRS)\n| SPDX-FileCopyrightText: 2014-2024 Commissariat a l'\u00e9nergie atomique et aux \u00e9nergies alternatives (CEA)\n| SPDX-FileCopyrightText: 2014-2024 Julien Bigot <julien.bigot@cea.fr>\n| SPDX-FileCopyrightText: 2014-2024 Universit\u00e9 Paris-Saclay\n| SPDX-FileCopyrightText: 2014-2024 Universit\u00e9 de Versailles Saint-Quentin-en-Yvelines\n| \n| SPDX-License-Identifier: MIT\n----------------------------------------------------------------------------->\n\n# zpp\n\nThis is zpp, the Z Pre-Processor.\n\nZpp transforms bash in a pre-processor for F90 source files.\nIt offers a set of functions specifically tailored to build clean Fortran90\ninterfaces by generating code for all types, kinds, and array ranks supported by\na given compiler.\n\n## Syntax\n\nZpp files are typically named `*.F90.zpp`.\n\nIn these files, the lines that start with `!$SH` are interpreted as bash lines. \nOther lines are copied as-is, except that variable substitution is operated as\nin a double-quoted string, including bash commands `${VAR}` or `$(command)`.\nIf inside a bash control block (`if`, `for`, etc.), the output generation obeys\nthe control statement.\n\nFor example, this code:\n```\n!$SH for GREETED in world universe multiverse ; do\nprint *, \"Hello ${GREETED}\"\n!$SH done\n```\n\nWould produce the following result:\n```\nprint *, \"Hello world\"\nprint *, \"Hello universe\"\nprint *, \"Hello multiverse\"\n```\n\n### Support functions\n\nPredefined bash functions, variable and code can be provided in `.zpp.sh` files\nthat can be included with `#!SH source <filename>.zpp.sh`.\n\n**Beware**: a file NEEDs to have the `.zpp.sh` extension to be included from\nzpp.\n\nZpp provides a standard library of functions tailored to build clean Fortran90\ninterfaces by generating code for all types, kinds, and array ranks supported by\na given compiler.\n\n#### zpp_str_repeat\n\nFound in `base.zpp.sh`\n\nOutputs a string multiple times.\n\nParameters:\n1. the string to Repeat\n2. the lower bound of the iterations (inclusive)\n3. the upper bound of the iterations (inclusive)\n4. the string separator\n5. the string starter\n6. the string ender\n\nRepeats string `$1` (`$3`-`$2`+1) times, separated by string `$4` inside `$5`\n`$6`.\n* If the number of repetitions is negative, the result is empty.\n* If `$1` contains the '@N' substring, it will be replaced by the iteration\n number (from `$2` to `$3`).\n\nexample:\n```\n#!SH source base.zpp.sh\nzpp_str_repeat v@N 5 7 '...' '<<' '>>'\nzpp_str_repeat w@N 1 1 '...' '<<' '>>'\nzpp_str_repeat x@N 1 0 '...' '<<' '>>'\n```\noutput:\n```\n<<v5...v6...v7>>\n<<w1>>\n```\n\n#### zpp_str_repeat_reverse\n\nFound in `base.zpp.sh`\n\nOutputs a string multiple times in reverse order.\n\nParameters:\n1. the string to Repeat\n2. the upper bound of the iterations (inclusive)\n3. the lower bound of the iterations (inclusive)\n4. the string separator\n5. the string starter\n6. the string ender\n\nRepeats string `$1` (`$2`-`$3`+1) times, separated by string `$4` inside `$5`\n`$6`.\n* If the number of repetitions is negative, the result is empty.\n* If `$1` contains the '@N' substring, it will be replaced by the iteration\n number (from `$2` to `$3`, i.e. upper to lower).\n\nexample:\n```\n#!SH source base.zpp.sh\nzpp_str_repeat_reverse v@N 5 7 '...' '<<' '>>'\nzpp_str_repeat_reverse w@N 1 1 '...' '<<' '>>'\nzpp_str_repeat_reverse x@N 1 0 '...' '<<' '>>'\n```\noutput:\n```\n<<v7...v6...v5>>\n<<w1>>\n```\n\n#### ZPP_FORT_TYPES\n\nFound in `fortran.zpp.sh`\n\nThe list of types supported by the fortran compiler as zpp:typeIDs.\n\nThe compiler ID should be provided in `ZPP_CONFIG` as `config.<ID>`.\nThe supported predefined IDs are: `Gnu`, `Intel`, `PGI` and `XL`.\nYou can also provide definitions for an additional compiler by defining\n`ZPP_FORT_TYPES` in a file named `config.<ID>.zpp.sh`.\n\nIf you use cmake, it will automatically generate such a file for your compiler\nand define `ZPP_CONFIG` so you don't have to handle it.\n\n### zpp_fort_array_desc\n\nFound in `fortran.zpp.sh`\n\nOutputs an assumed shaped array descriptor of the provided size.\n\nParameters:\n1. the size of the assumed shaped array\n\nexample:\n```\n#!SH source fortran.zpp.sh\ninteger:: scalar$(zpp_fort_array_desc 0)\ninteger:: array1d$(zpp_fort_array_desc 1)\ninteger:: array2d$(zpp_fort_array_desc 2)\n```\noutput:\n```\ninteger:: scalar\ninteger:: array1d(:)\ninteger:: array2d(:,:)\n```\n\n### zpp_fort_ptype\n\nFound in `fortran.zpp.sh`\n\nOutputs the type associated to a zpp:typeID.\n\nParameters:\n1. a zpp:typeID\n\nexample:\n```\n#!SH source fortran.zpp.sh\n!$SH for T in ${ZPP_FORT_TYPES} ; do\n$(zpp_fort_ptype $1)\n!$SH done\n```\nexample output:\n```\nCHARACTER\nCOMPLEX\nCOMPLEX\nINTEGER\nINTEGER\nINTEGER\nINTEGER\nLOGICAL\nREAL\nREAL\n```\n\n### zpp_fort_kind\n\nFound in `fortran.zpp.sh`\n\nOutputs the kind associated to a zpp:typeID.\n\nParameters:\n1. a zpp:typeID\n\nexample:\n```\n#!SH source fortran.zpp.sh\n!$SH for T in ${ZPP_FORT_TYPES} ; do\n$(zpp_fort_kind $1)\n!$SH done\n```\nexample output:\n```\n1\n4\n8\n1\n2\n4\n8\n1\n4\n8\n```\n\n### zpp_fort_type\n\nFound in `fortran.zpp.sh`\n\nOutputs the full type (with kind included) associated to a zpp:typeID.\n\nParameters:\n1. a zpp:typeID\n2. additional attributes for the type\n\nexample:\n```\n#!SH source fortran.zpp.sh\n!$SH for T in ${MY_CHAR_TYPES} ; do\n$(zpp_fort_type $1)\n$(zpp_fort_type $1 \"len=5\")\n!$SH done\n```\nexample output:\n```\nCHARACTER(KIND=1)\nCHARACTER(KIND=1,len=5)\n```\n\n### zpp_fort_sizeof\n\nFound in `fortran.zpp.sh`\n\nOutputs the size in bits associated to a zpp:typeID.\n\nParameters:\n1. a zpp:typeID\n\n### zpp_fort_io_format\n\nFound in `fortran.zpp.sh`\n\nOutputs an IO descriptor suitable for a zpp:typeID.\n\nParameters:\n1. a zpp:typeID\n\n### ZPP_HDF5F_TYPES\n\nFound in `hdf5_fortran.zpp.sh`\n\nA list of zpp:typeIDs supported by HDF5.\n\n### hdf5_constant\n\nFound in `hdf5_fortran.zpp.sh`\n\nOutputs the HDF5 type constant associated to a zpp:typeID.\n\nParameters:\n1. a zpp:typeID\n\nexample:\n```\n#!SH source hdf5_fortran.zpp.sh\n!$SH for T in ${ZPP_HDF5F_TYPES} ; do\n$(hdf5_constant $1)\n!$SH done\n```\nexample output:\n```\nH5T_NATIVE_INTEGER\nH5T_NATIVE_REAL\nH5T_NATIVE_REAL\nH5T_NATIVE_CHARACTER\n```\n\n\n## Command-line interface\n\nZpp basic usage is as follow:\n```\nUsage: zpp [Options...] <source> [<destination>]\n use `zpp -h' for more info\n\nPreprocesses BASH in-line commands in a source file\n\nOptions:\n --version show program's version number and exit\n -h, --help show this help message and exit\n -I DIR Add DIR to search list for source directives\n -o FILE Place the preprocessed code in file FILE.\n -D OPTION=VALUE Set the value of OPTION to VALUE\n```\n\n## CMake interface\n\nSupport is provided for using zpp from CMake based projects, but you can use\nit from plain Makefiles too.\n\nThere are two ways you can use zpp from your CMake project:\n* with `add_subdirectory`: include zpp in your project and use it directly from\n there,\n* with `find_package`: install zpp and use it as an external dependency of your\n project.\n\n#### CMake subdirectory usage\n\nUsing zpp with `add_subdirectory` is very simple.\nJust copy the `zpp` directory in your source and point to it with\n`add_subdirectory(zpp)`.\nThe `zpp_preprocess` then becomes available to process zpp files.\n\nThis is demonstrated in `example/cmake_subdirectory`.\n\n#### CMake find usage\n\nUsing zpp with `find_package` is no more complex.\nIf zpp is installed, just add a `find_package(zpp REQUIRED)`.\nThe `zpp_preprocess` then becomes available to process zpp files.\n\nThis is demonstrated in `example/cmake_find`.\n\n## GMake usage\n\nUsing zpp from a GNU Makefile is slightly less powerful than from CMake.\nThe types and kinds supported by the Fortran compiler will not be automatically\ndetected.\nPredefined lists of supported types for well known compilers are provided\ninstead.\n\nTo use zpp from a Makefile, include the `share/zpp/zpp.mk` file (either from an\ninstalled location or from a subdirectory in your project).\nYou can then set the `zpp_COMPILER_ID` variable to the compiler you use and\n`.F90` files will be automatically generated from their `.F90.zpp` equivalent.\nThe `zppFLAGS` variable is automatically passed to zpp similarly to `CFLAGS` or\n`CXXFLAGS` for `cc` and `cxx`.\n\nThis is demonstrated in `example/cmake_makefile`.\n\n## Installation\n\nZpp can be installed using the usual python way with `setup.py`.\n```\n./setup.py --help\n```\n\nThe cmake approach is deprecated.\n\n## FAQ\n\nQ. Isn't zpp redundant with assumed type parameters?\n\nA.\nThe assumed type parameters functionality allows to implement part of what can\nbe done with zpp (support for all kinds of a type). However as of 2013 it was\nnot correctly supported on most compilers installed on the supercomputers.\n\nIn addition, many things can be done with zpp but not with assumed type\nparameters, such as support for variable array rank or small variations of the\ncode depending on the kind.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "a Bash Pre-Processor for Fortran.ZPP is useful in order to build clean Fortran90 interfaces.It allows to generate Fortran code for all types, kinds, and array rankssupported by the compiler.",
"version": "1.1.0",
"project_urls": null,
"split_keywords": [
"bash",
" fortran",
" pre-processor"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5b2b8f526a84e20d9e1439a7fac0154efdd5c4636659916ac0afa9434f6b0cd9",
"md5": "d91313586f11242db86825ecd7878e3f",
"sha256": "bcb1d4c65d1a1706eebcc6fc58f16498ceb5511bcb03c050bbf648dcdada58c9"
},
"downloads": -1,
"filename": "zpp-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d91313586f11242db86825ecd7878e3f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 19365,
"upload_time": "2024-08-12T10:43:46",
"upload_time_iso_8601": "2024-08-12T10:43:46.579385Z",
"url": "https://files.pythonhosted.org/packages/5b/2b/8f526a84e20d9e1439a7fac0154efdd5c4636659916ac0afa9434f6b0cd9/zpp-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a5c374bb0058ed4b031a19aed84ceaf844fa10984f8fe899e2124bb64ffafd4f",
"md5": "203afd4f597d9b58941aed2800221986",
"sha256": "4cd07ef18df5d44798e213aaaf17af78449739b01c0bf41e046c95b8a1aad6bd"
},
"downloads": -1,
"filename": "zpp-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "203afd4f597d9b58941aed2800221986",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 16155,
"upload_time": "2024-08-12T10:43:48",
"upload_time_iso_8601": "2024-08-12T10:43:48.365248Z",
"url": "https://files.pythonhosted.org/packages/a5/c3/74bb0058ed4b031a19aed84ceaf844fa10984f8fe899e2124bb64ffafd4f/zpp-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-12 10:43:48",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "zpp"
}
