~ubuntu-branches/ubuntu/utopic/critcl/utopic

« back to all changes in this revision

Viewing changes to doc/include/api_diversions.inc

• browse files at revision 1
• compare with another revision
• download diff
• download tarball
• view history from revision 1

Show diffs side-by-side

added

removed

doc/include/api_diversions.inc

 

1

 

 

2

Diversions are for higher-level packages generating their own C code,

 

3

to make their use of critcl's commands generating

 

4

[sectref {Embedded C Code}] easier.

 

5

 

 

6

[para] These commands normally generate all of their C code for the

 

7

current [file .critcl] file, which may not be what is wanted by a

 

8

higher-level package.

 

9

 

 

10

[para] With a diversion the generator output can be redirected into

 

11

memory and from there on then handled and processed as the caller

 

12

desires before it is committed to an actual [file .c] file.

 

13

 

 

14

[para] An example of such a package comes with critcl itself, see the

 

15

implementation of package [package critcl::class].

 

16

 

 

17

[para] To help such developers three commands are provided to manage

 

18

diversions and the collection of C code in memory. These are:

 

19

 

 

20

[list_begin definitions]

 

21

[comment {- - -- --- ----- -------- ------------- ---------------------}]

 

22

[call [cmd ::critcl::collect_begin]]

 

23

 

 

24

This command starts the diversion of C code collection into memory.

 

25

 

 

26

[para] The result of the command is the empty string.

 

27

 

 

28

[para] Multiple calls are allowed, with each call opening a new

 

29

nesting level of diversion.

 

30

 

 

31

 

 

32

[comment {- - -- --- ----- -------- ------------- ---------------------}]

 

33

[call [cmd ::critcl::collect_end]]

 

34

 

 

35

This command end the diversion of C code collection into memory and

 

36

returns the collected C code.

 

37

 

 

38

[para] If multiple levels of diversion are open the call only closes

 

39

and returns the data from the last level.

 

40

 

 

41

[para] The command will throw an error if no diversion is active,

 

42

indicating a mismatch in the pairing of [cmd collect_begin] and

 

43

[cmd collect_end].

 

44

 

 

45

[comment {- - -- --- ----- -------- ------------- ---------------------}]

 

46

[call [cmd ::critcl::collect] [arg script]]

 

47

 

 

48

This is a convenience command which runs the [arg script] under

 

49

diversion and returns the collected C code, ensuring the correct

 

50

pairing of [cmd collect_begin] and [cmd collect_end].

 

51

 

 

52

[comment {- - -- --- ----- -------- ------------- ---------------------}]

 

53

[list_end]

• Older »

Loggerhead is a web-based interface for Breezy
Version: 2.0.1