feat: modernize API

docs/src/man/examples.md

@@ -17,31 +17,31 @@ using DataFrames
 ```
 
 ```@example examples
-output = KEGGAPI.conv("eco", "ncbi-geneid"); 
+output = KEGGAPI.kegg_conv("eco", "ncbi-geneid"); 
 first(DataFrame(
   output.data,
   output.colnames
 ), 5)
 ```
 
 ```@example examples
-output = KEGGAPI.conv("ncbi-geneid", "eco");
+output = KEGGAPI.kegg_conv("ncbi-geneid", "eco");
 first(DataFrame(
   output.data,
   output.colnames
 ), 5)
 ```
 
 ```@example examples
-output = KEGGAPI.conv("ncbi-proteinid", "hsa:10458+ece:Z5100");
+output = KEGGAPI.kegg_conv("ncbi-proteinid", "hsa:10458+ece:Z5100");
 DataFrame(
   output.data,
   output.colnames
 )
 ```
 
 ```@example examples
-output = KEGGAPI.conv("genes", "ncbi-geneid:948364");
+output = KEGGAPI.kegg_conv("genes", "ncbi-geneid:948364");
 DataFrame(
   output.data,
   output.colnames

docs/src/man/getting-started.md

@@ -19,7 +19,7 @@ using KEGGAPI
 
 And use the interfaces to query the KEGG API. For example, to list all organisms in KEGG:
 ```@example examples
-result = KEGGAPI.list("organism");
+result = KEGGAPI.kegg_list("organism");
 ```
 This returns a `KeggOrganismList` object with the API call, column names and data. The data can
 accessed by indexing into the respective fields of the object:

src/Conv.jl

@@ -1,28 +1,81 @@
 """
-KEGGAPI.conv(<target_db>, <source_db>)
+    kegg_conv(target_db::String, source_db::String)
 
 Convert KEGG identifiers to/from outside identifiers.
 
-Example:
+# Arguments
+- `target_db::String`: Target database
+- `source_db::String`: Source database
 
-```@example
+# Examples
+```julia
 using KEGGAPI
+
 KEGGAPI.conv("eco", "ncbi-geneid")
 KEGGAPI.conv("ncbi-geneid", "eco")
-KEGGAPI.conv("ncbi-proteinid", "hsa:10458+ece:Z5100")
 KEGGAPI.conv("genes", "ncbi-geneid:948364")
 ```
+
+# Extended help
+
+This operation can be used to convert entry identifiers (accession numbers) of outside databases
+to KEGG identifiers, and vice versa. The first form allows database to database mapping, while
+the second form allows conversion of a selected number of entries. The database name "genes" may
+be used only in the second form.
+
+## References
+
+- [KEGG API](https://www.kegg.jp/kegg/rest/keggapi.html#conv)
+
 """
-function conv(target_db::String, source_db::String)
-    # This function retrieves a list of entries from a specific database from the KEGG API.
-    # Define the URL for the API request.
+function kegg_conv(target_db::String, source_db::String)
     url = "https://rest.kegg.jp/conv/$target_db/$source_db"
     response_text = request(url)
-    kegg_data =
-        conv_parser(
-        response_text,
-        url
-    )
-    # return the arrays
+    kegg_data = conv_parser(response_text, url)
     return kegg_data
 end
+
+
+"""
+    kegg_conv(target_db::String, dbentries::Vector{String}; [timeout::Float64 = 0.4])
+
+Convert KEGG identifiers to/from outside identifiers.
+
+For gene identifiers:
+
+    <dbentries> = database entries of the following <database>
+    <database>  = <org> | genes | ncbi-geneid | ncbi-proteinid | uniprot
+    <org>       = KEGG organism code or T number
+
+For chemical substance identifiers:
+
+    <dbentries> = database entries of the following <database>
+    <database>  = compound | glycan | drug | pubchem | chebi
+
+# Arguments
+- `target_db::String`: Target database
+- `dbentries::Vector{String}`: Database entries of the available databases
+- `timeout::Float64`: Time to wait between requests (default: 0.4 seconds)
+
+# Examples
+```julia
+using KEGGAPI
+
+KEGGAPI.conv("ncbi-proteinid", ["hsa:10458", "ece:Z5100"])
+```
+"""
+function kegg_conv(target_db::String, dbentries::Vector{String}; timeout::Float64 = 0.4)
+    urls = String[]
+    data = []
+    for chunk in chunk_vector(dbentries, 10)
+        url = "https://rest.kegg.jp/conv/$(target_db)/$(join(chunk, "+"))"
+        push!(urls, url)
+        response_text = request(url)
+        for datum in eachline(IOBuffer(response_text))
+            id, d = split(datum, '\t') .|> String
+            push!(data, [id, d])
+        end
+        sleep(timeout)
+    end
+    return KeggTupleList(urls, ["source", target_db], data)
+end

src/Find.jl

@@ -8,7 +8,7 @@ using KEGGAPI
 KEGGAPI.find("compound","glucose")
 ```
 """
-function find(database::String, query::String, option::String = "")
+function kegg_find(database::String, query::String, option::String = "")
     # This function retrieves a list of entries from a specific database from the KEGG API.
     query = replace(query, " " => "+")
     # Check if the requested database is a "pathway" database