~narindergupta/charms/trusty/promise/trunk : revision 2

1

# juju-plugin-promise

b'\\ No newline at end of file'

1

# yfc -- YangForge Controller

2

3

[![Join the chat at https://gitter.im/saintkepha/yangforge](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/saintkepha/yangforge?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

4

5

`yfc` is the command shell for the YangForge framework, providing

6

schema-driven application lifecycle management.

7

8

`YangForge` provides runtime JavaScript execution based on YANG schema

9

modeling language as defined in IETF drafts and standards

10

([RFC 6020](http://tools.ietf.org/html/rfc6020)).

11

12

[![NPM Version][npm-image]][npm-url]

13

[![NPM Downloads][downloads-image]][downloads-url]

14

15

[![NPM][history-image]][history-url]

16

17

Basically, the framework enables YANG schema language to *become* a

18

**programming** language.

19

20

It also utilizes YAML with custom tags to construct a portable module

21

with embedded code.

22

23

It is written primarily using [CoffeeScript](http://coffeescript.org)

24

and runs on [Node.js](http://nodejs.org) and the **web browser** (yes, it's isomorphic).

25

26

This software is **sponsored** by

27

[ClearPath Networks](http://www.clearpathnet.com) on behalf of the

28

[OPNFV](http://opnfv.org) (Open Platform for Network Functions

29

Virtualization) community. For a reference implementation created entirely utilizing `YangForge`, please take a look at [OPNFV Promise](http://github.com/opnfv/promise) which provides future resource/capacity management (reservations/allocations) for virtualized infrastructure.

30

31

Please note that this project is under **active development**. Be sure

32

to check back often as new updates are being pushed regularly.

33

34

## Installation

35

```bash

36

$ npm install -g yangforge

37

```

38

39

You must have `node >= 0.10.28` as a minimum requirement to run

40

`yangforge`.

41

42

## Usage

43

```

44

Usage: yfc [options] [command]

45

46

47

Commands:

48

49

build [options] [file] package the application for deployment

50

config manage yangforge service configuration (planned)

51

deploy deploy application into yangforge endpoint (planned)

52

info [options] [name] shows info about a specific module

53

publish [options] publish package to upstream registry (planned)

54

run [options] [modules...] runs one or more modules and/or schemas

55

schema [options] [file] process a specific YANG schema file or string

56

sign sign package to ensure authenticity (planned)

57

58

YANG driven JS application builder

59

60

Options:

61

62

-h, --help output usage information

63

-V, --version output the version number

64

--no-color disable color output

65

```

66

67

The `yfc` command-line interface is **runtime-generated** according to

68

[yangforge.yang](yangforge.yang) schema definitions. Please refer to

69

the schema section covering various `rpc` extension statements and

70

sub-statement definitions for a reference regarding different types of

71

command-line arguments, descriptions, and options processing syntax.

72

The corresponding **actions** for each of the `rpc` extensions are

73

implemented inside the `YangForge` YAML module

74

[package.yaml](package.yaml).

75

76

For comprehensive **usage documentation** around various CLI commands,

77

please refer to the [YangForge Examples README](examples#readme).

78

79

## Troubleshooting

80

81

When you encounter errors or issues while utilizing the `yfc` command

82

line utility, you can set ENVIRONMENTAL variable `yfc_debug=1` to get

83

complete debug output of the `YangForge` execution log.

84

85

```bash

86

$ yfc_debug=1 yfc <some-command>

87

```

88

89

The output generated is very verbose and may or may not assist you in

90

determining the root cause. However, when reporting an issue into the

91

Github repository, it will be helpful to paste a snippet of the debug

92

output for quicker resolution by the project maintainer.

93

94

## Bundled YANG schema modules

95

96

There are a number of YANG schema modules commonly referenced and

97

utilized by other YANG modules during schema definition and they have

98

been *bundled* together into the `yangforge` package for convenience.

99

All you need to do is to `import <module name>` from your YANG schema

100

and they will be retrieved/resolved automatically.

101

102

name | description | reference

103

--- | --- | ---

104

[complex-types](core/complex-types.yang) | extensions to model complex types and typed instance identifiers | RFC-6095

105

[iana-crypt-hash](core/iana-crypt-hash.yang) | typedef for storing passwords using a hash function | RFC-7317

106

[ietf-inet-types](core/ietf-inet-types.yang) | collection of generally useful types for Internet addresses | RFC-6991

107

[ietf-yang-types](core/ietf-yang-types.yang) | collection of generally useful derived data types | RFC-6991

108

109

Additional YANG modules will be bundled into the `yangforge` package

110

over time. Since `yangforge` facilitate *forging* of new YANG modules

111

and easily using them in your own projects, only industry standards

112

based YANG schema modules will be considered for native bundling at

113

this time.

114

115

## Bundled YANG features

116

117

name | description | dependency

118

--- | --- | ---

119

[cli](features/cli.coffee) | generates command-line interface | none

120

[express](features/express.coffee) | generates HTTP/HTTPS web server instance | none

121

[restjson](features/restjson.coffee) | generates REST/JSON web services interface | express

122

[websocket](features/websocket.coffee) | generates socket.io interface | express

123

124

You can click on the *name* entry above for reference documentation on

125

each feature module.

126

127

## Using YangForge Programmatically

128

129

```coffeescript

130

forge = require 'yangforge'

131

forge.import 'my-cool-schema.yang'

132

.then (app) ->

133

console.log app.info()

134

```

135

136

### Key Features

137

138

* **Parse** YAML/YANG/JSON schema files and generate runtime

139

JavaScript semantic object tree hierarchy

140

* **Import/Export** capabilities to load modules using customizable

141

importers based on regular expressions and custom import

142

routines. Ability to serialize module meta data into JSON format

143

that is portable across systems. Also exports serialized JS

144

functions as part of export meta data.

145

* **Runtime Generation** allows compiler to directly create a live JS

146

class object definition so that it can be instantiated via `new`

147

keyword and used immediately

148

* **Dynamic Extensions** enable compiler to be configured with

149

alternative `resolver` functions to change the behavior of produced

150

output

151

152

[YangForge](src/forge.coffee) itself is also a YANG schema

153

([yangforge.yang](./yangforge.yang)) **compiled** module. It is

154

compiled by the [yang-compiler](src/compiler.litcoffee) and

155

natively includes

156

[yang-v1-extensions](core/yang-v1-extensions.yaml) submodule for

157

supporting the YANG version 1.0

158

([RFC 6020](http://tools.ietf.org/html/rfc6020)) specifications.

159

Please reference the

160

[yang-v1-extensions documentation](core/yang-v1-extensions.md) for

161

up-to-date info on YANG 1.0 language coverage status. It serves as a

162

good reference for writing new compilers, custom extensions, custom

163

typedefs, among other things.

164

165

### Primary interfaces

166

167

name | description

168

--- | ---

169

forge.import | local/remote async loading of one or more modules using filenames

170

forge.load | local async/sync loading of module(s), only one-at-a-time with sync

171

forge.compile | local sync compilation of a module, generates class obj that can be instantiated

172

forge.preprocess | local sync preprocessing of a module, constraint validations, schema manipulations

173

forge.parse | local sync parsing of a module, syntax validations, custom-tag resolutions

174

175

### Programmatic Usage Examples

176

177

The below examples can be executed using CoffeeScript REPL by running

178

`coffee` at the command-line from the top-directory of this repo.

179

180

Using the native YangForge module as a library:

181

182

```coffeescript

183

forge = require 'yangforge'

184

185

yang = """

186

module hello-world {

187

description "a test";

188

leaf hello { type string; default "world"; }

189

}

190

"""

191

192

# asynchronous load YANG schema

193

forge.load schema: yang

194

.then (app) ->

195

console.log app.get 'hello-world.hello'

196

app.set 'hello-world.hello', 'goodbye'

197

console.log app.get()

198

199

# synchronous load YANG schema

200

app = forge.load schmea: yang, async: false

201

console.log app.info format: 'json'

202

203

# compile YANG schema model as class object

204

HelloWorld = forge.compile schema: yang

205

hello = new HelloWorld 'hello-world': hello: 'howdy there'

206

console.log hello.get()

207

208

yaml = """

209

210

schema: !yang |

211

module embedded-world { leaf wow { type number; default 0; } }

212

config: !json |

213

{ "embedded-world": { "wow": 2 } }

214

"""

215

216

# it can do YAML quite well

217

forge.load yaml

218

.then (app) ->

219

console.log app.get()

220

221

# sometimes you just want to preprocess to see what it becomes

222

console.log forge.preprocess yaml

223

```

224

225

Forging a new module/application for build/publish using YAML

226

(see also [complex-types](core/complex-types.yaml)):

227

```coffeescript

228

229

schema: !yang some-new-application.yang

230

rpc:

231

something-useful: !coffee/function

232

(input, output, done) ->

233

console.log input.get()

234

output.set 'important data'

235

done()

236

```

237

238

Forging a new interface generator using YAML (see also

239

[cli example](features/cli.yaml)):

240

```yaml

241

242

description: Some new awesome interface

243

run: !coffee/function

244

(model, options) ->

245

# code logic to dynamically construct a new interface based on passed-in context

246

console.log model

247

```

248

249

There are many other ways of interacting with the module's class

250

object as well as the instantiated class.

251

252

**More examples coming soon!**

253

254

## Literate CoffeeScript Documentation

255

256

The source code is documented in Markdown format. It's code combined

257

with documentation all-in-one.

258

259

* [YangForge](src/forge.coffee)

260

* [Compiler](src/compiler.litcoffee)

261

* [Features](features)

262

* [Module](package.yaml)

263

* [Schema](yangforge.yang)

264

* External Dependencies

265

* [data-synth library](http://github.com/saintkepha/data-synth)

266

* [js-yaml library](https://github.com/nodeca/js-yaml)

267

* [yang-parser library](https://gitlab.labs.nic.cz/labs/yang-tools/wikis/coffee_parser)

268

269

## License

270

[Apache 2.0](LICENSE)

271

272

[npm-image]: https://img.shields.io/npm/v/yangforge.svg

273

[npm-url]: https://npmjs.org/package/yangforge

274

[downloads-image]: https://img.shields.io/npm/dm/yangforge.svg

275

[downloads-url]: https://npmjs.org/package/yangforge

276

[history-image]: https://nodei.co/npm-dl/yangforge.png?height=3

277

[history-url]: https://nodei.co/npm/yangforge

278