blob: bddb300e382112bdc7b5f2214f2da5cacd67015f [file] [log] [blame]
Radek Krejcif0e1ba52020-05-22 15:14:35 +02001/**
2 * @file parser_schema.h
3 * @author Radek Krejci <rkrejci@cesnet.cz>
4 * @brief Schema parsers for libyang
5 *
6 * Copyright (c) 2015-2020 CESNET, z.s.p.o.
7 *
8 * This source code is licensed under BSD 3-Clause License (the "License").
9 * You may not use this file except in compliance with the License.
10 * You may obtain a copy of the License at
11 *
12 * https://opensource.org/licenses/BSD-3-Clause
13 */
14
15#ifndef LY_PARSER_SCHEMA_H_
16#define LY_PARSER_SCHEMA_H_
17
18#ifdef __cplusplus
19extern "C" {
20#endif
21
22struct ly_in;
Michal Vasko3a41dff2020-07-15 14:30:28 +020023struct lys_module;
Radek Krejcif0e1ba52020-05-22 15:14:35 +020024
25/**
Radek Krejci8678fa42020-08-18 16:07:28 +020026 * @page howtoSchemaParsers Parsing YANG Modules
27 *
28 * YANG module parsers allow to read YANG module from a specific format. libyang supports the following module formats:
29 *
30 * - YANG
31 *
32 * Basic YANG schemas format described in [RFC 6020](http://tools.ietf.org/html/rfc6020) and
33 * [RFC 7951](http://tools.ietf.org/html/rfc7951) (so both YANG 1.0 and YANG 1.1 versions are supported).
34 *
35 * - YIN
36 *
37 * Alternative XML-based format to YANG - YANG Independent Notation. The details can be found in
38 * [RFC 6020](http://tools.ietf.org/html/rfc6020#section-11) and
39 * [RFC 7951](http://tools.ietf.org/html/rfc7951#section-13).
40 *
41 * When the [context](@ref howtoContext) is created, it already contains the following YANG modules, which
42 * are implemented internally by libyang:
43 * - ietf-yang-metadata@2016-08-05
44 * - yang@2020-06-17
45 * - ietf-inet-types@2013-07-15
46 * - ietf-yang-types@2013-07-15
47 * - ietf-datastores@2018-02-14
48 * - ietf-yang-library@2019-01-04
49 *
50 * The `yang` module is the libyang's internal module to provide namespace and definitions of for various YANG
51 * attributes described in [RFC 7951](https://tools.ietf.org/html/rfc6243) (such as `insert` attribute for
52 * edit-config's data).
53 *
54 * Other modules can be added to the context manually with the functions listed below. Besides them,
55 * it is also possible to use ::ly_ctx_load_module() which tries to find the required module automatically - using
56 * ::ly_module_imp_clb or automatic search in working directory and in the context's search directories. For details, see
57 * [how the context works](@ref howtoContext).
58 *
59 * YANG modules are loaded in two steps. First, the input YANG/YIN data are parsed into \b lysp_* structures that reflect
60 * the structure of the input module and submodule(s). Mostly just syntax checks are done, no reference or type checking is
61 * performed in this step. If the module is supposed to be implemented, not just imported by another module, the second step
62 * is to compile it. The compiled tree may significantly differ from the source (parsed) tree structure. All the references
63 * are resolved, groupings are instantiated, types are resolved (and compiled by joining all the relevant restrictions
64 * when derived from another types) and many other syntactical checks are done.
65 *
aPiecekb0445f22021-06-24 11:34:07 +020066 * There is the main parsing function ::lys_parse() working with the libyang [input handler](@ref howtoInput). However,
67 * to simplify some of the use-cases, it is also possible to use other functions accepting input data from various sources.
Radek Krejci8678fa42020-08-18 16:07:28 +020068 *
69 * Functions List
70 * --------------
71 * - ::lys_parse()
72 * - ::lys_parse_mem()
73 * - ::lys_parse_fd()
74 * - ::lys_parse_path()
75 *
76 * - ::lys_search_localfile()
77 * - ::ly_ctx_set_module_imp_clb()
78 * - ::ly_ctx_load_module()
79 */
80
81/**
Radek Krejcif0e1ba52020-05-22 15:14:35 +020082 * @addtogroup schematree
83 * @{
84 */
85
86/**
Radek Krejci8678fa42020-08-18 16:07:28 +020087 * @brief Schema input formats accepted by libyang [parser functions](@ref howtoSchemaParsers).
Radek Krejcif0e1ba52020-05-22 15:14:35 +020088 */
89typedef enum {
90 LYS_IN_UNKNOWN = 0, /**< unknown format, used as return value in case of error */
91 LYS_IN_YANG = 1, /**< YANG schema input format */
92 LYS_IN_YIN = 3 /**< YIN schema input format */
93} LYS_INFORMAT;
94
95/**
96 * @brief Load a schema into the specified context.
97 *
98 * @param[in] ctx libyang context where to process the data model.
99 * @param[in] in The input handle to provide the dumped data model in the specified format.
Radek Krejci545b4872020-11-15 10:15:12 +0100100 * @param[in] format Format of the schema to parse. Can be 0 to try to detect format from the input handler.
Michal Vasko7b1ad1a2020-11-02 15:41:27 +0100101 * @param[in] features Array of features to enable ended with NULL. If NULL, no features are enabled.
Michal Vasko3a41dff2020-07-15 14:30:28 +0200102 * @param[out] module Optional parsed module.
103 * @return LY_ERR value.
Radek Krejcif0e1ba52020-05-22 15:14:35 +0200104 */
Michal Vasko7b1ad1a2020-11-02 15:41:27 +0100105LY_ERR lys_parse(struct ly_ctx *ctx, struct ly_in *in, LYS_INFORMAT format, const char **features,
Michal Vasko4de7d072021-07-09 09:13:18 +0200106 struct lys_module **module);
Radek Krejcif0e1ba52020-05-22 15:14:35 +0200107
108/**
109 * @brief Load a schema into the specified context.
110 *
aPiecekb0445f22021-06-24 11:34:07 +0200111 * This function is considered for a simple use, if you have a complex use-case,
Radek Krejci8678fa42020-08-18 16:07:28 +0200112 * consider use of ::lys_parse() with a standalone input handler.
Radek Krejcif0e1ba52020-05-22 15:14:35 +0200113 *
114 * @param[in] ctx libyang context where to process the data model.
Michal Vasko3a41dff2020-07-15 14:30:28 +0200115 * @param[in] data The string containing the dumped data model in the specified format.
Michal Vasko64c91732021-06-08 16:41:21 +0200116 * @param[in] format Format of the schema to parse.
Michal Vasko3a41dff2020-07-15 14:30:28 +0200117 * @param[out] module Optional parsed module.
118 * @return LY_ERR value.
Radek Krejcif0e1ba52020-05-22 15:14:35 +0200119 */
Michal Vasko4de7d072021-07-09 09:13:18 +0200120LY_ERR lys_parse_mem(struct ly_ctx *ctx, const char *data, LYS_INFORMAT format, struct lys_module **module);
Radek Krejcif0e1ba52020-05-22 15:14:35 +0200121
122/**
123 * @brief Read a schema from file descriptor into the specified context.
124 *
125 * \note Current implementation supports only reading data from standard (disk) file, not from sockets, pipes, etc.
126 *
aPiecekb0445f22021-06-24 11:34:07 +0200127 * This function is considered for a simple use, if you have a complex use-case,
Radek Krejci8678fa42020-08-18 16:07:28 +0200128 * consider use of ::lys_parse() with a standalone input handler.
Radek Krejcif0e1ba52020-05-22 15:14:35 +0200129 *
130 * @param[in] ctx libyang context where to process the data model.
131 * @param[in] fd File descriptor of a regular file (e.g. sockets are not supported) containing the schema
132 * in the specified format.
Michal Vasko64c91732021-06-08 16:41:21 +0200133 * @param[in] format Format of the schema to parse.
Michal Vasko3a41dff2020-07-15 14:30:28 +0200134 * @param[out] module Optional parsed module.
135 * @return LY_ERR value.
Radek Krejcif0e1ba52020-05-22 15:14:35 +0200136 */
Michal Vasko4de7d072021-07-09 09:13:18 +0200137LY_ERR lys_parse_fd(struct ly_ctx *ctx, int fd, LYS_INFORMAT format, struct lys_module **module);
Radek Krejcif0e1ba52020-05-22 15:14:35 +0200138
139/**
140 * @brief Load a schema into the specified context from a file.
141 *
aPiecekb0445f22021-06-24 11:34:07 +0200142 * This function is considered for a simple use, if you have a complex use-case,
Radek Krejci8678fa42020-08-18 16:07:28 +0200143 * consider use of ::lys_parse() with a standalone input handler.
Radek Krejcif0e1ba52020-05-22 15:14:35 +0200144 *
145 * @param[in] ctx libyang context where to process the data model.
146 * @param[in] path Path to the file with the model in the specified format.
Michal Vasko64c91732021-06-08 16:41:21 +0200147 * @param[in] format Format of the schema to parse.
Michal Vasko3a41dff2020-07-15 14:30:28 +0200148 * @param[out] module Optional parsed module.
149 * @return LY_ERR value.
Radek Krejcif0e1ba52020-05-22 15:14:35 +0200150 */
Michal Vasko4de7d072021-07-09 09:13:18 +0200151LY_ERR lys_parse_path(struct ly_ctx *ctx, const char *path, LYS_INFORMAT format, struct lys_module **module);
Radek Krejcif0e1ba52020-05-22 15:14:35 +0200152
153/**
154 * @brief Search for the schema file in the specified searchpaths.
155 *
156 * @param[in] searchpaths NULL-terminated array of paths to be searched (recursively). Current working
157 * directory is searched automatically (but non-recursively if not in the provided list). Caller can use
Radek Krejci8678fa42020-08-18 16:07:28 +0200158 * result of the ::ly_ctx_get_searchdirs().
Radek Krejcif0e1ba52020-05-22 15:14:35 +0200159 * @param[in] cwd Flag to implicitly search also in the current working directory (non-recursively).
160 * @param[in] name Name of the schema to find.
161 * @param[in] revision Revision of the schema to find. If NULL, the newest found schema filepath is returned.
162 * @param[out] localfile Mandatory output variable containing absolute path of the found schema. If no schema
163 * complying the provided restriction is found, NULL is set.
164 * @param[out] format Optional output variable containing expected format of the schema document according to the
165 * file suffix.
166 * @return LY_ERR value (LY_SUCCESS is returned even if the file is not found, then the *localfile is NULL).
167 */
Radek Krejci857189e2020-09-01 13:26:36 +0200168LY_ERR lys_search_localfile(const char * const *searchpaths, ly_bool cwd, const char *name, const char *revision,
Radek Krejci0f969882020-08-21 16:56:47 +0200169 char **localfile, LYS_INFORMAT *format);
Radek Krejcif0e1ba52020-05-22 15:14:35 +0200170
171/** @} schematree */
172
173#ifdef __cplusplus
174}
175#endif
176
177#endif /* LY_PARSER_SCHEMA_H_ */