forks/erlang-sqlite3
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improved documentation

Browse Source
This commit is contained in:
Alexey Romanov
2010-11-18 14:31:33 +03:00
parent 466e0332f4
commit baa51b0c68
1 changed files with 35 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
src/sqlite3.erl
View File

@@ -43,15 +43,11 @@
%%-------------------------------------------------------------------- %%--------------------------------------------------------------------
%% @spec start_link(Db :: atom()) -> {ok, Pid :: pid()} | ignore | {error, Error} %% @spec start_link(Db :: atom()) -> {ok, Pid :: pid()} | ignore | {error, Error}
%% @doc %% @doc
%% Opens a sqlite3 dbase creating one if necessary. The dbase must %% Opens the sqlite3 database in file Db.db in the working directory
%% be called Db.db in the current path. start_link/1 can be use %% (creating this file if necessary). This is the same as open/1.
%% with stop/0, sql_exec/1, create_table/2, list_tables/0,
%% table_info/1, write/2, read/2, delete/2 and drop_table/1.
%% There can be only one start_link call per node.
%%
%% To open multiple dbases on the same node use open/1 or open/2.
%% @end %% @end
%%-------------------------------------------------------------------- %%--------------------------------------------------------------------
-type option() :: {file, string()} | temporary | in_memory.
-type result() :: {'ok', pid()} | 'ignore' | {'error', any()}. -type result() :: {'ok', pid()} | 'ignore' | {'error', any()}.
-spec start_link(atom()) -> result(). -spec start_link(atom()) -> result().
@@ -62,29 +58,23 @@ start_link(Db) ->
%%-------------------------------------------------------------------- %%--------------------------------------------------------------------
%% @spec start_link(Db :: atom(), Options) -> {ok, Pid :: pid()} | ignore | {error, Error} %% @spec start_link(Db :: atom(), Options) -> {ok, Pid :: pid()} | ignore | {error, Error}
%% @doc %% @doc
%% Opens a sqlite3 dbase creating one if necessary. By default the %% Opens a sqlite3 database creating one if necessary. By default the
%% dbase will be called Db.db in the current path. This can be changed %% database will be called Db.db in the current path. This can be changed
%% by passing the option {db, DbFile :: String()}. DbFile must be the %% by passing the option {file, DbFile :: String()}. DbFile must be the
%% full path to the sqlite3 db file. start_link/1 can be use with stop/0, %% full path to the sqlite3 db file. start_link/1 can be use with stop/0,
%% sql_exec/1, create_table/2, list_tables/0, table_info/1, write/2, %% sql_exec/1, create_table/2, list_tables/0, table_info/1, write/2,
%% read/2, delete/2 and drop_table/1. There can be only one start_link %% read/2, delete/2 and drop_table/1. This is the same as open/2.
%% call per node.
%%
%% To open multiple dbases on the same node use open/1 or open/2.
%% @end %% @end
%%-------------------------------------------------------------------- %%--------------------------------------------------------------------
-spec start_link(atom(), [{atom(), any()}]) -> result(). -spec start_link(atom(), [option()]) -> result().
start_link(Db, Options) -> start_link(Db, Options) ->
open(Db, Options). open(Db, Options).
%%-------------------------------------------------------------------- %%--------------------------------------------------------------------
%% @spec open(Db :: atom()) -> {ok, Pid :: pid()} | ignore | {error, Error} %% @spec open(Db :: atom()) -> {ok, Pid :: pid()} | ignore | {error, Error}
%% @doc %% @doc
%% Opens a sqlite3 dbase creating one if necessary. The dbase must be %% Opens the sqlite3 database in file Db.db in the working directory
%% called Db.db in the current path. Can be use to open multiple sqlite3 %% (creating this file if necessary). This is the same as open/1.
%% dbases per node. Must be use in conjunction with stop/1, sql_exec/2,
%% create_table/3, list_tables/1, table_info/2, write/3, read/3, delete/3
%% and drop_table/2.
%% @end %% @end
%%-------------------------------------------------------------------- %%--------------------------------------------------------------------
-spec open(atom()) -> result(). -spec open(atom()) -> result().
@@ -92,20 +82,22 @@ open(Db) ->
open(Db, []). open(Db, []).
%%-------------------------------------------------------------------- %%--------------------------------------------------------------------
%% @spec open(Db :: atom(), Options :: [{atom(), any()}]) -> {ok, Pid :: pid()} | ignore | {error, Error} %% @spec open(Db :: atom(), Options :: [option()]) -> {ok, Pid :: pid()} | ignore | {error, Error}
%% @type option() = {file, DbFile :: string()} | in_memory | temporary
%%
%% @doc %% @doc
%% Opens a sqlite3 dbase creating one if necessary. By default the dbase %% Opens a sqlite3 database creating one if necessary. By default the database
%% will be called Db.db in the current path. This can be changed by %% will be called Db.db in the current path. This can be changed by
%% passing the option {db, DbFile :: String()}. DbFile must be the full %% passing the option {file, DbFile :: string()}. DbFile must be the full
%% path to the sqlite3 db file. Can be use to open multiple sqlite3 dbases %% path to the sqlite3 db file. Can be use to open multiple sqlite3 databases
%% per node. Must be use in conjunction with stop/1, sql_exec/2, %% per node. Must be use in conjunction with stop/1, sql_exec/2,
%% create_table/3, list_tables/1, table_info/2, write/3, read/3, delete/3 %% create_table/3, list_tables/1, table_info/2, write/3, read/3, delete/3
%% and drop_table/2. %% and drop_table/2.
%% @end %% @end
%%-------------------------------------------------------------------- %%--------------------------------------------------------------------
-spec open(atom(), [{atom(), any()}]) -> result(). -spec open(atom(), [option()]) -> result().
open(Db, Options) -> open(Db, Options) ->
Opts = case proplists:lookup(db, Options) of Opts = case proplists:lookup(file, Options) of
none -> none ->
DbName = case proplists:is_defined(temporary, Options) of DbName = case proplists:is_defined(temporary, Options) of
true -> true ->
@@ -118,8 +110,8 @@ open(Db, Options) ->
"./" ++ atom_to_list(Db) ++ ".db" "./" ++ atom_to_list(Db) ++ ".db"
end end
end, end,
[{db, DbName} | Options]; [{file, DbName} | Options];
{db, _} -> {file, _} ->
Options Options
end, end,
gen_server:start_link({local, Db}, ?MODULE, Opts, []). gen_server:start_link({local, Db}, ?MODULE, Opts, []).
@@ -127,7 +119,7 @@ open(Db, Options) ->
%%-------------------------------------------------------------------- %%--------------------------------------------------------------------
%% @spec close(Db :: atom()) -> ok %% @spec close(Db :: atom()) -> ok
%% @doc %% @doc
%% Closes the Db sqlite3 dbase. %% Closes the Db sqlite3 database.
%% @end %% @end
%%-------------------------------------------------------------------- %%--------------------------------------------------------------------
-spec close(atom()) -> 'ok'. -spec close(atom()) -> 'ok'.
@@ -137,7 +129,7 @@ close(Db) ->
%%-------------------------------------------------------------------- %%--------------------------------------------------------------------
%% @spec stop() -> ok %% @spec stop() -> ok
%% @doc %% @doc
%% Closes the sqlite3 dbase. %% Closes the sqlite3 database.
%% @end %% @end
%%-------------------------------------------------------------------- %%--------------------------------------------------------------------
-spec stop() -> 'ok'. -spec stop() -> 'ok'.
@@ -157,7 +149,7 @@ sql_exec(SQL) ->
%%-------------------------------------------------------------------- %%--------------------------------------------------------------------
%% @spec sql_exec(Db :: atom(), Sql :: iodata()) -> any() %% @spec sql_exec(Db :: atom(), Sql :: iodata()) -> any()
%% @doc %% @doc
%% Executes the Sql statement directly on the Db dbase. Returns the %% Executes the Sql statement directly on the Db database. Returns the
%% result of the Sql call. %% result of the Sql call.
%% @end %% @end
%%-------------------------------------------------------------------- %%--------------------------------------------------------------------
@@ -267,7 +259,7 @@ write(Tbl, Data) ->
%% @spec write(Db :: atom(), Tbl :: atom(), Data) -> term() %% @spec write(Db :: atom(), Tbl :: atom(), Data) -> term()
%% Data = [{Column :: atom(), Value :: sql_value()}] %% Data = [{Column :: atom(), Value :: sql_value()}]
%% @doc %% @doc
%% Write Data into Tbl table in Db dbase. Value must be of the %% Write Data into Tbl table in Db database. Value must be of the
%% same type as determined from table_info/3. %% same type as determined from table_info/3.
%% @end %% @end
%%-------------------------------------------------------------------- %%--------------------------------------------------------------------
@@ -321,7 +313,7 @@ update(Tbl, Key, Value, Data) ->
%% Result = {ok, ID} | Unknown %% Result = {ok, ID} | Unknown
%% Unknown = term() %% Unknown = term()
%% @doc %% @doc
%% Updates rows into Tbl table in Db dbase such that the Value %% Updates rows into Tbl table in Db database such that the Value
%% matches the value in Key with Data. Returns ID of the first %% matches the value in Key with Data. Returns ID of the first
%% updated record. %% updated record.
%% @end %% @end
@@ -340,7 +332,7 @@ read_all(Db, Tbl) ->
gen_server:call(Db, {read, Tbl}). gen_server:call(Db, {read, Tbl}).
%%-------------------------------------------------------------------- %%--------------------------------------------------------------------
%% @spec read(Db :: atom(), Table :: atom(), Columns :: [atom()]) -> any() %% @spec read_all(Db :: atom(), Table :: atom(), Columns :: [atom()]) -> any()
%% @doc %% @doc
%% Reads Columns in all rows from Table in Db. %% Reads Columns in all rows from Table in Db.
%% @end %% @end
@@ -366,7 +358,7 @@ read(Tbl, Key) ->
%% @spec read(Db :: atom(), Tbl :: atom(), Key) -> [any()] %% @spec read(Db :: atom(), Tbl :: atom(), Key) -> [any()]
%% Key = {Column :: atom(), Value :: sql_value()} %% Key = {Column :: atom(), Value :: sql_value()}
%% @doc %% @doc
%% Reads a row from Tbl table in Db dbase such that the Value %% Reads a row from Tbl table in Db database such that the Value
%% matches the value in Column. ColValue must have the same type %% matches the value in Column. ColValue must have the same type
%% as determined from table_info/3. %% as determined from table_info/3.
%% @end %% @end
@@ -382,7 +374,7 @@ read(Db, Tbl, {Column, Value}) ->
%% Key = {Column :: atom(), Value :: sql_value()} %% Key = {Column :: atom(), Value :: sql_value()}
%% Columns = [atom()] %% Columns = [atom()]
%% @doc %% @doc
%% Reads a row from Tbl table in Db dbase such that the Value %% Reads a row from Tbl table in Db database such that the Value
%% matches the value in Column. Value must have the same type as %% matches the value in Column. Value must have the same type as
%% determined from table_info/3. %% determined from table_info/3.
%% @end %% @end
@@ -394,7 +386,7 @@ read(Db, Tbl, {Key, Value}, Columns) ->
%% @spec delete(Tbl :: atom(), Key) -> any() %% @spec delete(Tbl :: atom(), Key) -> any()
%% Key = {Column :: atom(), Value :: sql_value()} %% Key = {Column :: atom(), Value :: sql_value()}
%% @doc %% @doc
%% Delete a row from Tbl table in Db dbase such that the Value %% Delete a row from Tbl table in Db database such that the Value
%% matches the value in Column. %% matches the value in Column.
%% Value must have the same type as determined from table_info/3. %% Value must have the same type as determined from table_info/3.
%% @end %% @end
@@ -407,7 +399,7 @@ delete(Tbl, Key) ->
%% @spec delete(Db :: atom(), Tbl :: atom(), Key) -> any() %% @spec delete(Db :: atom(), Tbl :: atom(), Key) -> any()
%% Key = {Column :: atom(), Value :: sql_value()} %% Key = {Column :: atom(), Value :: sql_value()}
%% @doc %% @doc
%% Delete a row from Tbl table in Db dbase such that the Value %% Delete a row from Tbl table in Db database such that the Value
%% matches the value in Column. %% matches the value in Column.
%% Value must have the same type as determined from table_info/3. %% Value must have the same type as determined from table_info/3.
%% @end %% @end
@@ -429,7 +421,7 @@ drop_table(Tbl) ->
%%-------------------------------------------------------------------- %%--------------------------------------------------------------------
%% @spec drop_table(Db :: atom(), Tbl :: atom()) -> any() %% @spec drop_table(Db :: atom(), Tbl :: atom()) -> any()
%% @doc %% @doc
%% Drop the table Tbl from Db dbase. %% Drop the table Tbl from Db database.
%% @end %% @end
%%-------------------------------------------------------------------- %%--------------------------------------------------------------------
-spec drop_table(atom(), atom()) -> any(). -spec drop_table(atom(), atom()) -> any().
@@ -532,13 +524,11 @@ value_to_sql(X) -> sqlite3_lib:value_to_sql(X).
-spec init([any()]) -> {'ok', #state{}} | {'stop', string()}. -spec init([any()]) -> {'ok', #state{}} | {'stop', string()}.
init(Options) -> init(Options) ->
Dbase = proplists:get_value(db, Options), DbFile = proplists:get_value(file, Options),
io:format(user, "Dbase: ~p", [Dbase]),
PrivDir = get_priv_dir(), PrivDir = get_priv_dir(),
case erl_ddll:load(PrivDir, atom_to_list(?DRIVER_NAME)) of case erl_ddll:load(PrivDir, atom_to_list(?DRIVER_NAME)) of
ok -> ok ->
io:format(user, "~p", [create_port_cmd(Dbase)]), Port = open_port({spawn, create_port_cmd(DbFile)}, [binary]),
Port = open_port({spawn, create_port_cmd(Dbase)}, [binary]),
{ok, #state{port = Port, ops = Options}}; {ok, #state{port = Port, ops = Options}};
{error, Error} -> {error, Error} ->
Msg = io_lib:format("Error loading ~p: ~p", [?DRIVER_NAME, erl_ddll:format_error(Error)]), Msg = io_lib:format("Error loading ~p: ~p", [?DRIVER_NAME, erl_ddll:format_error(Error)]),
@@ -704,8 +694,8 @@ get_priv_dir() ->
-define(SQL_EXEC_COMMAND, 2). -define(SQL_EXEC_COMMAND, 2).
-define(SQL_CREATE_FUNCTION, 3). -define(SQL_CREATE_FUNCTION, 3).
create_port_cmd(Dbase) -> create_port_cmd(DbFile) ->
atom_to_list(?DRIVER_NAME) ++ " " ++ Dbase. atom_to_list(?DRIVER_NAME) ++ " " ++ DbFile.
do_handle_call_sql_exec(SQL, State) -> do_handle_call_sql_exec(SQL, State) ->
Reply = do_sql_exec(SQL, State), Reply = do_sql_exec(SQL, State),