diff --git a/src/development-guide/README.md b/src/development-guide/README.md index 66d8c0928..e38637d3c 100644 --- a/src/development-guide/README.md +++ b/src/development-guide/README.md @@ -22,7 +22,7 @@ Development related information - [Overview](serializers/overview.md) - [Serializer Class](serializers/serializers.md) - [New Serializers](serializers/task-list.md) -- [File Formats](serializers/file-formats.md) +- [File Naming and Formats](serializers/file-formats.md) ### Testing diff --git a/src/development-guide/serializers/README.md b/src/development-guide/serializers/README.md index af4ee9308..2c0198a44 100644 --- a/src/development-guide/serializers/README.md +++ b/src/development-guide/serializers/README.md @@ -12,4 +12,4 @@ dir: - [Overview](overview.md) - [Serializer Class](serializers.md) - [New Serializers](task-list.md) -- [File Formats](file-formats.md) +- [File Naming and Formats](file-formats.md) diff --git a/src/development-guide/serializers/file-formats.md b/src/development-guide/serializers/file-formats.md index 50d4db63a..28273ebc3 100755 --- a/src/development-guide/serializers/file-formats.md +++ b/src/development-guide/serializers/file-formats.md @@ -1,14 +1,38 @@ --- -title: File Formats +title: File Naming and Formats category: serializers order: 40 --- -All files for an object are located in the same folder, each folder corresponds to a package. Sub-packages are organized under parent packages(directories) according to the logic described in the [Repository Settings](/user-guide/repo-settings/dot-abapgit.md) +All files for an object are located in the same folder, each folder corresponds to a package. Sub-packages are organized under parent packages (directories) according to the logic described in the [Repository Settings](/user-guide/repo-settings/dot-abapgit.md). -## CLAS +## Naming -Files corresponding to the editable parts in source-based class builder or ABAP in Eclipse: +In general, the names of files containing the object definitions are derived from the TADIR entry i.e. object type and object name. Filenames are lower case and adhere to the following patterns: + +- `..`: Object metadata. Supported extensions: `xml` or `json` +- `...`: Additional object data. Typical extensions: `abap`, `html`, `js`, etc. +- `..i18n..`: Language-specific translation files: Supported extensions: `po` or `properties` + +## Codepage, EOL, EOF, Indentation + +Metadata, ABAP coding, and translation files are stored in `UFT-8` with leading [Byte-order-mark (xEF BB BF)](https://en.wikipedia.org/wiki/Byte_order_mark), linefeed (x0A) as end-of-line character and a final newline character. Indentation is set to 2 and uses spaces, not tabs. See [.editorconfig](https://github.com/abapGit/abapGit/blob/main/.editorconfig) for details. + +## Formats + +### Classic abapGit Format + +Each object is represented by at least one XML file, which contains the object metadata. Depending on the object type, other files may be added like a file with `abap` extension for source code. + +The XML file contains a root `` tag which specifies the [serializer class](overview.html) and version used by abapGit to convert the object to files and vice versa (see example below). + +Translations are either included in the XML file or stored in a separate `i18n..po` file. + +#### Example + +Here's an example for an ABAP OO Class, object type `CLAS` (See also [test repo](https://github.com/abapGit-tests/CLAS_full)). + +The following files correspond to the editable parts in source-based class builder or ABAP in Eclipse: * `zcl_example.clas.abap` * `zcl_example.clas.locals_def.abap` @@ -16,14 +40,52 @@ Files corresponding to the editable parts in source-based class builder or ABAP * `zcl_example.clas.testclasses.abap` * `zcl_example.clas.macros.abap` -Files do not exist if empty, ie. the developer did not choose to implement it +Files do not exist if empty, i.e. the developer did not choose to implement them. One XML file `zcl_example.clas.xml` containing: +```xml +* + + + + + ZCL_ABAPGIT_FACTORY + E + abapGit - Factory + 1 + X + X + X + + + + + +*: +``` + +Example XML data: + * VSEOCLASS information * TPOOL information * SOTR information * LINES from DOKU * Descriptions from SEOCOMPOTX -See example [https://github.com/abapGit-tests/CLAS_full](https://github.com/abapGit-tests/CLAS_full) +### SAP ABAP File Format + +Newer object types are represented by a JSON file and follow the [ABAP File Format (AFF)](https://github.com/SAP/abap-file-formats). + +Object types supporting AFF are registered [here](https://github.com/abapGit/abapGit/blob/main/src/objects/aff/zcl_abapgit_aff_registry.clas.abap#L48). + +Translations are stored in separate `i18n..properties` files (see [AFF properties file](https://github.com/SAP/abap-file-formats/blob/main/docs/properties.md)). + +## Source Code Reference + +[zcl_abapgit_filename_logic](https://github.com/abapGit/abapGit/blob/main/src/objects/core/zcl_abapgit_filename_logic.clas.abap) +- `file_to_object`: Get object from filename and path +- `object_to_file`: Get filename from object +- `detect_object_definition`: Return flags to detect if filename represents an object definition i.e. has an `xml` or `json` extension +- `is_obj_definition_file`: Return boolean flag, if the filename represents an object definition or not (metadata) +