From d67794d2ad332dea3c31edae948d22da172c1a03 Mon Sep 17 00:00:00 2001 From: Cyrus Harrison Date: Fri, 27 Dec 2019 20:47:59 -0800 Subject: [PATCH] update docs with info about Node parse --- ...conduit_docs_python_tutorial_parse_out.txt | 76 ++++ .../t_conduit_docs_tutorial_examples_out.txt | 390 ------------------ ... => t_conduit_docs_tutorial_parse_out.txt} | 84 ++-- src/docs/sphinx/tutorial_cpp.rst | 2 +- src/docs/sphinx/tutorial_cpp_json.rst | 88 ++-- src/docs/sphinx/tutorial_cpp_parse.rst | 192 +++++++++ src/docs/sphinx/tutorial_python.rst | 2 +- src/docs/sphinx/tutorial_python_json.rst | 82 ---- src/docs/sphinx/tutorial_python_parse.rst | 190 +++++++++ src/tests/docs/CMakeLists.txt | 3 +- .../docs/t_conduit_docs_tutorial_json.cpp | 174 -------- .../docs/t_conduit_docs_tutorial_parse.cpp | 134 ++++++ ...> t_conduit_docs_tutorial_python_parse.py} | 69 +++- 13 files changed, 770 insertions(+), 716 deletions(-) create mode 100644 src/docs/sphinx/t_conduit_docs_python_tutorial_parse_out.txt delete mode 100644 src/docs/sphinx/t_conduit_docs_tutorial_examples_out.txt rename src/docs/sphinx/{t_conduit_docs_tutorial_json_out.txt => t_conduit_docs_tutorial_parse_out.txt} (50%) create mode 100644 src/docs/sphinx/tutorial_cpp_parse.rst delete mode 100644 src/docs/sphinx/tutorial_python_json.rst create mode 100644 src/docs/sphinx/tutorial_python_parse.rst delete mode 100644 src/tests/docs/t_conduit_docs_tutorial_json.cpp rename src/tests/docs/{t_conduit_docs_tutorial_python_json.py => t_conduit_docs_tutorial_python_parse.py} (58%) diff --git a/src/docs/sphinx/t_conduit_docs_python_tutorial_parse_out.txt b/src/docs/sphinx/t_conduit_docs_python_tutorial_parse_out.txt new file mode 100644 index 000000000..83a42773a --- /dev/null +++ b/src/docs/sphinx/t_conduit_docs_python_tutorial_parse_out.txt @@ -0,0 +1,76 @@ +UpdateCTestConfiguration from :/Users/harrison37/Work/github/llnl/conduit/build-debug/DartConfiguration.tcl +Parse Config file:/Users/harrison37/Work/github/llnl/conduit/build-debug/DartConfiguration.tcl +UpdateCTestConfiguration from :/Users/harrison37/Work/github/llnl/conduit/build-debug/DartConfiguration.tcl +Parse Config file:/Users/harrison37/Work/github/llnl/conduit/build-debug/DartConfiguration.tcl +Test project /Users/harrison37/Work/github/llnl/conduit/build-debug +Constructing a list of tests +Done constructing a list of tests +Updating test list for fixtures +Added 0 tests to meet fixture requirements +Checking test dependency graph... +Checking test dependency graph end +test 104 + Start 104: t_conduit_docs_tutorial_python_parse + +104: Test command: /Users/harrison37/Work/github/llnl/conduit/uberenv_libs/spack/opt/spack/darwin-highsierra-x86_64/clang-9.0.0-apple/python-3.7.4-ss4j2sdo26gewstsqqmjxxzri7ozxevh/bin/python3.7 "-B" "-m" "unittest" "-v" "t_conduit_docs_tutorial_python_parse" +104: Environment variables: +104: PYTHONPATH=/Users/harrison37/Work/github/llnl/conduit/build-debug/python-modules/:/Users/harrison37/Work/github/llnl/conduit/src/tests/docs +104: Test timeout computed to be: 1500 +104: test_docs_tutorial_json (t_conduit_docs_tutorial_python_parse.Conduit_Tutorial_Python_Parse) ... ok +104: test_docs_tutorial_yaml (t_conduit_docs_tutorial_python_parse.Conduit_Tutorial_Python_Parse) ... ok +104: test_docs_tutorial_yaml_inline_array (t_conduit_docs_tutorial_python_parse.Conduit_Tutorial_Python_Parse) ... ok +104: test_json_generator_pure_json (t_conduit_docs_tutorial_python_parse.Conduit_Tutorial_Python_Parse) ... ok +104: test_json_generator_pure_yaml (t_conduit_docs_tutorial_python_parse.Conduit_Tutorial_Python_Parse) ... ok +104: test_json_generator_std (t_conduit_docs_tutorial_python_parse.Conduit_Tutorial_Python_Parse) ... ok +104: +104: ---------------------------------------------------------------------- +104: Ran 6 tests in 0.001s +104: +104: OK +104: BEGIN_EXAMPLE("t_py_conduit_docs_tutorial_json") +104: 42.0 +104: +104: { +104: "mykey": {"dtype":"float64", "number_of_elements": 1, "offset": 0, "stride": 8, "element_bytes": 8, "endianness": "little"} +104: } +104: END_EXAMPLE("t_py_conduit_docs_tutorial_json") +104: BEGIN_EXAMPLE("t_py_conduit_docs_tutorial_yaml") +104: 42.0 +104: +104: { +104: "mykey": {"dtype":"float64", "number_of_elements": 1, "offset": 0, "stride": 8, "element_bytes": 8, "endianness": "little"} +104: } +104: END_EXAMPLE("t_py_conduit_docs_tutorial_yaml") +104: BEGIN_EXAMPLE("t_py_conduit_docs_tutorial_yaml_inline_array") +104: [ 0. 10. 20. 30.] +104: {"dtype":"float64", "number_of_elements": 4, "offset": 0, "stride": 8, "element_bytes": 8, "endianness": "little"} +104: END_EXAMPLE("t_py_conduit_docs_tutorial_yaml_inline_array") +104: BEGIN_EXAMPLE("t_py_json_generator_pure_json") +104: 100.0 +104: +104: { +104: "test": 100.0 +104: } +104: END_EXAMPLE("t_py_json_generator_pure_json") +104: BEGIN_EXAMPLE("t_py_json_generator_pure_yaml") +104: 100.0 +104: +104: { +104: "test": 100.0 +104: } +104: END_EXAMPLE("t_py_json_generator_pure_yaml") +104: BEGIN_EXAMPLE("t_py_json_generator_std") +104: 100.0 +104: +104: { +104: "test": 100.0 +104: } +104: END_EXAMPLE("t_py_json_generator_std") +1/1 Test #104: t_conduit_docs_tutorial_python_parse ... Passed 0.17 sec + +The following tests passed: + t_conduit_docs_tutorial_python_parse + +100% tests passed, 0 tests failed out of 1 + +Total Test time (real) = 0.20 sec diff --git a/src/docs/sphinx/t_conduit_docs_tutorial_examples_out.txt b/src/docs/sphinx/t_conduit_docs_tutorial_examples_out.txt deleted file mode 100644 index 85b6a7528..000000000 --- a/src/docs/sphinx/t_conduit_docs_tutorial_examples_out.txt +++ /dev/null @@ -1,390 +0,0 @@ -Running main() from gtest_main.cc -[==========] Running 21 tests from 1 test case. -[----------] Global test environment set-up. -[----------] 21 tests from conduit_tutorial -[ RUN ] conduit_tutorial.basics_very_basic -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 63] - basics_very_basic - -{ - "my": "data" -} -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 69] - basics_very_basic -[ OK ] conduit_tutorial.basics_very_basic (0 ms) -[ RUN ] conduit_tutorial.basics_hierarchial -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 75] - basics_hierarchial - -{ - "my": "data", - "a": - { - "b": - { - "c": "d", - "e": 64.0 - } - } -} -total bytes: 15 -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 85] - basics_hierarchial -[ OK ] conduit_tutorial.basics_hierarchial (0 ms) -[ RUN ] conduit_tutorial.basics_object_and_list -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 91] - basics_object_and_list - -{ - "object_example": - { - "val1": "data", - "val2": 10, - "val3": 3.1415 - }, - "list_example": - [ - 0, - 1, - 2, - 3, - 4 - ] -} -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 106] - basics_object_and_list -[ OK ] conduit_tutorial.basics_object_and_list (0 ms) -[ RUN ] conduit_tutorial.basics_object_and_list_itr -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 112] - basics_object_and_list_itr - -{ - "object_example": - { - "val1": "data", - "val2": 10, - "val3": 3.1415 - }, - "list_example": - [ - 0, - 1, - 2, - 3, - 4 - ] -} -val1: "data" -val2: 10 -val3: 3.1415 -0 -1 -2 -3 -4 -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 143] - basics_object_and_list_itr -[ OK ] conduit_tutorial.basics_object_and_list_itr (0 ms) -[ RUN ] conduit_tutorial.basics_mem_spaces -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 150] - basics_mem_spaces - -{ - "mem_spaces": - { - "0x7fd7dac04570": - { - "path": "my", - "type": "allocated", - "bytes": 5 - }, - "0x7fd7dac07690": - { - "path": "a/b/c", - "type": "allocated", - "bytes": 2 - }, - "0x7fd7dac07680": - { - "path": "a/b/e", - "type": "allocated", - "bytes": 8 - } - }, - "total_bytes_allocated": 15, - "total_bytes_mmaped": 0, - "total_bytes_compact": 15, - "total_strided_bytes": 15 -} -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 161] - basics_mem_spaces -[ OK ] conduit_tutorial.basics_mem_spaces (1 ms) -[ RUN ] conduit_tutorial.basics_bw_style -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 167] - basics_bw_style - -{ - "test": 100 -} - -{ - "test": {"dtype":"uint32", "number_of_elements": 1, "offset": 0, "stride": 4, "element_bytes": 4, "endianness": "little", "value": 100} -} -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 175] - basics_bw_style -[ OK ] conduit_tutorial.basics_bw_style (0 ms) -[ RUN ] conduit_tutorial.basics_bw_style_from_native -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 181] - basics_bw_style_from_native - -{ - "test": {"dtype":"int32", "number_of_elements": 1, "offset": 0, "stride": 4, "element_bytes": 4, "endianness": "little", "value": 100} -} -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 188] - basics_bw_style_from_native -[ OK ] conduit_tutorial.basics_bw_style_from_native (0 ms) -[ RUN ] conduit_tutorial.numeric_as_dtype -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 196] - numeric_as_dtype -100 -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 203] - numeric_as_dtype -[ OK ] conduit_tutorial.numeric_as_dtype (0 ms) -[ RUN ] conduit_tutorial.numeric_via_value -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 210] - numeric_via_value -100 -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 218] - numeric_via_value -[ OK ] conduit_tutorial.numeric_via_value (0 ms) -[ RUN ] conduit_tutorial.numeric_ptr_as_dtype -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 226] - numeric_ptr_as_dtype -my_vals[0] = 100 -my_vals[1] = 200 -my_vals[2] = 300 -my_vals[3] = 400 -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 240] - numeric_ptr_as_dtype -[ OK ] conduit_tutorial.numeric_ptr_as_dtype (0 ms) -[ RUN ] conduit_tutorial.numeric_ptr_via_value -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 247] - numeric_ptr_via_value -my_vals[0] = 100 -my_vals[1] = 200 -my_vals[2] = 300 -my_vals[3] = 400 -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 261] - numeric_ptr_via_value -[ OK ] conduit_tutorial.numeric_ptr_via_value (0 ms) -[ RUN ] conduit_tutorial.numeric_strided_data_array -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 268] - numeric_strided_data_array -my_vals[0] = 100 -my_vals[1] = 300 -[100, 300] -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 286] - numeric_strided_data_array -[ OK ] conduit_tutorial.numeric_strided_data_array (0 ms) -[ RUN ] conduit_tutorial.numeric_double_conversion_start -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 292] - numeric_double_conversion_start -[ OK ] conduit_tutorial.numeric_double_conversion_start (0 ms) -[ RUN ] conduit_tutorial.numeric_double_conversion -float32 case: - converting to temporary double array -[100.0, 200.0, 300.0, 400.0] -vals[0] = 100 -vals[1] = 200 -vals[2] = 300 -vals[3] = 400 -double case: - using existing buffer -[1000.0, 2000.0, 3000.0, 4000.0] -vals[0] = 1000 -vals[1] = 2000 -vals[2] = 3000 -vals[3] = 4000 -[ OK ] conduit_tutorial.numeric_double_conversion (0 ms) -[ RUN ] conduit_tutorial.numeric_double_conversion_end -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 358] - numeric_double_conversion_end -[ OK ] conduit_tutorial.numeric_double_conversion_end (0 ms) -[ RUN ] conduit_tutorial.json_generator_std -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 365] - json_generator_std -100 - -{ - "test": 100.0 -} - -{ - "test": {"dtype":"float64", "number_of_elements": 1, "offset": 0, "stride": 8, "element_bytes": 8, "endianness": "little", "value": 100.0} -} -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 376] - json_generator_std -[ OK ] conduit_tutorial.json_generator_std (0 ms) -[ RUN ] conduit_tutorial.json_generator_pure_json -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 382] - json_generator_pure_json -100 - -{ - "test": {"dtype":"float64", "number_of_elements": 1, "offset": 0, "stride": 8, "element_bytes": 8, "endianness": "little", "value": 100.0} -} - -{ - "test": 100.0 -} -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 393] - json_generator_pure_json -[ OK ] conduit_tutorial.json_generator_pure_json (0 ms) -[ RUN ] conduit_tutorial.json_generator_bind_to_incore -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 399] - json_generator_bind_to_incore -100 vs 100 -200 vs 200 - -{ - "a": 100.0, - "b": 200.0 -} - -{ - "mem_spaces": - { - "0x7fff5103bfa0": - { - "path": "a", - "type": "external" - } - }, - "total_bytes_allocated": 0, - "total_bytes_mmaped": 0, - "total_bytes_compact": 16, - "total_strided_bytes": 16 -} -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 418] - json_generator_bind_to_incore -[ OK ] conduit_tutorial.json_generator_bind_to_incore (0 ms) -[ RUN ] conduit_tutorial.json_generator_compact -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 425] - json_generator_compact -[100.0, 200.0, 300.0, 400.0, 500.0] -[-100.0, -200.0, -300.0, -400.0, -500.0] - -{ - "mem_spaces": - { - "0x7fff5103bf60": - { - "path": "", - "type": "external" - } - }, - "total_bytes_allocated": 0, - "total_bytes_mmaped": 0, - "total_bytes_compact": 40, - "total_strided_bytes": 72 -} - -{ - "mem_spaces": - { - "0x7fff5103bf60": - { - "path": "", - "type": "external" - } - }, - "total_bytes_allocated": 0, - "total_bytes_mmaped": 0, - "total_bytes_compact": 40, - "total_strided_bytes": 72 -} -[100.0, 200.0, 300.0, 400.0, 500.0] -{"dtype":"float64", "number_of_elements": 5, "offset": 0, "stride": 8, "element_bytes": 8, "endianness": "little"} - -{ - "mem_spaces": - { - "0x7fd7dac07960": - { - "path": "", - "type": "allocated", - "bytes": 40 - } - }, - "total_bytes_allocated": 40, - "total_bytes_mmaped": 0, - "total_bytes_compact": 40, - "total_strided_bytes": 40 -} -[-100.0, -200.0, -300.0, -400.0, -500.0] - -{ - "mem_spaces": - { - "0x7fd7dac07ac0": - { - "path": "", - "type": "allocated", - "bytes": 40 - } - }, - "total_bytes_allocated": 40, - "total_bytes_mmaped": 0, - "total_bytes_compact": 40, - "total_strided_bytes": 40 -} -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 476] - json_generator_compact -[ OK ] conduit_tutorial.json_generator_compact (1 ms) -[ RUN ] conduit_tutorial.mem_ownership_external -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 483] - mem_ownership_external - -{ - "mem_spaces": - { - "0x7fd7dac06500": - { - "path": "v_owned", - "type": "allocated", - "bytes": 40 - }, - "0x7fd7dac064d0": - { - "path": "v_external", - "type": "external" - } - }, - "total_bytes_allocated": 40, - "total_bytes_mmaped": 0, - "total_bytes_compact": 80, - "total_strided_bytes": 80 -} - -{ - "v_owned": [0.0, 3.1415, 6.283, 9.4245, 12.566], - "v_external": [0.0, 3.1415, 6.283, 9.4245, 12.566] -} - -{ - "v_owned": [0.0, 3.1415, 6.283, 9.4245, 12.566], - "v_external": [0.0, -3.1415, 6.283, 9.4245, 12.566] -} -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_examples.cpp : 503] - mem_ownership_external -[ OK ] conduit_tutorial.mem_ownership_external (0 ms) -[ RUN ] conduit_tutorial.error_handlers -[INFO] An info message -[WARNING!] Node::as_float32() const -- DataType float64 at path my_value does not equal expected DataType float32 -[ERROR!] Cannot const fetch_child, Node(my_value) is not an object -[ OK ] conduit_tutorial.error_handlers (0 ms) -[----------] 21 tests from conduit_tutorial (2 ms total) - -[----------] Global test environment tear-down -[==========] 21 tests from 1 test case ran. (2 ms total) -[ PASSED ] 21 tests. diff --git a/src/docs/sphinx/t_conduit_docs_tutorial_json_out.txt b/src/docs/sphinx/t_conduit_docs_tutorial_parse_out.txt similarity index 50% rename from src/docs/sphinx/t_conduit_docs_tutorial_json_out.txt rename to src/docs/sphinx/t_conduit_docs_tutorial_parse_out.txt index f00ab17ae..d92517d59 100644 --- a/src/docs/sphinx/t_conduit_docs_tutorial_json_out.txt +++ b/src/docs/sphinx/t_conduit_docs_tutorial_parse_out.txt @@ -1,10 +1,36 @@ Running main() from gtest_main.cc -[==========] Running 4 tests from 1 test case. +[==========] Running 8 tests from 1 test case. [----------] Global test environment set-up. -[----------] 4 tests from conduit_tutorial +[----------] 8 tests from conduit_tutorial +[ RUN ] conduit_tutorial.t_conduit_docs_tutorial_yaml +BEGIN_EXAMPLE("t_conduit_docs_tutorial_yaml") +42 + +{ + "mykey": {"dtype":"float64", "number_of_elements": 1, "offset": 0, "stride": 8, "element_bytes": 8, "endianness": "little", "value": 42.0} +} +END_EXAMPLE("t_conduit_docs_tutorial_yaml") +[ OK ] conduit_tutorial.t_conduit_docs_tutorial_yaml (1 ms) +[ RUN ] conduit_tutorial.t_conduit_docs_tutorial_json +BEGIN_EXAMPLE("t_conduit_docs_tutorial_json") +42 + +{ + "mykey": {"dtype":"float64", "number_of_elements": 1, "offset": 0, "stride": 8, "element_bytes": 8, "endianness": "little", "value": 42.0} +} +END_EXAMPLE("t_conduit_docs_tutorial_json") +[ OK ] conduit_tutorial.t_conduit_docs_tutorial_json (0 ms) +[ RUN ] conduit_tutorial.t_conduit_docs_tutorial_yaml_inline_array +BEGIN_EXAMPLE("t_conduit_docs_tutorial_yaml_inline_array") +[0.0, 10.0, 20.0, 30.0] + +{ + "myarray": {"dtype":"float64", "number_of_elements": 4, "offset": 0, "stride": 8, "element_bytes": 8, "endianness": "little", "value": [0.0, 10.0, 20.0, 30.0]} +} +END_EXAMPLE("t_conduit_docs_tutorial_yaml_inline_array") +[ OK ] conduit_tutorial.t_conduit_docs_tutorial_yaml_inline_array (0 ms) [ RUN ] conduit_tutorial.json_generator_std -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_json.cpp : 62] - json_generator_std +BEGIN_EXAMPLE("t_json_generator_std") 100 { @@ -14,12 +40,10 @@ Running main() from gtest_main.cc { "test": {"dtype":"float64", "number_of_elements": 1, "offset": 0, "stride": 8, "element_bytes": 8, "endianness": "little", "value": 100.0} } -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_json.cpp : 73] - json_generator_std +END_EXAMPLE("t_json_generator_std") [ OK ] conduit_tutorial.json_generator_std (0 ms) [ RUN ] conduit_tutorial.json_generator_pure_json -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_json.cpp : 79] - json_generator_pure_json +BEGIN_EXAMPLE("t_json_generator_pure_json") 100 { @@ -29,12 +53,23 @@ Running main() from gtest_main.cc { "test": 100.0 } -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_json.cpp : 90] - json_generator_pure_json +END_EXAMPLE("t_json_generator_pure_json") [ OK ] conduit_tutorial.json_generator_pure_json (0 ms) +[ RUN ] conduit_tutorial.json_generator_pure_yaml +BEGIN_EXAMPLE("t_json_generator_pure_yaml") +100 + +{ + "test": {"dtype":"float64", "number_of_elements": 1, "offset": 0, "stride": 8, "element_bytes": 8, "endianness": "little", "value": 100.0} +} + +{ + "test": 100.0 +} +END_EXAMPLE("t_json_generator_pure_yaml") +[ OK ] conduit_tutorial.json_generator_pure_yaml (0 ms) [ RUN ] conduit_tutorial.json_generator_bind_to_incore -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_json.cpp : 96] - json_generator_bind_to_incore +BEGIN_EXAMPLE("t_json_generator_bind_to_incore") 100 vs 100 200 vs 200 @@ -46,7 +81,7 @@ Running main() from gtest_main.cc { "mem_spaces": { - "0x7fff5b4da040": + "0x7ffee1aafda0": { "path": "a", "type": "external" @@ -57,19 +92,17 @@ Running main() from gtest_main.cc "total_bytes_compact": 16, "total_strided_bytes": 16 } -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_json.cpp : 115] - json_generator_bind_to_incore +END_EXAMPLE("t_json_generator_bind_to_incore") [ OK ] conduit_tutorial.json_generator_bind_to_incore (0 ms) [ RUN ] conduit_tutorial.json_generator_compact -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_json.cpp : 122] - json_generator_compact +BEGIN_EXAMPLE("t_json_generator_compact") [100.0, 200.0, 300.0, 400.0, 500.0] [-100.0, -200.0, -300.0, -400.0, -500.0] { "mem_spaces": { - "0x7fff5b4da000": + "0x7ffee1aafd60": { "path": "", "type": "external" @@ -84,7 +117,7 @@ Running main() from gtest_main.cc { "mem_spaces": { - "0x7fff5b4da000": + "0x7ffee1aafd60": { "path": "", "type": "external" @@ -101,7 +134,7 @@ Running main() from gtest_main.cc { "mem_spaces": { - "0x7fe5e2c05540": + "0x7f8324700680": { "path": "", "type": "allocated", @@ -118,7 +151,7 @@ Running main() from gtest_main.cc { "mem_spaces": { - "0x7fe5e2c05d80": + "0x7f8324700600": { "path": "", "type": "allocated", @@ -130,11 +163,10 @@ Running main() from gtest_main.cc "total_bytes_compact": 40, "total_strided_bytes": 40 } -[/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_json.cpp : 173] - json_generator_compact +END_EXAMPLE("t_json_generator_compact") [ OK ] conduit_tutorial.json_generator_compact (1 ms) -[----------] 4 tests from conduit_tutorial (1 ms total) +[----------] 8 tests from conduit_tutorial (2 ms total) [----------] Global test environment tear-down -[==========] 4 tests from 1 test case ran. (1 ms total) -[ PASSED ] 4 tests. +[==========] 8 tests from 1 test case ran. (2 ms total) +[ PASSED ] 8 tests. diff --git a/src/docs/sphinx/tutorial_cpp.rst b/src/docs/sphinx/tutorial_cpp.rst index 24aa06b41..28d075c03 100644 --- a/src/docs/sphinx/tutorial_cpp.rst +++ b/src/docs/sphinx/tutorial_cpp.rst @@ -54,7 +54,7 @@ of examples for Conduit's Core API and additional libraries. tutorial_cpp_basics tutorial_cpp_numeric - tutorial_cpp_json + tutorial_cpp_parse tutorial_cpp_ownership tutorial_cpp_update tutorial_cpp_errors diff --git a/src/docs/sphinx/tutorial_cpp_json.rst b/src/docs/sphinx/tutorial_cpp_json.rst index 5f1554038..6a652e0a8 100644 --- a/src/docs/sphinx/tutorial_cpp_json.rst +++ b/src/docs/sphinx/tutorial_cpp_json.rst @@ -43,7 +43,7 @@ .. ############################################################################ ================================== -Reading YAML and JSON +Reading YAML and JSON Strings ================================== Parsing text with *Node::parse()* @@ -75,7 +75,15 @@ Parsing text with *Node::parse()* :start-after: BEGIN_EXAMPLE("t_conduit_docs_tutorial_json") :end-before: END_EXAMPLE("t_conduit_docs_tutorial_json") -For leaf nodes wide types such as *int64*, *uint64*, and *float64* are inferred. +The first argument is the string to parse and the second argument +selects the protocol to use when parsing. + +Valid Protocols: ``json``, ``conduit_json``, ``conduit_base64_json``, ``yaml``. + +* ``json`` and ``yaml`` protocols parse pure JSON or YAML strings. For leaf + nodes wide types such as *int64*, *uint64*, and *float64* are inferred. + + Homogeneous numeric lists are parsed as Conduit arrays. .. # from t_conduit_docs_tutorial_parse: t_conduit_docs_tutorial_yaml_inline_array @@ -90,53 +98,78 @@ Homogeneous numeric lists are parsed as Conduit arrays. :start-after: BEGIN_EXAMPLE("t_conduit_docs_tutorial_yaml_inline_array") :end-before: END_EXAMPLE("t_conduit_docs_tutorial_yaml_inline_array") +* ``conduit_json`` parses JSON with conduit data type information, allowing you + to specify bitwidth style types, strides, etc. + +* ``conduit_base64_json`` combies the *conduit_json* protocol with an embedded + base64-encoded data block ====================== Generators ====================== - -*Generator* instances to parse JSON schemas +Using *Generator* instances --------------------------------------------------- -Node::parse() is sufficient for most use case, but you can also use a *Generator* c -lass instance to parse JSON and YAML. Generators also allow you to parse a conduit JSON -schema and bind to in-core data. - +Node::parse() is sufficient for most use cases, but you can also use a *Generator* +instance to parse JSON and YAML. Additionally, Generators can parse a +conduit JSON schema and bind it to in-core data. .. # from t_conduit_docs_tutorial_json: json_generator_std -.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_json.cpp - :lines: 63-72 +.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_parse.cpp + :start-after: BEGIN_EXAMPLE("t_json_generator_std") + :end-before: END_EXAMPLE("t_json_generator_std") :language: cpp :dedent: 4 -.. literalinclude:: t_conduit_docs_tutorial_json_out.txt - :lines: 8-16 +.. literalinclude:: t_conduit_docs_tutorial_parse_out.txt + :start-after: BEGIN_EXAMPLE("t_json_generator_std") + :end-before: END_EXAMPLE("t_json_generator_std") -The *Generator* can also parse pure json. For leaf nodes: wide types such as *int64*, *uint64*, and *float64* are inferred. +Like *Node::parse()*, *Generators* can also parse pure JSON or YAML. +For leaf nodes: wide types such as *int64*, *uint64*, and *float64* are inferred. .. # from t_conduit_docs_tutorial_json: json_generator_pure_json -.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_json.cpp - :lines: 80-89 +.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_parse.cpp + :start-after: BEGIN_EXAMPLE("t_json_generator_pure_json") + :end-before: END_EXAMPLE("t_json_generator_pure_json") + :language: cpp + :dedent: 4 + +.. literalinclude:: t_conduit_docs_tutorial_parse_out.txt + :start-after: BEGIN_EXAMPLE("t_json_generator_pure_json") + :end-before: END_EXAMPLE("t_json_generator_pure_json") + +.. # from t_conduit_docs_tutorial_json: json_generator_pure_yaml + +.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_parse.cpp + :start-after: BEGIN_EXAMPLE("t_json_generator_pure_yaml") + :end-before: END_EXAMPLE("t_json_generator_pure_yaml") :language: cpp :dedent: 4 -.. literalinclude:: t_conduit_docs_tutorial_json_out.txt - :lines: 23-31 +.. literalinclude:: t_conduit_docs_tutorial_parse_out.txt + :start-after: BEGIN_EXAMPLE("t_json_generator_pure_yaml") + :end-before: END_EXAMPLE("t_json_generator_pure_yaml") + + -Schemas can easily be bound to in-core data. +Schemas can be bound to in-core data. .. # from t_conduit_docs_tutorial_json: json_generator_bind_to_incore -.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_json.cpp - :lines: 97-114 +.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_parse.cpp + :start-after: BEGIN_EXAMPLE("t_json_generator_bind_to_incore") + :end-before: END_EXAMPLE("t_json_generator_bind_to_incore") :language: cpp :dedent: 4 -.. literalinclude:: t_conduit_docs_tutorial_json_out.txt - :lines: 38-59 +.. literalinclude:: t_conduit_docs_tutorial_parse_out.txt + :start-after: BEGIN_EXAMPLE("t_json_generator_bind_to_incore") + :end-before: END_EXAMPLE("t_json_generator_bind_to_incore") + Compacting Nodes @@ -146,13 +179,14 @@ Compacting Nodes .. # from t_conduit_docs_tutorial_json: json_generator_compact -.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_json.cpp - :lines: 123-172 +.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_parse.cpp + :start-after: BEGIN_EXAMPLE("t_json_generator_compact") + :end-before: END_EXAMPLE("t_json_generator_compact") :language: cpp :dedent: 4 -.. literalinclude:: t_conduit_docs_tutorial_json_out.txt - :lines: 101-132 - +.. literalinclude:: t_conduit_docs_tutorial_parse_out.txt + :start-after: BEGIN_EXAMPLE("t_json_generator_compact") + :end-before: END_EXAMPLE("t_json_generator_compact") diff --git a/src/docs/sphinx/tutorial_cpp_parse.rst b/src/docs/sphinx/tutorial_cpp_parse.rst new file mode 100644 index 000000000..319e31241 --- /dev/null +++ b/src/docs/sphinx/tutorial_cpp_parse.rst @@ -0,0 +1,192 @@ +.. ############################################################################ +.. # Copyright (c) 2014-2019, Lawrence Livermore National Security, LLC. +.. # +.. # Produced at the Lawrence Livermore National Laboratory +.. # +.. # LLNL-CODE-666778 +.. # +.. # All rights reserved. +.. # +.. # This file is part of Conduit. +.. # +.. # For details, see: http://software.llnl.gov/conduit/. +.. # +.. # Please also read conduit/LICENSE +.. # +.. # Redistribution and use in source and binary forms, with or without +.. # modification, are permitted provided that the following conditions are met: +.. # +.. # * Redistributions of source code must retain the above copyright notice, +.. # this list of conditions and the disclaimer below. +.. # +.. # * Redistributions in binary form must reproduce the above copyright notice, +.. # this list of conditions and the disclaimer (as noted below) in the +.. # documentation and/or other materials provided with the distribution. +.. # +.. # * Neither the name of the LLNS/LLNL nor the names of its contributors may +.. # be used to endorse or promote products derived from this software without +.. # specific prior written permission. +.. # +.. # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +.. # AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.. # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.. # ARE DISCLAIMED. IN NO EVENT SHALL LAWRENCE LIVERMORE NATIONAL SECURITY, +.. # LLC, THE U.S. DEPARTMENT OF ENERGY OR CONTRIBUTORS BE LIABLE FOR ANY +.. # DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.. # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.. # OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.. # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.. # STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING +.. # IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.. # POSSIBILITY OF SUCH DAMAGE. +.. # +.. ############################################################################ + +================================== +Reading YAML and JSON Strings +================================== + +Parsing text with *Node::parse()* +------------------------------------------------------ + +*Node::parse()* parses YAML and JSON strings into a *Node* tree. + +.. # from t_conduit_docs_tutorial_parse: t_conduit_docs_tutorial_yaml + +.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_parse.cpp + :start-after: BEGIN_EXAMPLE("t_conduit_docs_tutorial_yaml") + :end-before: END_EXAMPLE("t_conduit_docs_tutorial_yaml") + :language: cpp + :dedent: 4 + +.. literalinclude:: t_conduit_docs_tutorial_parse_out.txt + :start-after: BEGIN_EXAMPLE("t_conduit_docs_tutorial_yaml") + :end-before: END_EXAMPLE("t_conduit_docs_tutorial_yaml") + +.. # from t_conduit_docs_tutorial_parse: t_conduit_docs_tutorial_json + +.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_parse.cpp + :start-after: BEGIN_EXAMPLE("t_conduit_docs_tutorial_json") + :end-before: END_EXAMPLE("t_conduit_docs_tutorial_json") + :language: cpp + :dedent: 4 + +.. literalinclude:: t_conduit_docs_tutorial_parse_out.txt + :start-after: BEGIN_EXAMPLE("t_conduit_docs_tutorial_json") + :end-before: END_EXAMPLE("t_conduit_docs_tutorial_json") + +The first argument is the string to parse and the second argument +selects the protocol to use when parsing. + +Valid Protocols: ``json``, ``conduit_json``, ``conduit_base64_json``, ``yaml``. + +* ``json`` and ``yaml`` protocols parse pure JSON or YAML strings. For leaf + nodes wide types such as *int64*, *uint64*, and *float64* are inferred. + + +Homogeneous numeric lists are parsed as Conduit arrays. + +.. # from t_conduit_docs_tutorial_parse: t_conduit_docs_tutorial_yaml_inline_array + +.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_parse.cpp + :start-after: BEGIN_EXAMPLE("t_conduit_docs_tutorial_yaml_inline_array") + :end-before: END_EXAMPLE("t_conduit_docs_tutorial_yaml_inline_array") + :language: cpp + :dedent: 4 + +.. literalinclude:: t_conduit_docs_tutorial_parse_out.txt + :start-after: BEGIN_EXAMPLE("t_conduit_docs_tutorial_yaml_inline_array") + :end-before: END_EXAMPLE("t_conduit_docs_tutorial_yaml_inline_array") + +* ``conduit_json`` parses JSON with conduit data type information, allowing you + to specify bitwidth style types, strides, etc. + +* ``conduit_base64_json`` combines the *conduit_json* protocol with an embedded + base64-encoded data block + +====================== +Generators +====================== + +Using *Generator* instances +--------------------------------------------------- +Node::parse() is sufficient for most use cases, but you can also use a *Generator* +instance to parse JSON and YAML. Additionally, Generators can parse a +conduit JSON schema and bind it to in-core data. + +.. # from t_conduit_docs_tutorial_json: json_generator_std + +.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_parse.cpp + :start-after: BEGIN_EXAMPLE("t_json_generator_std") + :end-before: END_EXAMPLE("t_json_generator_std") + :language: cpp + :dedent: 4 + +.. literalinclude:: t_conduit_docs_tutorial_parse_out.txt + :start-after: BEGIN_EXAMPLE("t_json_generator_std") + :end-before: END_EXAMPLE("t_json_generator_std") + + +Like *Node::parse()*, *Generators* can also parse pure JSON or YAML. +For leaf nodes: wide types such as *int64*, *uint64*, and *float64* are inferred. + +.. # from t_conduit_docs_tutorial_json: json_generator_pure_json + +.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_parse.cpp + :start-after: BEGIN_EXAMPLE("t_json_generator_pure_json") + :end-before: END_EXAMPLE("t_json_generator_pure_json") + :language: cpp + :dedent: 4 + +.. literalinclude:: t_conduit_docs_tutorial_parse_out.txt + :start-after: BEGIN_EXAMPLE("t_json_generator_pure_json") + :end-before: END_EXAMPLE("t_json_generator_pure_json") + +.. # from t_conduit_docs_tutorial_json: json_generator_pure_yaml + +.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_parse.cpp + :start-after: BEGIN_EXAMPLE("t_json_generator_pure_yaml") + :end-before: END_EXAMPLE("t_json_generator_pure_yaml") + :language: cpp + :dedent: 4 + +.. literalinclude:: t_conduit_docs_tutorial_parse_out.txt + :start-after: BEGIN_EXAMPLE("t_json_generator_pure_yaml") + :end-before: END_EXAMPLE("t_json_generator_pure_yaml") + + + +Schemas can be bound to in-core data. + +.. # from t_conduit_docs_tutorial_json: json_generator_bind_to_incore + +.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_parse.cpp + :start-after: BEGIN_EXAMPLE("t_json_generator_bind_to_incore") + :end-before: END_EXAMPLE("t_json_generator_bind_to_incore") + :language: cpp + :dedent: 4 + +.. literalinclude:: t_conduit_docs_tutorial_parse_out.txt + :start-after: BEGIN_EXAMPLE("t_json_generator_bind_to_incore") + :end-before: END_EXAMPLE("t_json_generator_bind_to_incore") + + + +Compacting Nodes +-------------------------------- + +*Nodes* can be compacted to transform sparse data. + +.. # from t_conduit_docs_tutorial_json: json_generator_compact + +.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_parse.cpp + :start-after: BEGIN_EXAMPLE("t_json_generator_compact") + :end-before: END_EXAMPLE("t_json_generator_compact") + :language: cpp + :dedent: 4 + +.. literalinclude:: t_conduit_docs_tutorial_parse_out.txt + :start-after: BEGIN_EXAMPLE("t_json_generator_compact") + :end-before: END_EXAMPLE("t_json_generator_compact") + + diff --git a/src/docs/sphinx/tutorial_python.rst b/src/docs/sphinx/tutorial_python.rst index c3b5d4ff7..406f252e4 100644 --- a/src/docs/sphinx/tutorial_python.rst +++ b/src/docs/sphinx/tutorial_python.rst @@ -53,5 +53,5 @@ of examples for Conduit's Core API and additional libraries. .. toctree:: tutorial_python_basics - tutorial_python_json + tutorial_python_parse diff --git a/src/docs/sphinx/tutorial_python_json.rst b/src/docs/sphinx/tutorial_python_json.rst deleted file mode 100644 index e6d9e55e6..000000000 --- a/src/docs/sphinx/tutorial_python_json.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. ############################################################################ -.. # Copyright (c) 2014-2019, Lawrence Livermore National Security, LLC. -.. # -.. # Produced at the Lawrence Livermore National Laboratory -.. # -.. # LLNL-CODE-666778 -.. # -.. # All rights reserved. -.. # -.. # This file is part of Conduit. -.. # -.. # For details, see: http://software.llnl.gov/conduit/. -.. # -.. # Please also read conduit/LICENSE -.. # -.. # Redistribution and use in source and binary forms, with or without -.. # modification, are permitted provided that the following conditions are met: -.. # -.. # * Redistributions of source code must retain the above copyright notice, -.. # this list of conditions and the disclaimer below. -.. # -.. # * Redistributions in binary form must reproduce the above copyright notice, -.. # this list of conditions and the disclaimer (as noted below) in the -.. # documentation and/or other materials provided with the distribution. -.. # -.. # * Neither the name of the LLNS/LLNL nor the names of its contributors may -.. # be used to endorse or promote products derived from this software without -.. # specific prior written permission. -.. # -.. # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -.. # AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.. # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.. # ARE DISCLAIMED. IN NO EVENT SHALL LAWRENCE LIVERMORE NATIONAL SECURITY, -.. # LLC, THE U.S. DEPARTMENT OF ENERGY OR CONTRIBUTORS BE LIABLE FOR ANY -.. # DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.. # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.. # OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.. # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, -.. # STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING -.. # IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE -.. # POSSIBILITY OF SUCH DAMAGE. -.. # -.. ############################################################################ - -====================== -Generators -====================== - - -Using *Generator* instances to parse JSON schemas ---------------------------------------------------- - -The *Generator* class is used to parse conduit JSON schemas into a *Node*. - - -.. # from t_conduit_docs_tutorial_python_json: json_generator_std - -.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_python_json.py - :lines: 62-67 - :language: python - :dedent: 8 - -.. literalinclude:: t_conduit_docs_python_tutorial_json_out.txt - :lines: 29-32 - :dedent: 4 - - -The *Generator* can also parse pure json. For leaf nodes: wide types such as *int64*, *uint64*, and *float64* are inferred. - -.. # from t_conduit_docs_tutorial_python_json: json_generator_pure_json - -.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_python_json.py - :lines: 74-79 - :language: python - :dedent: 8 - -.. literalinclude:: t_conduit_docs_python_tutorial_json_out.txt - :lines: 37-42 - :dedent: 4 - - -.. # TODO, analog to C++ Compacting Nodes diff --git a/src/docs/sphinx/tutorial_python_parse.rst b/src/docs/sphinx/tutorial_python_parse.rst new file mode 100644 index 000000000..df6180729 --- /dev/null +++ b/src/docs/sphinx/tutorial_python_parse.rst @@ -0,0 +1,190 @@ +.. ############################################################################ +.. # Copyright (c) 2014-2019, Lawrence Livermore National Security, LLC. +.. # +.. # Produced at the Lawrence Livermore National Laboratory +.. # +.. # LLNL-CODE-666778 +.. # +.. # All rights reserved. +.. # +.. # This file is part of Conduit. +.. # +.. # For details, see: http://software.llnl.gov/conduit/. +.. # +.. # Please also read conduit/LICENSE +.. # +.. # Redistribution and use in source and binary forms, with or without +.. # modification, are permitted provided that the following conditions are met: +.. # +.. # * Redistributions of source code must retain the above copyright notice, +.. # this list of conditions and the disclaimer below. +.. # +.. # * Redistributions in binary form must reproduce the above copyright notice, +.. # this list of conditions and the disclaimer (as noted below) in the +.. # documentation and/or other materials provided with the distribution. +.. # +.. # * Neither the name of the LLNS/LLNL nor the names of its contributors may +.. # be used to endorse or promote products derived from this software without +.. # specific prior written permission. +.. # +.. # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +.. # AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.. # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.. # ARE DISCLAIMED. IN NO EVENT SHALL LAWRENCE LIVERMORE NATIONAL SECURITY, +.. # LLC, THE U.S. DEPARTMENT OF ENERGY OR CONTRIBUTORS BE LIABLE FOR ANY +.. # DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.. # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.. # OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.. # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.. # STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING +.. # IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.. # POSSIBILITY OF SUCH DAMAGE. +.. # +.. ############################################################################ + +================================== +Reading YAML and JSON Strings +================================== + +Parsing text with *Node::parse()* +------------------------------------------------------ + +*Node.parse()* parses YAML and JSON strings into a *Node* tree. + +.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_python_parse.py + :start-after: BEGIN_EXAMPLE("t_py_conduit_docs_tutorial_yaml") + :end-before: END_EXAMPLE("t_py_conduit_docs_tutorial_yaml") + :language: python + :dedent: 8 + +.. literalinclude:: t_conduit_docs_python_tutorial_parse_out.txt + :start-after: BEGIN_EXAMPLE("t_py_conduit_docs_tutorial_yaml") + :end-before: END_EXAMPLE("t_py_conduit_docs_tutorial_yaml") + :dedent: 4 + +.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_python_parse.py + :start-after: BEGIN_EXAMPLE("t_py_conduit_docs_tutorial_json") + :end-before: END_EXAMPLE("t_py_conduit_docs_tutorial_json") + :language: python + :dedent: 8 + +.. literalinclude:: t_conduit_docs_python_tutorial_parse_out.txt + :start-after: BEGIN_EXAMPLE("t_py_conduit_docs_tutorial_json") + :end-before: END_EXAMPLE("t_py_conduit_docs_tutorial_json") + :dedent: 4 + +The first argument is the string to parse and the second argument +selects the protocol to use when parsing. + +Valid Protocols: ``json``, ``conduit_json``, ``conduit_base64_json``, ``yaml``. + +* ``json`` and ``yaml`` protocols parse pure JSON or YAML strings. For leaf + nodes wide types such as *int64*, *uint64*, and *float64* are inferred. + + +Homogeneous numeric lists are parsed as Conduit arrays. + +.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_python_parse.py + :start-after: BEGIN_EXAMPLE("t_py_conduit_docs_tutorial_yaml_inline_array") + :end-before: END_EXAMPLE("t_py_conduit_docs_tutorial_yaml_inline_array") + :language: python + :dedent: 8 + +.. literalinclude:: t_conduit_docs_python_tutorial_parse_out.txt + :start-after: BEGIN_EXAMPLE("t_py_conduit_docs_tutorial_yaml_inline_array") + :end-before: END_EXAMPLE("t_py_conduit_docs_tutorial_yaml_inline_array") + :dedent: 4 + +* ``conduit_json`` parses JSON with conduit data type information, allowing you + to specify bitwidth style types, strides, etc. + +* ``conduit_base64_json`` combines the *conduit_json* protocol with an embedded + base64-encoded data block + +====================== +Generators +====================== + +Using *Generator* instances +--------------------------------------------------- +Node.parse() is sufficient for most use cases, but you can also use a *Generator* +instance to parse JSON and YAML. Additionally, Generators can parse a +conduit JSON schema and bind it to in-core data. + +.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_python_parse.py + :start-after: BEGIN_EXAMPLE("t_py_json_generator_std") + :end-before: END_EXAMPLE("t_py_json_generator_std") + :language: python + :dedent: 8 + +.. literalinclude:: t_conduit_docs_python_tutorial_parse_out.txt + :start-after: BEGIN_EXAMPLE("t_py_json_generator_std") + :end-before: END_EXAMPLE("t_py_json_generator_std") + :dedent: 4 + +Like *Node::parse()*, *Generators* can also parse pure JSON or YAML. +For leaf nodes: wide types such as *int64*, *uint64*, and *float64* are inferred. + + +.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_python_parse.py + :start-after: BEGIN_EXAMPLE("t_py_json_generator_pure_json") + :end-before: END_EXAMPLE("t_py_json_generator_pure_json") + :language: python + :dedent: 8 + +.. literalinclude:: t_conduit_docs_tutorial_parse_out.txt + :start-after: BEGIN_EXAMPLE("t_py_json_generator_pure_json") + :end-before: END_EXAMPLE("t_py_json_generator_pure_json") + :dedent: 4 + +.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_python_parse.py + :start-after: BEGIN_EXAMPLE("t_py_json_generator_pure_yaml") + :end-before: END_EXAMPLE("t_py_json_generator_pure_yaml") + :language: python + :dedent: 8 + +.. literalinclude:: t_conduit_docs_python_tutorial_parse_out.txt + :start-after: BEGIN_EXAMPLE("t_py_json_generator_pure_yaml") + :end-before: END_EXAMPLE("t_py_json_generator_pure_yaml") + :dedent: 4 + +.. ====================== +.. Generators +.. ====================== +.. +.. +.. Using *Generator* instances to parse JSON schemas +.. --------------------------------------------------- +.. +.. The *Generator* class is used to parse conduit JSON schemas into a *Node*. +.. +.. +.. .. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_python_parse.py +.. :start-after: BEGIN_EXAMPLE("t_py_json_generator_std") +.. :end-before: END_EXAMPLE("t_py_json_generator_std") +.. :language: python +.. :dedent: 8 +.. +.. .. literalinclude:: t_conduit_docs_python_tutorial_parse_out.txt +.. :start-after: BEGIN_EXAMPLE("t_py_json_generator_std") +.. :end-before: END_EXAMPLE("t_py_json_generator_std") +.. :dedent: 4 +.. +.. +.. The *Generator* can also parse pure json. For leaf nodes: wide types such as *int64*, *uint64*, and *float64* are inferred. +.. +.. .. # from t_conduit_docs_tutorial_python_json: json_generator_pure_json +.. +.. .. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_python_parse.py +.. :start-after: BEGIN_EXAMPLE("t_py_json_generator_pure_json") +.. :end-before: END_EXAMPLE("t_py_json_generator_pure_json") +.. :language: python +.. :dedent: 8 +.. +.. .. literalinclude:: t_conduit_docs_python_tutorial_parse_out.txt +.. :start-after: BEGIN_EXAMPLE("t_py_json_generator_pure_json") +.. :end-before: END_EXAMPLE("t_py_json_generator_pure_json") +.. :dedent: 4 + + +.. # TODO, analog to C++ Compacting Nodes diff --git a/src/tests/docs/CMakeLists.txt b/src/tests/docs/CMakeLists.txt index 6afa9725e..67dec7007 100644 --- a/src/tests/docs/CMakeLists.txt +++ b/src/tests/docs/CMakeLists.txt @@ -53,7 +53,6 @@ set(DOCS_TESTS t_conduit_docs_tutorial_basics t_conduit_docs_tutorial_numeric t_conduit_docs_tutorial_parse - t_conduit_docs_tutorial_json t_conduit_docs_tutorial_ownership t_conduit_docs_tutorial_errors t_conduit_docs_relay_io_generic_examples @@ -68,7 +67,7 @@ set(DOCS_HDF5_TESTS set(DOCS_PYTHON_TESTS t_conduit_docs_tutorial_python_basics t_conduit_docs_tutorial_python_numeric - t_conduit_docs_tutorial_python_json + t_conduit_docs_tutorial_python_parse t_conduit_docs_tutorial_python_ownership t_conduit_docs_tutorial_python_relay_io_handle_examples) diff --git a/src/tests/docs/t_conduit_docs_tutorial_json.cpp b/src/tests/docs/t_conduit_docs_tutorial_json.cpp deleted file mode 100644 index 64c389eba..000000000 --- a/src/tests/docs/t_conduit_docs_tutorial_json.cpp +++ /dev/null @@ -1,174 +0,0 @@ -//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~// -// Copyright (c) 2014-2019, Lawrence Livermore National Security, LLC. -// -// Produced at the Lawrence Livermore National Laboratory -// -// LLNL-CODE-666778 -// -// All rights reserved. -// -// This file is part of Conduit. -// -// For details, see: http://software.llnl.gov/conduit/. -// -// Please also read conduit/LICENSE -// -// Redistribution and use in source and binary forms, with or without -// modification, are permitted provided that the following conditions are met: -// -// * Redistributions of source code must retain the above copyright notice, -// this list of conditions and the disclaimer below. -// -// * Redistributions in binary form must reproduce the above copyright notice, -// this list of conditions and the disclaimer (as noted below) in the -// documentation and/or other materials provided with the distribution. -// -// * Neither the name of the LLNS/LLNL nor the names of its contributors may -// be used to endorse or promote products derived from this software without -// specific prior written permission. -// -// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -// ARE DISCLAIMED. IN NO EVENT SHALL LAWRENCE LIVERMORE NATIONAL SECURITY, -// LLC, THE U.S. DEPARTMENT OF ENERGY OR CONTRIBUTORS BE LIABLE FOR ANY -// DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -// DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -// OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -// HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, -// STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING -// IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE -// POSSIBILITY OF SUCH DAMAGE. -// -//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~// - -//----------------------------------------------------------------------------- -/// -/// file: t_conduit_docs_tutorial_json.cpp -/// -//----------------------------------------------------------------------------- - -#include "conduit.hpp" -#include "conduit_blueprint.hpp" -#include "conduit_relay.hpp" - -#include -#include "gtest/gtest.h" -using namespace conduit; - -//----------------------------------------------------------------------------- -TEST(conduit_tutorial, json_generator_std) -{ - CONDUIT_INFO("json_generator_std"); - - Generator g("{test: {dtype: float64, value: 100.0}}","conduit_json"); - - Node n; - g.walk(n); - - std::cout << n["test"].as_float64() <