Groonga組み込みコマンドを実行するC-API

# Groonga組み込みコマンドの実行

※組み込みコマンドを使う視点で説明を書いています。

 [use_grn_expr_exec.c](https://gist.github.com/Yujiro3/48e353aa41938663fc68 "use_grn_expr_exec.c")

## grn_ctx_get

組み込みコマンドを取得するために呼び出します。

```c
grn_obj *grn_ctx_get(grn_ctx *ctx, const char *name, int name_size);
```

**引数**

| 名前        | 型            | 概要             |
|:-----------:|:-------------:|:----------------:|
| ctx         |  grn_ctx *    | コンテキスト     |
| name        |  const char * | コマンド名       |
| name_size   |  int          | コマンド文字列長 |


**戻り値**

グルンコマンドオブジェクト


```c
  grn_ctx ctx;

  /* Groongaの初期化 */
  grn_init();

  /* コンテキストの初期化 */
  grn_ctx_init(&ctx, 0);

  /* コマンドを取得 */
  table_create = grn_ctx_get(&ctx, "table_create", strlen("table_create"));
```



## grn_expr_get_var

組み込みコマンドの引数名を指定して引数を取得します。

```c
grn_obj *grn_expr_get_var(grn_ctx *ctx, grn_obj *expr,
                                  const char *name, unsigned int name_size);
```

**引数**

| 名前        | 型            | 概要                 |
|:-----------:|:-------------:|:--------------------:|
| ctx         |  grn_ctx *    | コンテキスト         |
| expr        |  grn_obj *    | コマンドオブジェクト |
| name        |  const char * | 引数名               |
| name_size   |  int          | 引数文字列長         |


**戻り値**

グルン引数オブジェクト


```c

  /* コマンドを取得 */
  grn_obj *truncate = grn_ctx_get(&ctx, "truncate", strlen("truncate"));

  /* 引数を取得して値を設定 */
  grn_obj *table = grn_expr_get_var(&ctx, command, "table", strlen("table"));


  /* 引数の中身を設定 */
  GRN_TEXT_PUTS(&ctx, table, "Users");
```





## grn_expr_get_var_by_offset

組み込みコマンドの引数をOffsetにより指定して取得します。

```c
grn_obj *grn_expr_get_var_by_offset(grn_ctx *ctx, grn_obj *expr, unsigned int offset);
```

**引数**

| 名前        | 型            | 概要                 |
|:-----------:|:-------------:|:--------------------:|
| ctx         |  grn_ctx *    | コンテキスト         |
| expr        |  grn_obj *    | コマンドオブジェクト |
| offset      |  unsigned int | 引数の順番           |


**戻り値**

グルン引数オブジェクト


```c

  /* コマンドを取得 */
  grn_obj *truncate = grn_ctx_get(&ctx, "truncate", strlen("truncate"));

  /* Offsetから引数を取得して値を設定 */
  grn_obj *table = grn_expr_get_var_by_offset(&ctx, truncate, 0);

  /* 引数の中身を設定 */
  GRN_TEXT_PUTS(&ctx, table, "Users");
```




## grn_expr_exec

指定した組み込みコマンドを実行します。

```c
grn_obj *grn_expr_exec(grn_ctx *ctx, grn_obj *expr, int nargs);
```

**引数**

| 名前        | 型            | 概要                 |
|:-----------:|:-------------:|:--------------------:|
| ctx         |  grn_ctx *    | コンテキスト         |
| expr        |  grn_obj *    | コマンドオブジェクト |
| nargs       |  int          |                      |


**戻り値**

グルンオブジェクト


```c
  grn_ctx ctx;

  /* Groongaの初期化 */
  grn_init();

  /* コンテキストの初期化 */
  grn_ctx_init(&ctx, 0);

  /* コマンドを取得 */
  grn_obj *status = grn_ctx_get(ctx, "status", strlen("status"));

  /* コマンドの実行*/
  grn_expr_exec(ctx, status, 0);
```




## grn_ctx_set_output_type

実行結果などのフォーマットタイプを設定します。

```c
grn_content_type grn_ctx_get_output_type(grn_ctx *ctx);
grn_rc grn_ctx_set_output_type(grn_ctx *ctx, grn_content_type type);
```

**引数**

| 名前        | 型                | 概要                   |
|:-----------:|:-----------------:|:----------------------:|
| ctx         |  grn_ctx *        | コンテキスト           |
| type        |  grn_content_type | コンテンツフォーマット |


**戻り値**

結果セット


**コンテンツタイプ**

| 定数             | 概要      |
|:----------------:|:---------:|
| GRN_CONTENT_TSV  | TSV形式   |
| GRN_CONTENT_JSON | JSON形式  |
| GRN_CONTENT_XML  | XML形式   |


```c
  grn_ctx ctx;

  /* Groongaの初期化 */
  grn_init();

  /* コンテキストの初期化 */
  grn_ctx_init(&ctx, 0);


  /* 出力タイプの設定 */
  grn_ctx_set_output_type(&ctx, GRN_CONTENT_JSON);
```






## grn_expr_clear_vars

引数の値を除去します。

```c
grn_rc grn_expr_clear_vars(grn_ctx *ctx, grn_obj *expr);
```

**引数**

| 名前        | 型            | 概要                 |
|:-----------:|:-------------:|:--------------------:|
| ctx         |  grn_ctx *    | コンテキスト         |
| expr        |  grn_obj *    | コマンドオブジェクト |


**戻り値**

結果セット



```c
    /* コマンドを取得 */
    grn_obj *table_create = grn_ctx_get(&ctx, "table_create", strlen("table_create"));

    /* 引数の取得 */
    grn_obj *name = grn_expr_get_var(&ctx, table_create, "name", strlen("name"));
    grn_obj *flags = grn_expr_get_var(&ctx, table_create , "flags", strlen("flags"));
    grn_obj *key_type = grn_expr_get_var(&ctx, table_create , "key_type", strlen("key_type"));


    /* 引数の設定 */
    GRN_TEXT_PUTS(&ctx, name, "Users");
    GRN_TEXT_PUTS(&ctx, flags, "TABLE_HASH_KEY");
    GRN_TEXT_PUTS(&ctx, key_type, "ShortText");

    /* コマンドの実行 */
    grn_expr_exec(&ctx, table_create, 0);


    /* 引数のリセット */
    grn_expr_clear_vars(&ctx, table_create);

    /* 引数の取得 */
    name = grn_expr_get_var(&ctx, table_create, "name", strlen("name"));
    flags = grn_expr_get_var(&ctx, table_create , "flags", strlen("flags"));
    key_type = grn_expr_get_var(&ctx, table_create , "key_type", strlen("key_type"));


    /* 引数の設定 */
    GRN_TEXT_PUTS(&ctx, name, "Comments");
    GRN_TEXT_PUTS(&ctx, flags, "TABLE_HASH_KEY");
    GRN_TEXT_PUTS(&ctx, key_type, "ShortText");

    /* コマンドの実行 */
    grn_expr_exec(&ctx, table_create, 0);
```





## grn_ctx_info_get

コンテキスト内に格納された情報を取得します。

```c
grn_rc grn_ctx_info_get(grn_ctx *ctx, grn_ctx_info *info);
```

**引数**

| 名前        | 型              | 概要                         |
|:-----------:|:---------------:|:----------------------------:|
| ctx         |  grn_ctx *      | コンテキスト                 |
| info        |  grn_ctx_info * | コンテキスト情報オブジェクト |


**戻り値**

結果セット



```c
  grn_ctx_info info;


  /* コマンドを取得 */
  grn_obj *status = grn_ctx_get(ctx, "status", strlen("status"));

  /* コマンドの実行*/
  grn_expr_exec(&ctx, status, 0);


  /* コマンド結果の取得 */
  grn_ctx_info_get(&ctx, &info);
  printf("%.*s\n", (int)GRN_TEXT_LEN(info.outbuf), GRN_TEXT_VALUE(info.outbuf));
```



## grn_ctx_recv

結果内容の取得

```c
unsigned int grn_ctx_recv(grn_ctx *ctx, char **str, unsigned int *str_len, int *flags);
```

**引数**

| 名前        | 型              | 概要                         |
|:-----------:|:---------------:|:----------------------------:|
| ctx         |  grn_ctx *      | コンテキスト                 |
| str         |  char **        | 結果内容                     |
| str_len     |  unsigned int * | 結果内容文字列長             |
| flags       |  int *          | フラグ                       |

**戻り値**

結果



```c
  /* コマンドを取得 */
  grn_obj *status = grn_ctx_get(ctx, "status", strlen("status"));

  /* コマンドの実行*/
  grn_expr_exec(&ctx, status, 0);

  {
    /* 結果の取得 */
    char *result;
    unsigned int result_length;
    int recv_flags;

    grn_ctx_recv(&ctx, &result, &result_length, &recv_flags);
    printf("%.*s\n", result_length, result);
  }
```


## サンプルコード

 [use_grn_expr_exec.c](https://gist.github.com/Yujiro3/48e353aa41938663fc68 "use_grn_expr_exec.c")