|
Reckon 0.5.1-dev
A Tool to Count Logical Lines of Code
|
The primary API of the Reckon library. More...
#include <stddef.h>#include <stdbool.h>#include <stdint.h>#include "reckon_export.h"Go to the source code of this file.
Data Structures | |
| struct | RcnResultState |
| The result status type of an operation indicating success or failure. More... | |
| struct | RcnCountResult |
| The result type for a single code analysis operation. More... | |
| struct | RcnCountResultGroup |
| Result type for a group of analysis operations on a single source entity. More... | |
| struct | RcnSourceText |
| A block of source text. More... | |
| struct | RcnSourceFile |
| A structure representing a text source file. More... | |
| struct | RcnCountResultSet |
| The count results for a set of source files. More... | |
| struct | RcnCountStatistics |
| A collection of source code metrics. More... | |
| struct | RcnStatOptions |
| Options to customize the behaviour of counting operations. More... | |
Macros | |
| #define | RECKON_NUM_SUPPORTED_FORMATS 3 |
| The total number of supported text formats, including supported programming languages. | |
| #define | RECKON_MK_FRMT_OPT(frmt) |
| Macro to create a format option bitmask. | |
| #define | RECKON_ENV_VAR_DEBUG "RECKON_DEBUG" |
| The name of the environment variable to control debug logging. | |
Typedefs | |
| typedef enum RcnTextFormat | RcnTextFormat |
| Enumeration of supported text formats and programming languages. | |
| typedef enum RcnErrorCode | RcnErrorCode |
| Enumeration of error states. | |
| typedef struct RcnResultState | RcnResultState |
| The result status type of an operation indicating success or failure. | |
| typedef uint64_t | RcnCount |
| A count number of some metric within source text. | |
| typedef struct RcnCountResult | RcnCountResult |
| The result type for a single code analysis operation. | |
| typedef struct RcnCountResultGroup | RcnCountResultGroup |
| Result type for a group of analysis operations on a single source entity. | |
| typedef struct RcnSourceText | RcnSourceText |
| A block of source text. | |
| typedef enum RcnFileOpStatus | RcnFileOpStatus |
| Enumeration of file processing operation status codes. | |
| typedef struct RcnSourceFile | RcnSourceFile |
| A structure representing a text source file. | |
| typedef struct RcnCountResultSet | RcnCountResultSet |
| The count results for a set of source files. | |
| typedef struct RcnCountStatistics | RcnCountStatistics |
| A collection of source code metrics. | |
| typedef enum RcnCountOption | RcnCountOption |
| Options to specify which counting operations to perform. | |
| typedef enum RcnFormatOption | RcnFormatOption |
| Options for format-specific analysis behaviours. | |
| typedef struct RcnStatOptions | RcnStatOptions |
| Options to customize the behaviour of counting operations. | |
Functions | |
| RcnCountStatistics * | rcnCreateCountStatistics (const char *path) |
| Creates a new RcnCountStatistics struct for the specified file path. | |
| void | rcnFreeCountStatistics (RcnCountStatistics *stats) |
| Frees a previously allocated RcnCountStatistics struct. | |
| void | rcnCount (RcnCountStatistics *stats, RcnStatOptions options) |
| Performs counting operations using the specified statistics options. | |
| RcnCountResult | rcnCountLogicalLines (RcnTextFormat language, RcnSourceText sourceCode) |
| Counts the number of logical lines of code in the specified source text. | |
| RcnSourceText | rcnMarkLogicalLinesInFile (const char *path) |
| Marks the counted logical lines in the source code of the specified file. | |
| RcnSourceText | rcnMarkLogicalLinesInSourceText (RcnTextFormat language, RcnSourceText sourceCode) |
| Marks the counted logical lines in the specified source code text. | |
| void | rcnFreeSourceText (RcnSourceText *source) |
| Frees the previously allocated data of a RcnSourceText struct. | |
| RcnCountResult | rcnCountPhysicalLines (RcnSourceText source) |
| Counts the number of hard physical lines in the specified source text. | |
| RcnCountResult | rcnCountWords (RcnSourceText source) |
| Counts the number of words in the specified source text. | |
| RcnCountResult | rcnCountCharacters (RcnSourceText source) |
| Counts the number of characters in the specified source text. | |
The primary API of the Reckon library.
Exposes types and function declarations for source code metrics. Provides functionality to count the occurrences of various source code related concepts such as number of words, physical lines and logical lines of code, and other related metrics. The library supports multiple programming languages and file formats. Supported formats are enumerated by the RcnTextFormat enum.
The Reckon library only supports processing text that is encoded in UTF-8 or UTF-16. In the case of UTF-16, a BOM must be present at the start of the text to indicate endianness. For any operation provided by the library, if the input text has encoding errors, the operation finishes gracefully but the computed result is undefined.
The typical usage is to create a RcnCountStatistics struct for either a single file or directory path using the rcnCreateCountStatistics() function. Choose the desired counting operations, formats and other options using a RcnStatOptions struct. Then pass both the created statistics and options to the rcnCount() function to perform the counting. Finally, after having evaluated the computed statistics, free the allocated statistics using the rcnFreeCountStatistics() function.
What follows are definitions of metrics that are computed by this library.
Please note that the above definitions themselves are not strictly formal and not part of the API contract. Both the definitions as well as the library implementation may evolve in future releases, such that different versions of the Reckon library may compute slightly different results for a particular metric and input combination. For more information, please refer to the official Reckon documentation.
The functions in this library are not MT-safe.
| #define RECKON_ENV_VAR_DEBUG "RECKON_DEBUG" |
The name of the environment variable to control debug logging.
If the environment has a variable with this name set to "1", then debug logging is enabled and for certain operations additional information is printed on stdout. A variable value of "0" disables all debug logging. If the environment variable is not set, debug logging is disabled by default. The definition of the environment variable only has an effect if the library is compiled as a debug build.
| #define RECKON_MK_FRMT_OPT | ( | frmt | ) |
Macro to create a format option bitmask.
Users should prefer to use the RcnFormatOption enumeration, instead of using this macro directly.
| frmt | The RcnTextFormat enumerator value. |
| #define RECKON_NUM_SUPPORTED_FORMATS 3 |
The total number of supported text formats, including supported programming languages.
| typedef uint64_t RcnCount |
A count number of some metric within source text.
This type is used to represent, for example, the count of lines within source text. Shall be treated as a non-negative integer number of arbitrary bit width. In the unlikely event of an overflow, count values wrap around according to standard unsigned integer arithmetic.
| typedef enum RcnCountOption RcnCountOption |
Options to specify which counting operations to perform.
Users can combine multiple options using a bitwise OR operation. Do not rely on concrete numeric enumerator values.
| typedef struct RcnCountResult RcnCountResult |
The result type for a single code analysis operation.
Represents the end result of one concrete type of count operation. For example, it will only contain the count of logical lines of code, or only the count of physical lines, depending on the operation performed.
| typedef struct RcnCountResultGroup RcnCountResultGroup |
Result type for a group of analysis operations on a single source entity.
Represents the end results of possibly multiple count operations performed on a single named source entity, like a specific source file. This is used to group multiple different count metrics together into a single type.
| typedef struct RcnCountResultSet RcnCountResultSet |
The count results for a set of source files.
Contains a list of source files that are subject to analysis, along with their corresponding count results. Each file in the files list has a corresponding result in the results list at the same index. No checks are performed regarding duplicate files in the list, as a result, uniqueness is not guaranteed.
| typedef struct RcnCountStatistics RcnCountStatistics |
A collection of source code metrics.
This type is used to track and store the results for code analysis operations. It contains statistics about a set of source code files, where conceptually every text file that would be part of a source tree is considered a source code file, even if it doesn't contain actual code.
| typedef enum RcnErrorCode RcnErrorCode |
Enumeration of error states.
All count operations return a RcnResultState struct that contains information about the operation's success or failure, and in latter case, the error code indicates the type of error that has occurred.
| typedef enum RcnFileOpStatus RcnFileOpStatus |
Enumeration of file processing operation status codes.
RcnSourceFile structs carry this status to indicate the processing state of the file, allowing to differentiate between various error conditions. It is guaranteed that the status code indicating success (i.e. no error) evaluates to zero, whereas all codes indicating a detected error evaluate to non-zero values.
| typedef enum RcnFormatOption RcnFormatOption |
Options for format-specific analysis behaviours.
Users can use these options to enable or disable specific formats when processing source files. Multiple options can be combined using a bitwise OR operation. Do not rely on concrete numeric enumerator values.
| typedef struct RcnResultState RcnResultState |
The result status type of an operation indicating success or failure.
Count operations return result types that contain this type of state. For a single operation, e.g. rcnCountLogicalLines(), an ok value of true indicates that the operation was fully successful, implying that errorCode is set to RCN_ERR_NONE and errorMessage is NULL. Therefore, if ok is false, then errorCode indicates the type of error that has occurred and errorMessage may or may not be set to provide additional information. For compound operations, e.g. rcnCount(), an ok value of true indicates that the operation was at least partially successful and parts of the computed compound result are usable. In such a case, errorCode may still indicate one of the encountered errors, usually the last encountered one, and errorMessage may or may not provide more information. This implies that for compound operations an ok value of true might only indicate that no critical error has occurred.
| typedef struct RcnSourceFile RcnSourceFile |
A structure representing a text source file.
Holds metadata and content of a source file to be analyzed. A source file may or may not contain source code written in a programming language. It may as well be regular text, formatted or unformatted. Users typically don't need to create, manipulate or manage the memory of this struct directly, as it is managed internally by the Reckon library to represent and track files.
The file content may or may not be loaded at any given time. Check the isContentRead field to determine if the content was read from the file system. The content.size of a not yet read file is defined to be zero. Thus, empty files that were read will have isContentRead equal to true, content.size of zero and an empty string in content.text.
| typedef struct RcnSourceText RcnSourceText |
A block of source text.
Holds a pointer to the text content and its size in bytes. The source text may or may not be null-terminated. A different type that is composed of this type may further define this explicitly. The text field may contain the bytes of text encoded in any of the supported encodings.
| typedef struct RcnStatOptions RcnStatOptions |
Options to customize the behaviour of counting operations.
Allows users to specify various options that control how counting operations are performed.
A zero-initialized RcnStatOptions struct will select default behaviour.
| typedef enum RcnTextFormat RcnTextFormat |
Enumeration of supported text formats and programming languages.
Users should not rely on the numeric enumerator value as it may change when support for new formats or programming languages is added in the future and the enumerators are reordered.
| enum RcnCountOption |
Options to specify which counting operations to perform.
Users can combine multiple options using a bitwise OR operation. Do not rely on concrete numeric enumerator values.
| enum RcnErrorCode |
Enumeration of error states.
All count operations return a RcnResultState struct that contains information about the operation's success or failure, and in latter case, the error code indicates the type of error that has occurred.
| enum RcnFileOpStatus |
Enumeration of file processing operation status codes.
RcnSourceFile structs carry this status to indicate the processing state of the file, allowing to differentiate between various error conditions. It is guaranteed that the status code indicating success (i.e. no error) evaluates to zero, whereas all codes indicating a detected error evaluate to non-zero values.
| enum RcnFormatOption |
Options for format-specific analysis behaviours.
Users can use these options to enable or disable specific formats when processing source files. Multiple options can be combined using a bitwise OR operation. Do not rely on concrete numeric enumerator values.
| enum RcnTextFormat |
Enumeration of supported text formats and programming languages.
Users should not rely on the numeric enumerator value as it may change when support for new formats or programming languages is added in the future and the enumerators are reordered.
| void rcnCount | ( | RcnCountStatistics * | stats, |
| RcnStatOptions | options ) |
Performs counting operations using the specified statistics options.
Processes the source files of the specified statistics and performs analysis operations, e.g. counting the number of logical lines of code, according to the given options. The files inside the given statistics must exist and be readable regular text files.
This function is not idempotent with respect to the same stats struct. Calling it multiple times on the same RcnCountStatistics struct is undefined behaviour.
| stats | The statistics to evaluate. |
| options | Options to customize the analysis behaviour. |
| RcnCountResult rcnCountCharacters | ( | RcnSourceText | source | ) |
Counts the number of characters in the specified source text.
A character is defined as a Unicode code point. This metric includes control characters, like newlines. The returned count therefore includes non-printable characters. See header documentation for details on supported encodings.
| source | The source text to count characters in. |
| RcnCountResult rcnCountLogicalLines | ( | RcnTextFormat | language, |
| RcnSourceText | sourceCode ) |
Counts the number of logical lines of code in the specified source text.
See header documentation for details on how logical lines of code are defined and for supported encodings.
| language | The format of the specified source text. Must denote a supported programming language. |
| sourceCode | The source code text to count logical lines in. |
| RcnCountResult rcnCountPhysicalLines | ( | RcnSourceText | source | ) |
Counts the number of hard physical lines in the specified source text.
The count includes all physical lines, including blank lines and comments, not only physical lines of code. The result of this function is therefore independent of any programming language. A physical line count can be computed for every text file, independent of its format.
See header documentation for details on how hard physical lines are defined and for supported encodings.
| source | The source text to count physical lines in. |
| RcnCountResult rcnCountWords | ( | RcnSourceText | source | ) |
Counts the number of words in the specified source text.
A word is a non-zero-length sequence of printable characters delimited by white space. See header documentation for details on supported encodings.
| source | The source text to count words in. |
| RcnCountStatistics * rcnCreateCountStatistics | ( | const char * | path | ) |
Creates a new RcnCountStatistics struct for the specified file path.
The specified file path can denote either a single regular file or a directory containing multiple files and subdirectories. In the case of a directory, all regular files within the directory and subdirectories therein will be part of the RcnCountResultSet of the returned statistics. A relative file path will be interpreted as relative to the underlying current working directory.
A user takes ownership of the returned struct and must free it with rcnFreeCountStatistics().
| path | A path in the file system. Is interpreted as a byte sequence in the underlying platform's native encoding. |
| void rcnFreeCountStatistics | ( | RcnCountStatistics * | stats | ) |
Frees a previously allocated RcnCountStatistics struct.
Must have been previously allocated using rcnCreateCountStatistics().
| stats | The RcnCountStatistics struct to free. May be NULL. |
| void rcnFreeSourceText | ( | RcnSourceText * | source | ) |
Frees the previously allocated data of a RcnSourceText struct.
Use this deallocation function for RcnSourceText structs that were returned by functions of this API that allocate new source text. The struct must not be used after calling this function.
| source | The RcnSourceText struct to free. The provided struct and the text field may be NULL. |
| RcnSourceText rcnMarkLogicalLinesInFile | ( | const char * | path | ) |
Marks the counted logical lines in the source code of the specified file.
Reads the file located at the specified file system path and adds source code comments to lines that are counted as logical lines of code. The comments are according to the syntax of the underlying used programming language and indicate the count number plus the type of syntactic construct that contributes to the logical line count. One physical line of code can contain an annotation for multiple logical lines. This function can only be used for files that contain text formatted in a supported programming language.
See header documentation for details on how logical lines of code are defined. The text in the file must be encoded with UTF-8. Other encodings are not supported by this function and result in undefined behaviour.
| path | The file system path of the source code file to annotate. Is interpreted as a byte sequence in the underlying platform's native encoding. Relative paths are interpreted relative to the current working directory. |
| RcnSourceText rcnMarkLogicalLinesInSourceText | ( | RcnTextFormat | language, |
| RcnSourceText | sourceCode ) |
Marks the counted logical lines in the specified source code text.
Creates a copy of the specified source code text and adds source code comments to lines that are counted as logical lines of code. The comments are according to the syntax of the used programming language and indicate the count number plus the type of syntactic construct that contributes to the logical line count. One physical line of code can contain an annotation for multiple logical lines. This function can only be used with RcnTextFormat enumerators that represent a supported programming language.
See header documentation for details on how logical lines of code are defined. The specified source code text must be encoded with UTF-8. Other encodings are not supported by this function and result in undefined behaviour.
| language | The format of the specified source code. Must denote a supported programming language. |
| sourceCode | The source code text to annotate. |