Package 'porter'

Description

locate_castxml() finds a CastXML executable installed by the user. porter does not download or install CastXML; install it with your system package manager before calling port().

Usage

locate_castxml(path = getOption("porter.castxml"))

Arguments

Details

When path is supplied, only that executable or directory is checked. With the default NULL path, the search order is:

• Sys.which("castxml").

• Common package-manager locations that may not be on PATH, including Homebrew, Linuxbrew, Scoop, Chocolatey, and conda prefixes.

Package-manager installations are usually found by Sys.which("castxml") when their shims or binary directories are on PATH.

Value

A single named character vector. The value is the normalized path to the CastXML executable, and the name is the detected version. Returns NULL if no usable CastXML executable is found.

Examples

locate_castxml()

Description

Parse C-family header files using CastXML and gather data from the generated XML.

Usage

port(
  header,
  limit = TRUE,
  keep = FALSE,
  cflags = NULL,
  castxml = locate_castxml()
)

Arguments

Value

An dynport object.

Note

Please note that function-like macros are not converted to callable entries. They are reported by port_report() as unsupported macros. See: https://github.com/CastXML/CastXML/issues/21

Examples

header <- tempfile(fileext = ".h")
writeLines(c(
    "typedef struct Point { int x; double y; } Point;",
    "int add(int a, int b);"
), header)

port(header)

Description

Query and update dynport fields

Usage

port_fields(port)

port_has(port, fields)

port_get(port, fields)

port_set(port, ...)

Arguments

Details

port_fields() lists the fields in the object.

port_has() checks if one or multiple fields are present in the object.

port_get() returns the current values of input fields in the object. If multiple fields are given, a named list is returned. Note that port_get() errors if non-existing fields are queried.

port_set() updates one or multiple field values in the object. It accepts two forms of arguments:

• Two arguments with the first element being the name of a single field, and the second being the field value. Use NULL value to remove the field.

• Multiple named arguments with names being names of field to set, and values being the new values. Use NULL value to remove the field.

For port_set(), you can use NULL to remove values of input fields. For example, the following two lines of code both remove the value of the Version field.

port_set(p, "Version", NULL)
port_set(p, Version = NULL)

Note that, following fields are always required for a dynport object and will be kept as NULL instead of removal: Package, Version, Library, Function, FuncPtr, Enum, Struct and Union. Other fields are treated as user customize fields and will be removed when setting to NULL.'

Value

port_fields() returns a character vector.

port_has() returns a logical vector.

port_get() returns a character vector or a data.frame, depending on the field value types.

port_set() returns a new dynport object, invisibly.

Examples

header <- tempfile(fileext = ".h")
writeLines("int add(int a, int b);", header)

p <- port(header)
port_fields(p)
port_has(p, c("Package", "Function"))
port_get(p, "Function")
port_set(p, Package = "Example", Version = "1.0", Library = "example")

Description

Inspect diagnostics recorded while generating a dynport

Usage

port_report(port, kind = NULL)

Arguments

Value

A data frame with diagnostic entries, including source file and line when available.

Examples

header <- tempfile(fileext = ".h")
writeLines(c(
    "#define ADD_ONE(x) ((x) + 1)",
    "int add(int a, int b);"
), header)

p <- port(header)
port_report(p)
port_report(p, "unsupported_macro")

Description

Validate generated function symbols against an exported symbol list

Usage

port_validate_symbols(port, symbols, ...)

Arguments

Value

A data frame with symbol validation status.

Examples

header <- tempfile(fileext = ".h")
writeLines("int add(int a, int b);", header)

p <- port(header)
port_validate_symbols(p, c("add", "other_symbol"))

Description

Write dynport file

Usage

port_write(port, file, reorder = TRUE)

Arguments

Value

A single string of the file path, invisibly.

Examples

header <- tempfile(fileext = ".h")
writeLines("int add(int a, int b);", header)

p <- port(header)
p <- port_set(p, Package = "Example", Version = "1.0", Library = "example")
port_write(p, file.path(tempdir(), "Example.dynport"))

Description

Print summary of an dynport object

Usage

## S3 method for class 'dynport'
print(x, n = 5L, ...)

Arguments

Value

x invisibly.

Examples

header <- tempfile(fileext = ".h")
writeLines("int add(int a, int b);", header)

p <- port(header)
print(p)